In this chapter we'll enhance an existing service with the features discussed above. As starting point we take the Hello World example as provided with the E2E Bridge.

Figure: Use Case Diagram of the Original Hello World Example

The example above Hello World example implements a service with two basic operations: The first operation creating and returning a simple object, the second doing the same but taking an input to parameterize the created object.

 Adding Role Based Access Control

Example File (Builder project Advanced Modeling/Security):

<your example path>\Advanced Modeling\Security\uml\interceptorHelloWorld.xml <your example path>\Advanced Modeling\Security\uml\interceptorHelloWorldAdvanced.xml

First, we would like to make the second operation only accessible to users with the role Client. To do so, we simply need to put it into a interceptor model box.
Draw a system boundary around the second operation and give it a name, e.g. Secure Zone.
Assign the stereotype <<InterceptorModel>> to the system boundary so the E2E Bridge recognizes it and treats its contents accordingly. The stereotype <<useCaseModel>> is optional and only documentary.

Figure: Assign Stereotype <<InterceptorModel>>

Assign the stereotype <<ServiceInteraction>> to the use cases and set the associated tagged value operations to point to the actual operation. This is required that the E2E Bridge knows what services to protect with the given security model. It doesn't hurt to set this stereotype and tagged value for all use cases representing exported services.

Figure: Set Tagged Value Operations on Use Case

Finally make sure that the use case bubble is logically inside the system boundary "Secure Zone", and not just graphically in front of it. You can check this in the containment tree. If required, correct it by simply drag & dropping the use case into "Secure Zone" inside the tree.

Figure: Containment Tree Showing Use Case inside Secure Zone

After these steps, the Hello World use case diagram looks like this:

Figure: Final Use Case Diagram with a Protected Operation

Note the icons identifying the system boundary as security model and the use cases as service interactions. If a use case shown behind the system boundary, simply resize the boundary and the use case will reappear, and turn off auto size on it.

Compile the model and deploy it to the Bridge. Now start the debugger and import the model. When testing the two operations you will notice that the operation createSimpleObject does still work as before but calling createSimpleObjectInOut will give the following error:

Figure: Error Message when Accessing Protected Operation

The error is generated because the (anonymous) user executing the request does not have the required role Client. To set the role a pre-processesor has to be defined (see next below).

 Adding Role Using Preprocessor

One (currently the only) way to give the anonymous user access to the protected operation is, by assigning the role "Client" to the Principal object using a preprocessor. In this example we'll simply set the role to a constant value. In a real-world project, this information would set by looking up the Principal name in a user repository (e.g. database, file or LDAP). How to implement this is described in chapter Advanced Security Options.
Take a look at chapter The Principal Object to refresh how the Principal object is structured. The goal of the preprocessor is to add a new Role object to the roles array of the current Principal. The activity diagram of a preprocessor might look like this:

Figure: Activity Diagram of Preprocessor Adding Client Role to Principal

Double-click the Secure Zone system boundary you defined in the use case diagram and define the Preprocessor activity as the mode preprocessor.

Figure: Secure Zone System Boundary in Use Case Diagram

After compiling and deploying the expanded model, the second operation will now work as expected. If you activated all trace information, you can inspect the preprocessing below the UML tab.

 Modifying Output Using Postprocessor

As last step we will use a postprocessor to manipulate the response of the request. The data of incoming requests can be inspected and modified in the same way.
First, we have to create a new Activity Diagram that implements the postprocessor. It consists of three steps:

1. The first output parameter is fetched from the interceptor message.
2. The output parameter value is casted to its static type (SimpleClass).
3. The parameter value is modified by appending the string "postprocessed".

If input parameters had to be changed, the process is analogous, because the parameters attribute of the Interceptor message contains either the input parameters or the output parameters in the preprocessor respectively postprocessor phase.

Figure:  Activity Diagram of Postprocessor Adding "postprocessed" to Output Message

Finally, we have to assign the above activity diagram to the postprocessor tagged value of the interceptor model. Including the preprocessor from the previous chapter, the interceptor model looks like this:

Figure:  Interceptor model having a pre- and postprocessor

Now the example is ready to run. When executed in the debugger, the output will echo the input and append postprocessed to it.
For more advanced features see chapter Advanced Security Options.

 Debugging Pre- and Postprocessors

When starting a service with pre- and/or postprocessor in the E2E Model Debugger with trace enabled, the sequence diagram contains links to inspect the interceptor functions.

Figure:  Sequence Diagram in E2E Model Debugger

The activity diagrams of pre- and postprocessors are regular activity diagrams.