1 Oracle BPEL Process Manager Security

1.1.1 WS-Security

WS-Security provides a mechanism for adding three levels of security to simple object access protocol (SOAP) messages. These security levels are as follows:

• Authentication tokens – Used for passing user name and password information, as well as X.509 certificates, within the SOAP message headers.

• XML encryption – Used for message confidentiality.

• XML digital signatures – Used for message integrity, source and origin validation, and nonrepudiation.

1.1.2 Authentication

Authentication is the process of proving the identity of a user. Oracle BPEL Process Manager supports basic authentication (HTTP), certificate-based authentication (HTTP/S), and native BPEL security extension authentication.

1.1.3 Authorization

Authorization is the evaluation of security constraints to send a message or make a request. Authorization uses specific criteria to determine whether to permit the request. The criteria are authentication and restriction. Oracle BPEL Process Manager has no current native support for inbound authorization. Oracle Web Services Manager can instead be used to provide this capability.

1.1.4 Encryption and Decryption

Encryption is the practice of encoding (encrypting) data in such a way that only an intended recipient can decode (decrypt) and read the data. Oracle BPEL Process Manager has no current native support for XML encryption. Oracle Web Services Manager can instead be used to provide this capability.

1.1.5 Secure Socket Layer

Secure Socket Layer (SSL) is a standard for the secure transmission of documents over the Internet using HTTP/S (secure HTTP). SSL uses digital signatures to prevent data from being compromised.

1.1.6 Digital Signatures for Integrity and Nonrepudiation

A digital signature is a code attached to an electronic document that reliably identifies the author or sender, and verifies that the document has not been compromised. Oracle BPEL Process Manager has no current native support for digital signatures. Oracle Web Services Manager can instead be used to provide digital signatures and signature verification capabilities.

1.1.7 BPEL Security Extensions

BPEL security extensions are fully integrated into Oracle BPEL Process Manager.

Regardless of which channel you use to invoke a process (such as HTTP, SOAP, Java API, and so on), the same security constraints apply. However, the way credentials are passed differs amongst channels.

BPEL security extensions are intended for BPEL developers who want to enhance the security of Oracle BPEL Process Manager. These extensions are technical and require a good understanding of Oracle BPEL Server, including the various technologies used for invoking processes (for example, SOAP and HTTP). There are also many references to the Oracle BPEL Java API, so a good knowledge of Java is required.

Oracle BPEL Process Manager's API includes BPEL security extensions that enable developers to create custom security. This is necessary in secure environments where users must be authenticated and authorized to use certain BPEL processes.

1.2.1 Using SSL for Certificate-Based Authentication

BPEL processes are usually invoked using SOAP over HTTP. While basic authentication ensures that only authenticated users access BPEL processes, user names and password are prone to identification by network packet sniffers. Therefore, the need exists for securing the network connection through use of HTTP/S instead of HTTP. If you use HTTP/S as the authentication schema, both the client and server can be configured to exchange certificates. A successful SSL handshake confirms authentication.

The following types of certification authentication can be used:

• Server certificate authentication

  In this scenario, the client asks the server for the certificate and authenticates the trustworthiness of the server. The client does not present its certificate unless it is requested by the server to do so. The type of server presenting the certificate is based upon the Oracle BPEL Process Manager installation type you are using:

  • For Oracle BPEL Process Manager for OracleAS Middle Tier, the server is Oracle Application Server (and its version of OC4J)

  • For Oracle BPEL Process Manager for Developers, the server is the standalone OC4J in which Oracle BPEL Process Manager is deployed.

• Server and client certificate authentication

  In this scenario, both the client and server exchange certificates and a successful SSL handshake confirms authentication. This is called client authentication mode. The server (either the standalone OC4J in which Oracle BPEL Process Manager is deployed or Oracle Application Server (and its version of OC4J)) must be configured to request the client's certificate during the SSL handshake and authenticate the trustworthiness of the client. In the context of securing BPEL processes, this means that a client invoking a service presents a valid certificate issued by a mutually-trusted certificate authority. Server and client certificate authentication is not as frequently used.

The following sections describe the SSL configuration method to use based on the Oracle BPEL Process Manager installation type you are using:

• Oracle BPEL Process Manager for OracleAS Middle Tier

• Oracle BPEL Process Manager for Developers

1.2.2 Using J2EE Basic Authentication

J2EE basic authentication involves authentication through unsigned tokens, namely a user name and password.

Table 1-1 describes the supported features of this method.

The following sections describe the configuration method to use based on the Oracle BPEL Process Manager installation type:

• Oracle BPEL Process Manager for OracleAS Middle Tier

• Oracle BPEL Process Manager for Developers

1.2.3 Using the Native BPEL Security Extensions

Native BPEL security extensions code can also handle authentication. (See Figure 1-2.) The following steps describe this process.

1. Oracle HTTP Server receives a service request.

2. Oracle HTTP Server forwards the request, part of which is intercepted by Oracle BPEL Process Manager.

3. The BPEL security extension code of Oracle BPEL Process Manager validates the message received against the configured identity service user repository:

   • OID

   • JAZN XML

   • Custom JAAS plug-in

4. If the user name and password are authenticated, Oracle BPEL Server services the request.

Table 1-2 describes the supported features of this method.

This section contains the following topics:

• Domain and Process Level Security

• Java API

• HTTP Binding

• SOAP over HTTP Binding

secured = username
username = password

secured = Clemens
Clemens = pwForClemens

secured = Clemens

<wsse:Security soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" 
               soapenv:mustUnderstand="1" 
               xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
                  wss-wssecurity-secext-1.0.xsd" 
               xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
                  <wsse:UsernameToken
               xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
                  wss-wssecurity-utility-1.0.xsd"><wsse:Username>Clemens
                     </wsse:Username><wsse:Password Type=
                        "http://docs.oasis-open.org/wss/2004/01/oasis-200401-
                         wss-username-token-profile-1.0#PasswordText">pwForClemens
                        </wsse:Password>
                    </wsse:UsernameToken>
</wsse:Security>

/**
   * Create a WSSecurity compliant token from username and password -
 UsernameToken!!
   * @throws javax.xml.soap.SOAPException in case the element cannot be
 constructed
   * @return the headerElement needed for the header of the call
   * @param pCredential the credential
   * @param pUsername the username
   */
  public static SOAPHeaderElement createWSSecurityHeader (String pUsername,
                                                          String pCredential)

public static SOAPHeaderElement createOASISWSSecurityHeader
       (String pUsername,
        String pCredential,
        boolean pIsWSPolicyCompliant) throws SOAPException
  {

1.3.1 Using SSL for Certificate-Based Authentication

If a partner exposes an HTTP/S-based service, the WSDL of that service contains the information in the service binding. You can invoke services from Oracle BPEL Process Manager that have a SOAP or HTTP binding.

Oracle BPEL Process Manager support for SSL is Java Secure Socket Extension (JSSE)-standards based and relies on the default SunJSSE provider for cryptographic services. For configuring the keystore and truststore, Oracle BPEL Process Manager relies on standard JSSE keytool and JSSE mechanisms. (See Figure 1-3.)

The following types of certification authentication can be used:

• Server certificate authentication

  During the SSL handshake process, Oracle BPEL Process Manager, which acts as a client to the secured service of the partner link server, is required to verify the trustworthiness of the partner link (server authentication). Verifying the certificate presented by the partner link server satisfies this requirement. To do this, the default SunJSEE functionality is used by Oracle BPEL Process Manager and the truststore used in the process must contain the appropriate certificate entries. If the partner link server uses a self-signed certificate, this certificate must be placed as a trusted entry in the truststore. If the partner link server presents a certificate chain, then the root certificate of that chain must be part of the truststore.

• Server and client certificate authentication

  During the handshaking process, a partner link server can sometimes require that the client (in this scenario, Oracle BPEL Process Manager) present its certificate for verification. This is called client authentication mode. For these situations, you must also set up a certificate for Oracle BPEL Process Manager. The certificate can be self-signed or provided by a certificate authority. The keytool can be used to save that certificate and keys in the keystore and truststore.

  Note that it is not possible to know from the WSDL of the service if the partner link service requires this. This requirement is not in wide practice.

It is beneficial to set up a truststore in which trusted certificate entries are placed. This is different from the keystore, in which private and public key entries are present.

The default keystore and truststore files located in the jre\lib\security directory for your JDK installation are used:

• The cacerts file is the default keystore

• The jssecacerts file (if present) is the truststore file. If jssecacerts is not present, cacerts also serves as the truststore.

Keystore and truststore files are created and managed with JDK's keytool. This tool is useful for performing operations such as the following:

• Creating new keystores and truststores

• Reading and listing information present in the stores

• Updating and deleting existing entries in keystores and truststore

1.3.2 WS-Security-Compliant Services

If a partner link expects WS-Security-compliant authentication tokens, BPEL can be configured to invoke the partner link with these. (See Figure 1-3.) Table 1-3 shows the relevant properties. These properties are configurable at the individual partner link level.

<partnerLinkBindings>
  <partnerLinkBinding name="client">
    <property name="wsdlLocation">CreditRatingService.wsdl</property>
  </partnerLinkBinding>
</partnerLinkBindings>

<property name="wsseHeaders">propagate</property>

<property name="basicHeaders">propagate</property>

<property name="wsseHeaders">credentials</property>
<property name="wsseUsername">your_user</property>
<property name="wssePassword">your_password</property>

<property name="basicHeaders">credentials</property>
<property name="basicUsername">your_user</property>
<property name="basicPassword">your_password</property>

<property name="wsseOASIS2004Compliant">true</property>

1.3.3 Axis Services with Custom Authentication Handlers

Table 1-4 shows the configurable properties at the partner link level for Axis services.

1.3.4 J2EE Basic Authentication Protected Services (HTTP)

This section describes HTTP basic authentication.

The section contains the following topics:

• HTTP Basic Authentication (10.1.2.0.2)

• HTTP Binding (10.1.3)

<property name="httpBasicHeaders">credentials</property>

<property name="httpBasicUsername">your_username</property>
<property name="httpBasicPassword">your_password</property>

<property name="httpBasicHeaders">propagate</property>

1.3.5 Java and EJB Binding (10.1.3)

Starting with Oracle BPEL Process Manager release 10.1.3, partner link properties can be propagated into the implementing class or EJB by implementing this interface:

com.oracle.bpel.client.wsif.IjavaEjbPlnkBindingInfo

It contains the following method:

/**
 * This method will be called immediately after the new instance
 * of the class/bean has been created
 * 
 * @param pProperties the map containing name/value pairs
 */
public void setPlnkProperties(HashMap pProperties);

This method is called directly after the class or bean has been created, and the map contains all partner link properties.

1.4.1 Example 1: Creating New Users and Groups to Access New BPEL Domains

This section describes how to create a new user and group to access a new BPEL domain. In this example, you use Oracle Internet Directory to create the user and group and the OracleAS JAAS Provider Admintool of the XML-based JAZN provider to grant the necessary domain permissions to the new user and group. The management tool to use to create the user and group is based on the type of identity service provider you are using.

1. Configure the 10.1.3.1.0 identity service with 10.1.2 Oracle Internet Directory as described in "Configuring Identity Service 10.1.3.1.0 with 10.1.2 Oracle Internet Directory".

2. Create a new domain in the Oracle BPEL Admin Console named soaAdmin.

3. Create a new user named soaAdmin and group named BPMsoaAdminDomainAdmin in Oracle Internet Directory.

4. Use the JAZN Admin tool to grant domain permissions to user soaAdmin or group BPMsoaAdminDomainAdmin:

   java -Xbootclasspath/a:/home/oc4j/bpel/lib/orabpel-boot.jar -jar jazn.jar
   -shell -grantperm jazn.com -user soaAdmin com.collaxa.security.DomainPermission
   soaAdmin all
   
   

   or

   java -Xbootclasspath/a:/home/oc4j/bpel/lib/orabpel-boot.jar -jar jazn.jar
   -shell -grantperm jazn.com -role BPMsoaAdminDomainAdmin
   com.collaxa.security.DomainPermission soaAdmin all
   
   

   where:

   • com.collaxa.security.DomainPermission — Is the name of the permission class. This permission class does not provide access to Oracle BPEL Admin Console.

   • soaAdmin — Is a parameter to the permission class. This parameter indicates the name of the domain to which the user has access.

   • all — Is a parameter to the permission class. This parameter indicates the level of actions the user or group can perform.

   Note:

   The user soaAdmin or group BPMsoaAdminDomainAdmin receives either all or no privileges in the soaAdmin domain. You cannot assign specific actions to a user or group, such as specifying read-only permissions, update permissions, and so on.

5. Log into Oracle BPEL Control.

1.4.2 Example 2: Creating a New User to Access the Default BPEL Domain

This section describes how to create a new user to access the default BPEL domain automatically included with Oracle BPEL Process Manager. In this example, you use the OracleAS JAAS Provider Admintool to create a user and grant the BPMDefaultDomainAdmin role to the user. The management tool to use to create the user is based on the type of identity service provider you are using.

1. Create a user named mike in realm jazn.com with a password of welcome.

   % java -Xbootclasspath/a:/home/oc4j/bpel/lib/orabpel-boot.jar -jar jazn.jar
    -shell -adduser jazn.com mike welcome
   
   

2. Grant the role BPMDefaultDomainAdmin to user mike in realm jazn.com.

   % java -Xbootclasspath/a:/home/oc4j/bpel/lib/orabpel-boot.jar -jar jazn.jar
    -shell -grantrole BPMDefaultDomainAdmin jazn.com mike
   
   

3. Log into Oracle BPEL Control.

1.4.3 Example 3: Creating a New User to Access All BPEL Domains

This section describes how to create a new user to access all BPEL domains. In this example, you use the OracleAS JAAS Provider Admintool to create a user and grant the BPMSystemAdmin role to the user. The management tool to use to create the user is based on the type of identity service provider you are using. This user also receives the com.collaxa.security.ServerPermission permission. This permission provides access to all domains and to Oracle BPEL Admin Console. This permission also automatically includes the default (com.collaxa.security.DomainPermission) permission.

1. Create a user named mike in realm jazn.com with a password of welcome.

   % java -Xbootclasspath/a:/home/oc4j/bpel/lib/orabpel-boot.jar -jar jazn.jar
    -shell -adduser jazn.com mike welcome
   
   

2. Grant the role BPMSystemAdmin to user mike in realm jazn.com.

   % java -Xbootclasspath/a:/home/oc4j/bpel/lib/orabpel-boot.jar -jar jazn.jar
    -shell -grantrole BPMSystemAdmin jazn.com mike
   
   

3. Log into Oracle BPEL Control.

1.5.1 Using the Default Validator

Oracle BPEL Process Manager provides a bridge to your identity store through the BPEL Identity Service. For example, in Oracle Application Server you can use JAZN, Oracle Internet Directory (OID), or a custom repository plug-in as your identity store.

If you want to invoke a BPEL process, your user name must be in the configured store, or, in the case of JAZN, created in SOA_Oracle_Home\j2ee\home\config\system-jazn-data.xml (for the Oracle BPEL Process Manager for OracleAS Middle Tier installation type). For example:

<user>
   <name>Clemens</name>
   <credentials>!yourpassword</credentials>
</user>

BPEL security validation is evaluated in the following order:

• If the BPEL suitcase contains the credentials within the configurations tag in bpel.xml. For example:

  <property name="user">Clemens</property> 
  <property name="pw">your_password</property> 
  
  

• If a role is specified in the BPEL suitcase, the user specified in the request must exist in the identity management store and must belong to that group.

  <property name="role">administrators</property>
  
  

  This method is useful when many processes are used and identity management cannot be reconfigured with a new role for each process.

• If neither of the security validators described above are found, BPEL concatenates the process name and ExecutionRole and expects the supplied user to belong to a role of that name. For example, if user Clemens invokes the CreditRatingService process, he must belong to a group named CreditRatingServiceExecutionRole as defined in your identity store (for example, system-jazn-data.xml if you are using JAZN):

  <role>
     <name>CreditRatingServiceExecutionRole</name>
        <members>
           <member>
              <type>user</type>
              <name>Clemens</name>
           </member>
         </members>
  </role>
  

1.5.2 Creating a Custom Validator

It is sometimes necessary to implement a custom validator when the default does not meet your requirements. To accomplish this, the following interface must be implemented and the message handler reconfigured.

/**
 * This source is proprietary to ORACLE CORPORATION
 * 2005, All rights reserved
 */
package com.oracle.bpel.security;

import com.oracle.bpel.client.ServerException;

import com.oracle.bpel.client.NormalizedMessage;
import com.oracle.bpel.client.BPELProcessId;

/**
 * Public abstract class that has to be implemented 
 * for having a valid ACLManager that is used by the BPEL server
 * for authentication & authorization
 * 
 * @version 1.1
 */
public abstract class ACLManager extends BaseACLManager {
  
  /**
   * Public constructor that should use a cache for connections
   * and care about other stuff. 
   * @throws com.oracle.bpel.client.ServerException
   * @since 1.0
   */
  public ACLManager() throws ServerException 
  {
  }
 
  /**
   * Checks if a user is valid in the context of a secured Process
   *  
   * @return valid or not 
   * @param pMessage the message will hold all information, including
   * the domain information and headers
   * @throws ServerException in case something breaks
   */
  public abstract boolean validateUser 
     (BPELProcessId pProcessID, NormalizedMessage pMessage) throws
        ServerException;
 
  /**
   * Checks if a user is allowed to execute (=invoke) a certain revision
   * (if given) of a process.
   * 
   * @return true if he is otherwise false
   * @param pProcessId the name, domain and revision of the process
   * @param pMessage the message will hold all information, including
   * the domain information and headers
   * @throws ServerException in case something breaks
   */
  public abstract boolean isAllowedToExecuteProcess 
   (BPELProcessId pProcessID, NormalizedMessage pMessage)
      throws ServerException; 

  /**
   * Checks if a user is allowed to execute (=invoke) a certain activity
   * of a process.
   * 
   * @return true if he is otherwise false
   * @param pProcessId the name, domain and revision of the process
   * @param pActivityName the name of the Activity
   * @param pMessage the message will hold all information, including
   * the domain information and headers
   * @throws ServerException in case something breaks
   */
  public abstract boolean isAllowedToExecuteActivity 
     (BPELProcessId pProcessID, NormalizedMessage pMessage, String  pActivityName)
         throws ServerException;

  /**
   * Checks if a user is allowed to lookup  a certain revision
   * (if given) of a process.
   * 
   * @return true if he is otherwise false
   * @param pMessage the message will hold all information, including
   * the domain information and headers
   * @param pProcessId the name, domain and revision of the process
   * @throws ServerException in case something breaks
   */
  public abstract boolean isAllowedToLookupProcess 
     (BPELProcessId pProcessID, NormalizedMessage pMessage)
         throws ServerException;

  /**
   * Checks if a user is allowed to lookup a certain activity of a process.
   * 
   * @return true if he is otherwise false
   * @param pActivityName the name of the Activity
   * @param pProcessId the name, domain and revision of the process
   * @throws ServerException in case something breaks
   */
  public abstract boolean isAllowedToLookupActivity 
     (BPELProcessId pProcessID, NormalizedMessage pMessage, String  pActivityName)
         throws ServerException;
         
}  

After implementation, the class must reside in SOA_Oracle_Home\bpel\system\classes to be reached by the class loader. The second step is to reconfigure the following property in message-handlers.xml:

<property id="ACLManager">
<value>com.oracle.bpel.security.validator.bpmid.BPMIdentityValidator</value>
   <comment>BPMIdentityValidator uses the server configured security such
      as JAAS to validate the user against
   </comment>
</property>

where value must point to the classname (including the package) of the implemented validator class.

1.7.1 Authorization

Outbound authorization in the context of BPEL invoking a service is within the responsibility of the service provider and its implementation of authorization. While Oracle BPEL Process Manager has no current native support for inbound authorization, Oracle Web Services Manager provides the following capabilities to let authorized users access BPEL processes:

• Supports authorization based on the information contained in any part of the XML message or body

• Provides the following fine-grained access control:

  • Access control at the service level

  • Access control at the SOAP method level

• Supports WS-Security

1.7.2 Message Encryption and Decryption

This section describes the actual message encryption. XML encryption is covered by the WS-Security profile. While Oracle BPEL Process Manager has no current native support for XML encryption, Oracle Web Services Manager provides the following encryption and decryption features:

• WS-security compliant message and content encryption and decryption

• Full or partial message encryption, enabling you to specify an XPath expression to the part of the message that requires encryption.

1.7.3 Digital Signatures

While Oracle BPEL Process Manager has no current native support for digital signatures, Oracle Web Services Manager provides digital signatures and signature verification capabilities. When a client invokes a service, Oracle Web Services Manager performs the following tasks:

• Intercepts this request

• Checks if the service has a digital signature verification policy to be honored

• Verifies the signature

• Passes this request to BPEL to be serviced

Similarly, when BPEL invokes a partner link, Oracle Web Services Manager attaches a digital signature to the SOAP header of the message.