Securing a BPEL process


WS-BPEL 2.0 for SOA Composite Applications with IBM WebSphere 7

WS-BPEL 2.0 for SOA Composite Applications with IBM WebSphere 7

Define, model, implement, and monitor real-world BPEL 2.0 business processes with SOA-powered BPM

  • Develop BPEL and SOA composite solutions with IBM's WebSphere SOA platform
  • Automate business processes with WS-BPEL 2.0 and develop SOA composite applications efficiently
  • Detailed explanation of advanced topics, such as security, transactions, human workflow, dynamic processes, fault handling, and more—enabling you to work smarter



        Read more about this book      

(For more resources on BPEL-Websphere, see here.)

Core concepts

BPEL as a specification does not provide any security concepts that we could leverage. All security aspects are left to the BPEL engine or, in other words, to the BPEL engine wrapper.

In WebSphere, BPEL processes are implemented as SCA components. So for BPEL processes, we can leverage all security constructs that SCA architecture offers. A BPEL process can be secured on an SCA component level so that only authorized users can access it through usage of a security permission qualifier. This qualifier defines that role-specific users must be assigned for accessing a specific SCA component, in our case a BPEL process. Before such a BPEL process is deployed on the server, it is possible to map specific users to the role qualifiers. At runtime, it is possible to dynamically add or remove users to and from this role.

A very common standardized way to expose BPEL process to the outside world is through the use of web services. In WebSphere, every SCA component can be exposed as a web service through a web service export. There are four web service export types supported, depending on the communication protocol (HTTP(S) or JMS), message exchange format (SOAP v1.1 or v1.2), and Java implementation framework (JAX-WS or JAX-RPC).

Web services use SOAP as a message exchange format. SOAP relies on XML. The root element of a SOAP message is a <soap:Envelope> that contains <soap:Header> and <soap:Body>. In the body, there are usually input data for the service operation (payload). Other data (such as credentials, correlation, and others) are contained in the header.

Web services in Java can be implemented with JAX-WS (Java API for XML Web Services) or JAX-RPC (a predecessor of JAX-WS called Java API for XML-based Remote Procedure Call) API. JAX-WS uses annotations introduced in Java SE 5 to make development and deployment of web services and their clients an easier task. JAX-WS is the preferred approach to service development. In WebSphere, JAX-WS supports WS-Policy sets to configure web service behavior in a declarative way.

WS-Policy is a framework for expressing characteristics (like capabilities or requirements) of web services. It uses flexible and extensible constructs. Each policy is a collection of many policy alternatives, each containing policy assertions. Policy assertions are used to express web service characteristics. In WebSphere, specific WS-Policy policies are grouped together in policy sets, each policy set containing one or more WS-Policy policies. The main purpose of using WS-Policy in WebSphere is to specify different web service behaviors, for example, to specify different security aspects. One of the most important security specifications for web services supported in WebSphere is WS-Security.

WS-Security (WSS) is a specification for delivering end-to-end security for web services. It provides extension to SOAP (to 1.1 and 1.2 versions) for assuring message content integrity and confidentiality. WS-Security supports a variety of security models such as PKI, Kerberos, and SSL. Moreover, WS-Security supports multiple security token formats (username token, binary security token, XML token, and EncryptedData token), trusted domains, signature formats and algorithms (Exclusive XML Canonicalization, SOAP Message Normalization), and encryption technologies (symmetric and asymmetric).

A WSS username token contains a username and is extensible to include possible authentication data, such as a password and additional data to increase security like a nonce (unique identifier to prevent replay attacks) or timestamp (to prevent replay attacks by leveraging message expiration methods). A WSS binary security token provides only one XML element which contains binary data (for example, X.509 certificate or Kerberos ticket). An XML token is an abstract token that is concretized into WSS subsequent specifications. One of the tokens is an SAML token (Security Assertion Markup Language), which is used for exchanging authentication and authorization data between different security domains (identity providers and service providers). An EncryptedData token is an encrypted version of any token contained in a WSS header to provide token confidentiality.

Securing a BPEL process

We will explain how to secure a BPEL process with an example. We will expose the BPEL process as a web service. This way, a client will be able to call it in a standardized way. Next, we will create a new WS-Policy set that will require the client to provide a WS-Security header with UsernameToken containing the username and password for user authentication. We will attach this WS-Policy set to our BPEL process's web service export to protect the process. Only authenticated users will have access to the BPEL process. We will then test the example, with and without providing credentials, to see if security is working. Next, we will see that authentication information (user's identity) is not automatically propagated to the BPEL process. So, the process does not know which user called it. We will extract a user's identity from UsernameToken and propagate this identity to the BPEL process. Through another round of testing, we will see that the user who called the process will become the process instance owner. The final step in this example will be to configure the BPEL process in a way that only authenticated users, who are authorized, will be able to call it. To achieve this, we will have to define the security permission qualifier on our BPEL process, define a role that will have access to our BPEL process, and map users to this role to actually allow specific users to access our BPEL process. Later on, we will be able to add or remove users from the role to enable runtime access permission update for specific users.

Exposing a BPEL process as web service

We will expose a BPEL process as a web service with the help of the following steps:

  1. Let us take the Travel Approval BPEL process and open it in the WebSphere Integration Developer. The Travel Approval process is an SCA component with an interface. The Travel Approval process and surrounding components are shown in the assembly diagram represented in the following screenshot:

    Securing a BPEL process

    The Travel Approval process sends an e-mail to confirm the reservation. You can download the sample from The sample can be deployed to the IBM WebSphere Process Server using the IBM WebSphere Integration Developer.

  2. We can expose this process as a web service by generating a web service export. We can generate the web service export by right-clicking on the TravelApproval process and selecting Generate Export... and then Web Service Binding from the context menu, as shown in the following screenshot:

    Securing a BPEL process

  3. The Travel Approval process implements more than one interface, so a dialog asks us which interface to expose. We should select the interface that is used to run the process, that is, the TravelApprovalPT interface, as shown in the following screenshot:

    Securing a BPEL process

  4. Next, we have to select the transport protocol. There are four options as we can see in the following image. The first two are using the HTTP protocol with JAX-WS as the implementation framework and the SOAP protocol of versions 1.1 and 1.2 respectively (the name Simple Object Access Protocol behind the SOAP abbreviation was dropped in version 1.2). SOAP 1.2 brings several advancements over SOAP 1.1. For example, it assures better interoperability, better support standards like XML Information Set (a set of definitions for use in other specifications), is truly protocol independent, and has better and more formalized extensibility. The third option uses JAX-RPC as the implementation framework for SOAP 1.1. The last option doesn't use HTTP as the transport protocol but instead uses JMS (Java Message Service).

    We will use WS-Policy to define authentication rules, so we need the WSPolicy support that is offered only with JAX-WS binding. We will choose usage of SOAP messages of version 1.2, that is, SOAP1.2/HTTP, as the latest standard, as shown in the following screenshot. Alternatively, we could also use SOAP 1.1 with JAX-WS.

    Securing a BPEL process

  5. At this point, we need to save our assembly diagram, because we will rename the newly generated export to have a more descriptive name. We will use the refactoring option for renaming SCA components, imports, and exports. Refactoring is enabled by right-clicking on our newly created web service export, TravelApprovalPTExport1 | Refactor... | Rename, as shown in the following screenshot:

    Securing a BPEL process

  6. We choose TravelApprovalWS as the new name for the export and click on Refactor:

    Securing a BPEL process

  7. When we created the web service export, WebSphere Integration Developer generated the following artifacts:
    • Web service binding TravelApprovalWS_TravelApprovalPTHttpBinding in namespace
    • A service called TravelApprovalWS_TravelApprovalPTHttpService with port TravelApprovalWS_TravelApprovalPTHttpPort and endpoint address http://localhost:9080/SecuringBPELWeb/sca/TravelApprovalWS

    Note that the endpoint address can change when the web service is deployed on another server. We can see all these details if we select our web service export in the assembly diagram and bring up its properties by clicking on Properties | Binding:

    Securing a BPEL process

  8. All these details are actually defined in the WSDL file that was generated in our SecuringBPEL_lib library, which contains data types and interfaces. We can find the TravelApprovalWS_TravelApprovalPTHttpPort WSDL file under Web Service Ports in SecuringBPEL_lib, as shown in the following screenshot:

    Securing a BPEL process

  9. When we open this WSDL file, we can see all the content we described earlier (binding, service, port, address). Notice that the <wsdl:import> element imports the actual (abstract) interface from TravelApprovalPT.wsdl:

    (Move the mouse over the image to enlarge.)

In this section, we have created a web service export for our BPEL process and examined the details that occurred behind the scenes.

        Read more about this book      

(For more resources on BPEL-Websphere, see here.)

Creating a WS-Policy set for WS-Security authentication

In this section, we will create a WS-Policy set on WebSphere Application Server through its console. The WS-Policy set will demand WS-Security UsernameToken to be present in the incoming SOAP Header. We will configure UsernameToken to be consumed, and credentials from it authenticated by the WAS users repository to determine if the caller is authentic and can call our TravelApproval BPEL business process.

We will achieve the described level of security by completing the following steps:

  1. First, we will define a security token that will be consumed at the service. There are UsernameToken, X.509 certificates, LTPA tokens, and Custom tokens available, as shown in the following screenshot. X.509 certificates require that the client send a certificate when invoking the process. An LTPA (Lightweight Third-Party Authentication) token is an IBM-specific token. It allows users to reuse their login credentials across physical servers. A Custom token can be defined to cover some specific requirements. We will use the UsernameToken in our example, because it is the most straightforward to use. Using other tokens is very similar to using UsernameToken, but it requires some additional work on the client side, where the client has to provide additional information (X.509 certificate, for example)

    Securing a BPEL process

  2. Next, we need to make sure that the Universal Test Environment (the WebSphere Application Server instance optimized for the development) is running. Check the Servers view in the WebSphere Integration Developer and if the server is in the state Stopped, run it by right-clicking on it and selecting Start:

  3. After the server is started, open Integrated Solutions Console (enter https://HOSTNAME(localhost):PORT(9043)/ibm/console in the browser or right-click on started server and from the menu select Administration | Run administrative console). Log in as administrator (the default administrator has username admin and password admin). In the console expand Services | Policy sets | Application policy sets:

    Securing a BPEL process

  4. A list of predefined policy sets appears. We will not use a predefined policy set. Rather we will create a new policy set. Click on New… to create a new policy set, as shown in the following screenshot:

  5. To complete the creation of a new policy set, we have to specify its name and optional description. Then we have to add some policies. In our case, we will add only one policy (WS-Security) with one token definition (WS-Security UsernameToken). We will enter WSS UsernameToken only for the Name and Policy that requires client to use WS-Security UsernameToken with proper credentials to access the web service for the Description. Click on Add | WS-Security:

  6. Optionally, we can define intents for each policy that are meant for descriptive (natural language) demands that a policy defines. Enter them in the Intents Satisfied field as shown in the following screenshot (enter Require WS-Security UsernameToken into the text box) and click on Apply.

  7. WS-Security is one of the policies in the policy set configuration. Each policy contains a security policy for communication with the service and the bootstrap policy for communication with the trusted service. Secure conversation bootstrap policy is used for the service consumer to acquire a security token for secure conversation from the trust service. This is achieved using a token issuing a WS-SecureConversation or WS-Trust protocol message. We can find both types of policies if we select WS-Security in the Policies list. The communication policy is called Main policy and the bootstrap policy is called Secure conversation bootstrap policy. In our case, the bootstrap policy is disabled and will remain so, because we have not defined any secure/trust requirements in the Main policy. We will not define them, because this is out of the scope of this example.

  8. Now, we will set all the details needed for the WS-Security policy to require that the client provides the UsernameToken. If we select Main policy, we can see all available settings that concern WS-Security. By default, Message level protection with asymmetric tokens is enabled. This option is for using digital signatures and encryption. Details are defined in Policy Details section.
  9. The Require signature confirmation option specifies whether in the response message there should be a signature confirmation token. The WS-Security v1.1 specification defines the XML element <wsse11:SignatureConfirmation wsu:Id="…" Value="…" />, which tells the client what happened when the service checked the request message signature. The Value attribute is important, because it contains the <ds:SignatureValue> value from the request message. If so, the request was processed as expected. On the other hand, if this attribute is not present, this tells the client that the received response is based on a request that was not signed. If the element is present but empty, this means that something went wrong and the client should proceed accordingly.
  10. Under Request message part protection and Response message part protection, we can define parts of request and response messages that should be encrypted and signed. We define this with XPath expressions.
  11. Under Key Symmetry, we can choose between symmetric and asymmetric tokens for encryption and signing. After we have chosen the appropriate tokens, we can define all the details for the selected tokens to function properly. Under Policy Details | Algorithms for asymmetric tokens, additional properties for asymmetric encryption are offered.
  12. Security header layout offers four options for elements ordering in the WS-Security header. A Strict layout means that any usage of other header elements (element referencing) must be preceded with a referenced element declaration. Layout (Lax) allows the order of contents in the header to vary as long as the header elements are defined within the restrictions specified in the WS-Security specification. Lax but timestamp required first in header and Lax but timestamp required last in header also pose no additional restrictions except on the position of the <wsu:Created> element that contains a timestamp when the message was created (first or last element in the header).
  13. For our example, we will not use message-level protection, so we will uncheck the checkbox next to Message level protection and click on Apply. The result should be as shown in the following screenshot:

  14. However, we will use UsernameToken. So, we have to define its usage in the request message. We will select Request token policies under Policy Details (we would choose Response token policies if UsernameToken would be required in the response message). We open the Add Token Type drop-down menu and select UserName:

  15. To define the UsernameToken usage, we have to specify its name and select its version. For the name, we will enter authentication_token and select WS-Security 1.0. We will use the WS-Security 1.0 specification in this example, as it defines all the necessary elements and is supported in more web service frameworks than the newer v1.1. We could have chosen WS-Security 1.1 without any major differences for the rest of the example.

  16. We should now save changes to the master configuration by clicking on Save:

We have created a WS-Policy set that demands WS-Security UsernameToken to be present in the incoming SOAP Header. UsernameToken holds user credentials through which users are authenticated on the server. All authenticated users are then allowed to access the TravelApproval BPEL business process. All unauthenticated users cannot access the process any more.

Securing a BPEL process web service export with a WS-policy set

We have finished configuring the WS-Security policy set. Now, we will export it and import it into WebSphere Integration Developer to include it into the assembly diagram. In this way, we will be able to tell the server to apply the selected policy set on our BPEL process web service export. To use the configured WS-Security policy set on the process web service export, we have to perform the following steps:

  1. First, let us export the policy set. On Application policy sets, click the checkbox next to WSS UsernameToken only policy set, and click on Export…:

  2. A dialog with a link to a ZIP file opens. Click on the link (or right-click and select Save as …) to download the file to a local disk:

    Securing a BPEL process

  3. Next, we have to import the policy definitions to WebSphere Integration Developer. We will select WebSphere Policy Sets and click on Next:

    Securing a BPEL process

  4. Then we will select the ZIP file that we have created in the previous step. The policy set called WSS UsernameToken only is already selected for us to import. We will click on Finish:

    Securing a BPEL process

  5. Now, we can check if the policy set has been imported properly. To do that, we have to go to the Window | Preferences menu. Select Service Policies in the navigation tree and expand WebSphere Policy Sets | WebSphere v7.0 Policy Sets. There we should see the WSS UsernameToken only policy listed. If we select it, we can see its details (description):

  6. The policy set was successfully imported. To use it in the Assembly Diagram editor, we have to restart WebSphere Integration Developer.
  7. All that is left here is to apply the imported policy set to our web service export. We will open the assembly diagram of our example. We will select the TravelApprovalWS web service export. In the Properties view, we will select the Policy Sets tab and in the Default policy set: drop-down menu, we select the WSS UsernameToken only policy:

    Securing a BPEL process

  8. The last step is to save the changes made to the assembly diagram.

We have successfully defined that the TravelApprovalWS export uses the policy called WSS UsernameToken only. This way, we secured our process through its web service export. We managed to do that by exporting the WSS UsernameToken only policy set from the WebSphere Application Server console and importing it to the WebSphere Integration Developer. The policy set is defined on the server and referenced from our BPEL process module. This way, it is possible to reuse and modify the policy set during runtime.

Testing a secured BPEL process

To test the secured BPEL process, we will deploy our solution on the server, locate the web service endpoint, create a test project, and then test the BPEL process through the web service export. First, we will try to invoke the BPEL process without providing credentials. Then we will invoke it with UsernameToken credentials.

  1. First, we will deploy the solution to the server. Open Add and Remove Projects from the server context menu. Select SecuringBPELApp and click on Add. By default, If server is started, publish changes immediately is selected and, in this case, our example will be automatically published on the server. Otherwise, please select this checkbox. Click on Finish.

    Securing a BPEL process

  2. To test the service, we need to locate the TravelApprovalWS web service endpoint. We will use a free tool, soapUI, to test our service. We can download soapUI from
  3. To locate the web service endpoint, we will select the export in the assembly diagram and in the Properties | Binding tab and copy the Address: field to the clipboard:

    Securing a BPEL process

  4. We can access the WSDL definition of our web service. This is the best way to create a test project in soapUI. We will paste the URL to the web browser address bar and add a ?wsdl string at the end of the HTTP query string:

    Securing a BPEL process

  5. This way, the browser will redirect us to the absolute path of the WSDL file of our service. We need this address for the soapUI tool to call our BPEL process.
  6. We are ready to create a test project in the soapUI. We will open the soapUI tool and create a new soapUI project with the WSDL URL we just located. In soapUI, we will select File | New soapUI Project:

    Securing a BPEL process

  7. To create the test project, we have to provide its name and WSDL location. For the Project Name, we will enter TravelApprovalWS, and in the Initial WSDL/WADL field, we will paste the WSDL URL from the clipboard. Leave other settings as they are and click on OK:

    Securing a BPEL process

Thus, we have created a test project with a sample request to send to our BPEL process.

Calling a BPEL process without credentials

First, we will try to call our BPEL process without specifying any credentials. This way we will see if the defined security mechanism through the WS-Policy definition works. We will test the security mechanism with the help of the following steps:

  1. In the Project tree, we will expand the TravelApprovalWS project until we find the Request 1 SOAP request leaf:

    Securing a BPEL process

  2. Double-clicking on Request 1 will bring up the skeleton of the SOAP request that soapUI generated from the WSDL file. We can safely delete lines with comments stating that some elements are optional (all lines with <!--Optional:-->). Now try calling the BPEL process with an empty request by clicking the green triangle () in the top-left corner of the screen.

    Securing a BPEL process

  3. We should get the following error:
    Error message: A security token whose type is [http://docs.oasisopen.
    1.0#UsernameToken] is required.

We can see that we have secured the BPEL process. We cannot invoke it without security credentials. In the next section, we will provide security credentials in the request.

Calling a BPEL process with credentials

Next, let us specify the credentials in the request and rerun the test by performing the following steps:

  1. We will create a UsernameToken containing a username and password for authentication. We will enter the username and the password in the Request Properties view. We will use the default administrator username admin and password admin:

    Securing a BPEL process

  2. Now, we will add the WS-Security UsernameToken to the request by right-clicking on the request content and selecting Add WSS Username Token:

    Securing a BPEL process

  3. UsernameToken supports two types of passwords:
    • PasswordText: Plain text password
    • PasswordDigest: Base-64 SHA-1 hash value of the UTF-8 or equivalent encoded password

    The WS-Security specification states that the password digest offers no additional security over the plain text password without using secured transport protocol (such as HTTPS). This is one of the reasons why WebSphere Application Server does not support PasswordDigest. The other reason is that most advanced identity repositories (such as LDAP) use their own encryption/digest algorithms for passwords and many times it is impossible to get a password from the identity repository to create SHA-1 hash and do the comparison between hash from the identity repository and hash in the UsernameToken for authentication. So, we will choose the plain text PasswordText and click on OK, as shown in the following image.

    Securing a BPEL process

    The wsse:Security header containing UsernameToken with username, password, nonce, and timestamp is inserted. We already mentioned timestamp earlier in this chapter. wsse:Nonce, on the other hand, might be new for us. It is a unique identifier in the request message to prevent replay attacks. See the next image for a nonce example.

  4. Now, let us insert some test data into our request. Let us do that, because in the next step we will call our BPEL process with proper credentials and the BPEL process will not work correctly without the data specified.

  5. If we try to run our BPEL process, we will see that it starts. We can see a new process instance in the Business Process Choreographer (https://HOSTNAME(localhost):PORT(9443)/bpc, or right-click on the server in the Server view and select Launch | Business Process Choreographer Explorer). We can locate one process instance of the TravelApproval process in the Process Instances | Administrated by me view.
  6. If we click on that process instance, we can see its details. Be aware of Starter and Administrators properties where it states UNAUTHENTICATED. This is because so far we only authenticated the client when receiving the request message on the export. We have not propagated the client user identity to the BPEL process.

To propagate the user identity to the BPEL process, we have to define the Caller on the web service export. Caller definition ensures that successfully authenticated user identity is propagated to the succeeding service components within an assembly.


In this article, we have become familiar with the principles of securing BPEL processes. We have learned how to protect a BPEL process and how to achieve that it can be accessed by authenticated users only. We have demonstrated how to limit the access to the BPEL process to only those authenticated users that are also authorized to have access to the process.

In the next article, Authorizing User Access to BPEL Process, we will see how we can authorise user access to a BPEL process.

Further resources on this subject:

You've been reading an excerpt of:

WS-BPEL 2.0 for SOA Composite Applications with IBM WebSphere 7

Explore Title