How to pass Security Credentials from BPEL to ESB to a Web Service

I have seen people facing problems to pass security credentials from an ESB routing service to a WS-Security compliant Web Service. Passing security credentials from ESB routing service is possible but it's tricky. You need to play with the XSLT transformation to add WS-Security tokens in SOAP header of a Web Service request.

Oracle ESB is having four extension function for SOAP header manipulation:

1. String getRequestHeader(String xpathExpression,String namespaceDecl)
2. void setOutboundHeader(String xpathExpression,String value, String namespaceDecl)
3. String getInboundResponseHeader(String xpathExpression,String namespaceDecl)
4. void setResponseHeader(String xpathExpression,String value, String namespaceDecl)

here,
xpathExpression - XPath expression to get/set
value - value to be set for the xpathExpression
namespaceDecl - namespace declarations in the form ‘prefix=namespace;’

You need to add the four expressions given below in the XSLT map before invoking a WS-Security compliant Web Service. First two expressions extract user name and password from the incoming SOAP header and the last two expressions add security credentials in the outbound SOAP header.

<xsl:variable name="userName"
select="ehdr:getRequestHeader('/soap:Header/wsse:Security/wsse:UsernameToken/wsse:Username','wsse=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd; soap=http://schemas.xmlsoap.org/soap/envelope/;')"/>

<xsl:variable name="password"
select="ehdr:getRequestHeader('/soap:Header/wsse:Security/wsse:UsernameToken/wsse:Password','wsse=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd; soap=http://schemas.xmlsoap.org/soap/envelope/;')"/>

<xsl:variable name="setUsername"
select="ehdr:setOutboundHeader('/soap:Header/wsse:Security/wsse:UsernameToken/wsse:Username',$userName,'wsse=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd;')"/>

<xsl:variable name="setPassword"
select="ehdr:setOutboundHeader('/soap:Header/wsse:Security/wsse:UsernameToken/wsse:Password',$password,'wsse=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd;')"/>

See my previous posts How to set security credentials dynamically in Oracle BPEL and Invoking WS-Security compliant Web Services from Oracle BPEL to learn how to send security credentials from a BPEL process. You can download sample BPEL and ESB projects from here. You can use these projects for your reference.

How to set security credentials dynamically in Oracle BPEL

Few months ago I have written a post on invoking WS-Security compliant services, In Oracle BPEL you can either propagate the security credentials coming from the caller process or you can hard-code the tokens in partner link properties.

If you want to invoke a WS-Security compliant web service and want to pass user supplied security tokens, Oracle BPEL does not let you set the security credential dynamically. You need to manually create a UserNameToken and then you need to pass the token as a SOAP header.

Follow the steps given below to change and pass security credentials dynamically:

• Import http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd as it is having definitions for WS-Security tokens.
  

• Create 3 variable as given below:

   <variable name="securityContext" element="ns2:Security"/>
   <variable name="userNameToken" element="ns2:UsernameToken"/>
   <variable name="pswd" element="ns2:Password"/>

• Assign incoming security credentials to these variables:

    <assign name="AssignSecurityCredentials">
       <copy>
         <from variable="inputVariable" part="payload" 
           query="/client:SampleRequest/client:pswd"/>
          <to variable="pswd" query="/wsse:Password"/>  
       </copy>
       <copy>
          <from variable="inputVariable" part="payload"
              query="/client:SampleRequest/client:user"/>  
          <to variable="userNameToken"
              query="/wsse:UsernameToken/wsse:Username"/>
     </copy>       
       <bpelx:insertAfter>  
          <bpelx:from variable="pswd" query="/wsse:Password"/>
          <bpelx:to variable="userNameToken"
            query="/wsse:UsernameToken/wsse:Username"/>  
       </bpelx:insertAfter>
      <bpelx:append>  
        <bpelx:from variable="userNameToken" query="/wsse:UsernameToken"/>
      <bpelx:to variable="securityContext" query="/wsse:Security"/>  
      </bpelx:append>
  </assign>

• Pass the security credentials to the calling service like the expression given below:

  <invoke name="InvokeAxisService" partnerLink="PartnerLinkAxisService"
     portType="ns1:sample03PortType" operation="echo"
     inputVariable="Invoke_1_echo_InputVariable"
     outputVariable="Invoke_1_echo_OutputVariable"
     bpelx:inputHeaderVariable="securityContext"/>

• Complete you BPEL process by adding required functionalities then deploy and test it.

How to deploy Java Classes with BPEL Process

While implementing a business process using BPEL, sometimes it is required to use Java to implement a functionality required by a business process. You can embed your Java code in BPEL process using Java embedding activity provided by Oracle BPEL. If your Java code is of few lines you can paste it inside the Java embedding editor and you can manage it but if you are planning to implement a functionality which requires lines of code, it is better to create java classes inside your BPEL Process Project. You can leverage JDeveloper’s Java editor to write and manage Java code.

You can import Java classes in the BPEL process using <bpelx:exec import....>. If you deploy the BPEL process from JDeveloper it compiles the Java code and bundle required classes and libraries inside the BPEL suitcase. You can use JDeveloper to deploy your processes on the development server. To deploy a business processes on Test/Performance/Production servers its better to use deployment scripts, because its not wise to modify endpoint URL and other connectivity information manually for each server in your BPEL process project and deploy it.

Using deployment scripts you can

• Customize WSDL/XSL/XSD end-point locations.
• Customize JNDI address of Data source/JMS Queue or Topics.
• Checkout latest code from SVN/CVS/VSS repositories.
• Deploy BPEL/ESB/Java on the development/test/performance/production environments.

JDeveloper generates an ant build script for each BPEL process project, it uses ant script to build and deploy business process. If your BPEL process is using java classes and you would deploy it from JDeveloper the process will be deployed successfully. All the Java classes and required libraries will be bundled in BPEL-INF folder of the BPEL suitcase.

If you try to execute the same script from the command prompt it will throw an exception like the one given below:

ORABPEL-00017
Java compilation failed.
Failed to compile file(s) "HelloWorldProcess.bpel".
Exception reported is: HelloWorldProcess.bpel:3: Class build.test.HelloWorld not found in import.import build.test.HelloWorld;

If you see the deployment script it does not have an ant task to compile java code. It works in JDeveloper because JDevloper compile the java classes first and then executes this script so the bpelc task is able to find the required Java classes. To make this script work from command prompt you need to do the following:

• Add a task to compile the java classes.

<target name="compileJava" description="Compile Java files">
 <echo>
--------------------------------------------------------------
Compiling java files
--------------------------------------------------------------
</echo>
  <javac destdir="${process.dir}/output" encoding="UTF-8" source="1.5" target="1.5">
    <src path="${src}"/>
  </javac>
  <mkdir dir="${process.dir}/lib"/>
  <jar destfile="${process.dir}/lib/${bpel.classes.jar}">
    <fileset dir="${process.dir}/output"/>
  </jar>
</target>

• Modify target "compile" and add dependency for target "compileJava".

<target name="compile" depends="compileJava">

• Modify the bpelc task to add classpath for the compiled java classes so bpelc will be able to find the required classes.

<bpelc input="${process.dir}/bpel/bpel.xml" out="${process.dir}/output"
rev="${rev}" home="${bpel.home}" classpath="${env.classpath};${process.dir}\output">

• As some libraries are business process specific, you want to keep them inside the BPEL suitcase rather then adding them to shared libraries or copying to <ORASOA_HOME>/j2ee/home/applib folder. If you copy the libraries to applib folder or add to shared libraries by modifying server.xml you need to bounce the SOA server. To copy the BPEL process specific dependency jars and the classes in the BPEL-INF folder of BPEL suitecase, you need to add <lib> tag in the bpelc task:

<bpelc input="${process.dir}/bpel/bpel.xml" out="${process.dir}/output"
   rev="${rev}" home="${bpel.home}" classpath="${env.classpath};${process.dir}\output">
  <lib dir="${process.dir}/lib" includes="bpelclasses.jar"/>
  <lib dir="${bpel.lib}" includes="**/*.jar"/>
</bpelc>

Save the build script and execute it from command prompt, don’t forget to set username/password for SOA suite and all other environment related properties in build.properties.

ORABPEL-09500

Sometime it is required to do file input/output operations from a BPEL process. You can use file adapter to read/write files, but it’s not a wise choice always. Oracle BPEL having three XPath extension functions ora:readFile, ora:readBinaryFromFile and ora:writeBinaryFIle for file input/output operations. You can read/write files using these extension functions.

Syntax of these functions is simple and JDeveloper expression builder helps you to add the functions in your BPEL process. You can read files packaged inside BPEL process suite case or from the file system.

While accessing files from the file system using absolute path, you might get the following error:

ORABPEL-09500 XPath expression failed to execute. Error while processing xpath expression, the expression is "ora:readFile(bpws:getVariableData('inputVariable','payload','/client:TestProcessRequest/client:input'))", the reason is FOTY0001: type error. Please verify the xpath query.

The error message is wrong and deceptive. Although the error message is showing that the XPath expression is incorrect but it’s not the reason behind this fault. Reason behind this error is that the BPEL process manager is unable to access file(s) from the given path and it is showing wrong error message. It may be a bug in Oracle BPEL Process Manager.

To get rid of this issue you need to check the path of the file you want to read or write. Make sure that you are giving the correct path and the file is available at the given location (if you are reading the file). After checking and correcting the file path you need to prefix the file path with “file:”. Next step is to save, deploy and test the BPEL process.

How to Manipulate SOAP Headers in BPEL

Now Web Services are the De facto standard to implement SOA for any organization. Web Services are self contained, self descriptive and open standard based. Everyone who is implementing web services needs to follow the same standards. W3C, OASIS, and WS-I standardizes these open standards. These standard can be applied to a new service as well as an existing service and it is the beauty of these standards. WS-* standards are based on the SOAP headers so you don't need to touch the web service implementation. To support these standards the BPEL specification implementation should have inbuilt capabilities to manipulate SOAP headers.

If we talk about Oracle BPEL Process Manager (Oracle's implementation of BPEL specification) it is having SOAP header manipulation capabilities through BPEL extensions. You can send or receive SOAP headers from a BPEL process using bpelx:inputHeaderVariable, bpelx:headerVariable extensions.

To send SOAP headers from the BPEL process you need to use bpelx:inputHeaderVariable extension in the invoke activity, just give a comma separated list of all the variables you want to send in the SOAP header. To receive SOAP headers you need to use bpelx:headerVariable extension in the receive activity. Once you add these extensions in the receive or invoke activity your part is over and the BPEL Process Manager will add your variables to SOAP header if you are invoking a web service or extract SOAP headers if you are using receive activity and assign SOAP headers to the specified variables.

Sending or receiving SOAP headers from Oracle BPEL is very simple, you need to create messages inside WSDL, variables in BPEL process and then need to use bpelx:inputHeaderVariable and bpelx:headerVariable extensions. See the following to understand how to add bpelx:inputHeaderVariable and bpelx:headerVariable into the invoke, receive, onMessage and reply activities respectively:

<receive name="receiveInput" partnerLink="client" portType="client:TestProcess"
operation="process" variable="inputVariable" createInstance="yes" bpelx:headerVariable="yourVariable1, yourVariable2"/>

<invoke name="Invoke_1" partnerLink="NestedSchemaTest"
portType="ns1:NestedSchemaTest" operation="process"
inputVariable="Invoke_1_process_InputVariable" outputVariable="Invoke_1_process_OutputVariable" bpelx:inputHeaderVariable="yourVariable1, yourVariable2 .." bpelx:outputHeaderVariable="yourVariable1, yourVariable2 ..."/>

If you are invoking an asynchronous process then don't use bpelx:outputHeaderVariable extension.

<onMessage bpelx:headerVariable="variable_1 variable_2 ..." />
<reply bpelx:headerVariable="variable_1 variable_2..." />

Deploy your BPEL process and use TCP protocol monitor or obtunnel to see the SOAP headers in the SOAP envelop. Don't forget to set the "optSoapShortcut" property to "false" otherwise you wont be able to see the SOAP headers in obtunnel or TCP monitor. From oracle 10.1.3.1 this property is not available on the BPEL control so you need to add it in the <BPEL Home>/domains/<domain>/config/domain.xml as given below:

<property id="optSoapShortcut">
   <name>Optimize SOAP invocations.</name>
   <value>false</value>
   <comment></comment>
</property>

How to Make Libraries Available to BPEL Process

I have seen many integration developers struggling with the classpath settings in Oracle SOA Suite. If you don't know the right place to store libraries or the configuration files where you can add required libraries, you can easily waste hours or even days to make libraries available to your BPEL process.

While developing Oracle BPEL Process you need to add the required libraries in Jdeveloper. To add a library in Jdeveloper right click on the BPEL Process project and select “Project Properties” from the context menu. Click on Libraries in the Project Properties tree. From Libraries page you can add a predefined library or you can add jars or folders in the classpath.

If you want to use standalone ant scripts to compile and build your BPEL process flow you need to set classpath in ant build scripts. You need to add libraries in the bpelc task. Add your libraries as given below, add a pathelement for each library:

<classpath>
 <pathelement location="Library you want to add into classpath"/>
</classpath>

If you want to use common jars in multiple projects, add the files into classpath of obsetenv.bat or obsetenv.sh based on the platform you are using to run ant build scripts. Edit the obsetenv file and add the libraries in the MY_CLASSPATH variable. e.g.

set MY_CLASSPATH=%Existing Libraries%;<new libraries>

If you are using Java embedding activity in your BPEL process and this activity is referring classes and jars those are not part of the BPEL suite case , you need to add those libraries in the classpath of BPEL Process compiler. BPEL Process Manager generates Java files and compile them at the deployment time so it is required to set all the referenced libraries in BPEL compilers classpath.

You can add the referenced libraries in BPEL Process compiler's classpath by modifying the domain.xml or from the BPEL Process Manager's Console. I am mentioning both procedures, you can use any of them.

• Edit Domain Configuration file-

  • Edit <Oracle SOA Home>/bpel/domains/<Domain Name>/config/domain.xml

• Add referenced libraries the file as given below:
  <property id="bpelcClasspath">
  <name>BPEL process compiler classpath</name>
  <value>list of jars separated by ; or : based on the platform you are using</value>
  </property>

• Restart Oracle BPEL Server.

• Use BPEL Process Manager Console

  • Open BPEL Process Manager Console and click on “Manage BPEL Domain”. Go to Configuration tab.

  • Enter all the referenced libraries(including path of the libraries); in the value field of bpelcClasspath property..

  • Click on Apply button.

  • Restart Oracle BPEL Process Manager..
    

  After deployment you will definitely want to test the BPEL process. You need to add the required libraries into Oracle Application Server's classpath, so the referenced libraries would be available for your BPEL process at runtime. Follow the steps given below to add libraries into Oracle Application Server's classpath:

• Open <Oracle Home>/j2ee/home/config/application.xml and find a shared library named oracle.bpel.common.

• Add <code-source path="Your library path"/> for each required jar file. You can create a separate library and import it inside the oracle.bpel.common shared library.

Insert New Line Character in BPEL Payload

Today my colleague has an interesting requirement. He need to interact with a legacy application which accepts input in CSV format. In the input first row should contain operation name, second row should contain all the column names and the next row is the data row. He was using Oracle BPEL to integrate legacy application with new application infrastructure. He was having data in a canonical business object and want to generate the required input CSV format.

The major challenge for him was to transform the business object into the input CSV which is having three rows. As he was a Java developer in the past, he tried using \n to insert new line character with no luck. Then he tried &#13; which is the correct one to insert a new line character in an XML payload but when he executed the BPEL flow, &amp;#13; was inserted rather than the line break.

The trick to insert the new line character in XML payload from Oracle BPEL is to append &#13; in the from expression of assign activity, then check your .bpel file it would have &amp;#13; rather than &#13; because Jdeveloper replaces & with its equivalent escape character &amp;. You need to replace &amp; with & so it would become the correct new line character &#13;.

How to change Input/Output Variable for a BPEL Process

When you create a BPEL process project it asks for input and output XSD elements, you can choose your input and output elements over there. Once you are finish with the project creation you can start designing BPEL flow using the IDE. It is the ideal scenario where you have your input and output XML schema's defined before starting development of BPEL process and these schema's won't require any modifications in the future. But in the real life scenarios it rarely happens. Any change in requirements or policies impacts input and output XML schema's. Sometimes you need to change input and output schema elements for a BPEL process.

Changing input or output XML schema element types is really a challenge in JDeveloper. You need to check for the impact of these changes. JDeveloper doesn't give any feature to update all the artifacts impacted by any changes in the input/output XSD elements. You need to modify all the impacted artifacts manually.

Every BPEL process is exposed as a web service using WSDL so you need to change the WSDL first. If you need to use input/output elements from an XSD or WSDL file, you need to import the XSD or WSDL in your BPEL process project WSDL.

To import a WSDL use the following statement:

<import namespace="Namespace of WSDL" location="WSDL Location"/>

To import an XSD use the following statement:

<types>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:import namespace="Namespace of XSD" schemaLocation="XSD Location"/>

</xsd:schema>

</types>

Delete all the <import> statements having unused XSD's or WSDL's. Make sure that all the imported XSD's and WSDL's doesn't have duplicate elements and you are not importing any WSDL, XSD more than one time, otherwise you will get ORABPEL-10902 error while compiling the BPEL process project.

Next step is to change the input/output element type. If you are importing a WSDL for input/output element you need to change the input and output message for the desired operation. e.g.

<operation name="process">

<input message="prefix:Message Type"/>

<output message="prefix:Message Type"/>

</operation>

If you are importing an XSD for input/output element you need to change the element name in the message part for request and response messages.

<message name="YourProcessNameRequestMessage">

<part name="payload" element="prefix:Element Name"/>

</message>

<message name="YourProcessNameResponseMessage">

<part name="payload" element="prefix:Element Name"/>

</message>

Make sure that you are providing the correct elements and you are using the correct namespaces otherwise you will get ORRABPEL-10902 error with the following message:

[Error ORABPEL-10902]: compilation failed [Description]: in "bpel.xml", XML parsing failed because "undefined part element.

Validate your BPEL flow, compile it and deploy it on the server.

How to change Namespace for a BPEL Process Project:

I have seen many developers faced problems while changing namespaces for a BPEL process project. When you create a project in JDeveloper it asks for the project namespace and uses the given namespace for the project artifacts. JDeveloper does not give any option to change namespace for a BPEL process project after creating the project. You could have faced the same issue many times.

To change namespace for a BPEL Process project you need to modify .wsdl, .bpel and .xsd files in your BPEL Process project manually. You need to modify the targetNamespace in .wsdl, .bpel, .xsd files from old to the new one.

Bug In Oracle BPEL Process Manager Console

Last week one of my colleague was developing a synchronous BPEL process. He was using a nested XML schema to create input variable for the BPEL process. After completion of development he deployed the BPEL process on Oracle BPEL Process Manager 10.1.3.3. While testing he got a time out exception, he thought process is doing heavy processing so it might take longer to complete the execution so he increased the time out for synchronous process by setting a larger value for “syncMaxWaitTime” property. He tried so many times with no luck. Then he checked the flow on BPEL console and he found the assign activity is having SelectionFailure error so he started checking BPEL process . He checked XSD's and the XPATH expressions used in assign activity. He was wondering why he is getting SelectionFailure even though everything is correct in the BPEL process and XSD's.

After investing ample of time he has got frustrated and started looking for someone who has already faced the same issue and lucky enough to get rid of this issue.

The reason behind this issue is the wrong input XML that was generated by Oracle BPEL Process Manager. The namespace prefixes are not correct in the input XML so it was not able to find the values from input XML document.

Following input XML is generated by the BPEL Process Manager Console, see the namespace prefixes given in bold, these namespace prefixes are wrong :

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body xmlns:ns1="http://xmlns.oracle.com/schemas/employee">
<ns1:Employee>
<ns1:PersonalDetails>
<ns1:Name>Vijay</ns1:Name>
<ns1:Age>30</ns1:Age>
</ns1:PersonalDetails>
<ns1:Address xmlns:ns2="http://xmlns.oracle.com/schemas/common">
<ns2:Address1>2800 S Ashland</ns2:Address1>
<ns2:Address2>GeenBay</ns2:Address2>
</ns1:Address>
<ns1:Department xmlns:ns3="http://xmlns.oracle.com/schemas/common">
<ns3:Name>IT</ns3:Name>
<ns3:DeptType>Development</ns3:DeptType>
</ns1:Department>
</ns1:Employee>
</soap:Body>
</soap:Envelope>

So correcting the namespace prefixes solved the problem. See the modified XML schema given below.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body xmlns:ns1="http://xmlns.oracle.com/schemas/employee">
<ns1:Employee>
<ns1:PersonalDetails>
<ns1:Name>Dan</ns1:Name>
<ns1:Age>30</ns1:Age>
</ns1:PersonalDetails>
<ns2:Address xmlns:ns2="http://xmlns.oracle.com/schemas/common">
<ns2:Address1>2800 S Ashland</ns2:Address1>
<ns2:Address2>GeenBay</ns2:Address2>
</ns2:Address>
<ns3:Department xmlns:ns3="http://xmlns.oracle.com/schemas/common">
<ns3:Name>IT</ns3:Name>
<ns3:DeptType>Development</ns3:DeptType>
</ns3:Department>
</ns1:Employee>
</soap:Body>
</soap:Envelope>

Invoking WS-Security compliant Web Services from Oracle BPEL

In last post I have discussed my experience on invoking Web Services using SSL from Oracle BPEL. SSL is a transport level security mechanism; it offers authentication, confidentiality and message integrity. It is one of the proven technologies to secure web applications. Various organizations leverage SSL to protect their web applications.

SOA applications are loosely coupled and composed with multiple services. SOA applications are discoverable from public registries. So securing SOA application is not only securing the transport layer. For a Business Process it might be required to invoke multiple intermediary services. Transport Layer Security can only guarantees security when data is on wires. SOA application security requires a mix of Transport Layer Security and Application-Level Security.

Nowadays many organizations are using Web Services to implement SOA. In Web Services world a lot of specifications are existed to address SOA security needs:

• WS-Security.

• WS-Addressing.

• WS-ReliableMessaging.

• WS-Policy.

• WS-SecurityPolicy.

• SAML.

• WS-Trust.

• WS-SecureConversation.

• WSFederation

In future posts I would discuss all the above mentioned standards in detail.

WS-Security specification provides extensions to the SOAP envelope header used to implement integrity and confidentiality of a message and authenticating the sender. WS-Security specifies how to associate a security token with a SOAP message. WS-Security specification is designed to be extensible. It doesn’t require any specific type of security token.

Oracle SOA Suite supports WS-Security specification. We can handle most of the complex SOA security scenarios using Oracle BPEL Process Manager and Oracle Web Service Manager.

“User Name Token” is a very common scenario to authenticate the web service consumer. It provides a standards-based way to send user credentials so that web services deployed on different platforms can share user credentials. It utilizes a message-based security approach moving credentials outside of the actual operation into SOAP headers without modifying the Web Service contract,

Let’s assume a WS-Security compliant Web Service is deployed on Axis2 and this method contains a method named getPrice(). To interact with this web service, you need to send SOAP messages containing valid WS-security credentials. We can convert any unsecured web service to a secured web service. No need to modify any web service to make it secure. The WS security specification plays with the soap headers rather than modifying the business logic or adding the authentication and authorization logic inside any service. It is the beauty of the WS-Security specification.

To pass security credentials from a BPEL process to another BPEL Process or any other web service it is required to set the following properties on the partner link which is used to invoke a WS Security compliant web service:

wsseHeaders Creates a WS-Security username token. The following values are supported:

• propagate — If the process has been invoked securely, these credentials are also used for the outbound direction

• credentials — Passes credentials from the BPEL deployment descriptor(bpel.xml).

wsseUsername The username for the token. It is a required property.

wssePassword The password for the token. It is an optional property.

Now you are ready to create a BPEL process in JDeveloper. Follow the given steps to create a BPEL Process:

• Create a new BPEL process project named “InvokeWSSecurityCompliantService“ with the Synchronous BPEL Process.

• Click on next and accept all the defaults and finish the wizard.

• Right click on the services area and choose “Create Partner Link” from the context menu.

• Name this partner link “WSSecurityCompliantServicePL”.

• Browse the WSDL file from the file system. JDeveloper would ask to make a local copy of the external WSDL file and ask to add partner link in the WSDL. Click on “Yes” on both the dialog boxes.

• Select Partner Link Type, Partner Role and click on the “Property” tab to provide WS security credentials.

• Click on “Create” and select “wsseHeaders” from the drop down list.

• You can use either “credentials” or “propagate” based on the requirement. If this BPEL process would be invoked by another process which is passing security credentials then you can use “propagate” to tell BPEL process manager to pass the incoming credentials to the service you are calling. You can use “credentials” as the property value to instruct BPEL Process Manager to read credentials from the deployment descriptor(bpel.xml).

• Create two new properties “wsseUsername” and “wssePassword” by following the same approach.

• Add “invoke” activity, name it as “InvokeSecuredWS” and link it with the partner link. Select the operation “getPrice” and create input and output variables.

• Add 2 assign activities to assign and transform the input and out variables. Final BPEL process will look like the following image:

• To deploy the BPEL process project on Oracle BPEL Process manager right click on the BPEL Process Project. From the context menu select “Deploy”, choose the appropriate integration server connection from the Deploy menu and select the appropriate domain.

• Test the BPEL process from the BPEL Console or from any client.

Now you are able to invoke WS-Security compliant web services. In next post I would throw some light on BEPL deployment descriptors configuration and preference properties. These properties play a crucial role in customizing BPEL processes as per our requirements.

Invoking Secured Services (https) from Oracle BPEL

Security is one of the main concerns for IT from its initial stages. Nowadays IT is more matured and more aligned with business so securing IT is securing the overall business. When we think about SOA we can apply security at various levels. This is the first post in SOA security series; in this post I would share my experience on invoking Web Services using SSL from Oracle BPEL.

The Web Services are deployed on Axis2. Follow these steps to enable SSL in tomcat:

• Create a certificate keystore using the following commands:

• On Windows:

%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA

• On Unix:

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA

• Provide the required details and set the password to "changeit".

• Uncomment the "SSL HTTP/1.1 Connector" entry in <TOMCAT_HOME>/conf/server.xml and make changes if necessary.

These configurations are well enough for enabling SSL using JKS, see the following for more information on adding third party certificates:

http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html

Oracle BPEL Process Manager has problems to consume a web service when the WSDL has two bindings one for http over soap and the other for https over soap, so you need to expose the web service on Axis2 for https over soap only.

Open <AXIS_HOME>\samples\quickstart \resources\META-INF\services.xml and add the following xml fragment inside <service > tag to expose the web service on https transport only:

<transports>

<transport>https</transport>

</transports>

Generate a web service for <AXIS_HOME>\ samples\quickstart from the Axis2 distributable by executing the ant script given in <AXIS_HOME>\samples\quickstart folder. The generated web service would go inside the <AXIS_HOME>\samples\quickstart\build folder as “StockQuoteService.aar”.

Deploy the generated web service to Axis2 either manually copying to the <TOMCAT_HOME>\webapps\axis2\WEB-INF\services folder or using the axis2 admin console.

Now service is available on HTTPS so we can move forward to create an Oracle BPEL process project to invoke the service using SSL.

To invoke the service exposed on HTTPS you need to import the server certificate in Oracle BPEL Process Manager and Oracle JDeveloper. Follow these steps to import the SSL certificate in Oracle BPEL Process Manager and Oracle JDeveloper:

• Open the endpoint URL of the service to invoke in internet explorer After connecting to the server, a pop-up window displays the security alert and asks whether you trust this certificate or not?

• Click on “yes” to accept the certificate.

• Wait for the page to load completely. Once the page gets loaded double click on the lock displays in the status bar in the bottom right corner of the browser window.

• A new popup window titled “Certificate” would be displayed click on the details tab and press “copy the file” button to save the certificate in a file.

• When you press the “Copy to File” button a wizard would guide to save the certificate. Select “Base-64 encoded X.509(.cer)” for certificate format.

• Give the file location and file name to store the certificate e.g. Cert.cer. Click on next and finish the wizard by pressing the “Finish” button

• Use the saved file to import the server certificate to the trust store of Oracle BPEL Process Manager and Oracle JDeveloper.

• Copy the server certificate into the following folders:

• <ORACLE_SOA_HOME>\jdk\jre\lib\security folder

• <JDEVELOPER_JRE_HOME>\jdk\jre\lib\security

Note: To know the JRE home for JDeveloper go to “Tools” menu and select “Project Properties” a new window would be opened. Click on Libraries to see the JRE home.

• Use the following command to import the certificate into Oracle BPEL Process Manager :

<ORACLE_SOA_HOME>\jdk\bin\keytool -import -v –file <CERTIFICATE_LOCATION>\Cert.cer -keypass <KEYSTORE_PASSWORD> -keystore <ORACLE_SOA_HOME>\jdk\jre\lib\security\cacerts -alias <Any Alias>

• You need to import the same certificate in the JRE of the JDEveloper. Use the following command to import the certificate into the JRE used by the Oracle JDeveloper:  

<JDEVELOPER_JRE_HOME>\jdk\bin\keytool -import -v -file <CERTIFICATE_LOCATION>\Cert.cer -keypass <KEYSTORE_PASSWORD> -keystore <JDEVELOPER_JRE_HOME>\jdk\jre\lib\security\cacerts -alias <Any Alias>

• Restart Oracle SOA Suite and Oracle JDeveloper.

Now you are ready to create a BPEL process in JDeveloper. Follow the given steps to create a BPEL Process:

• Create a new BPEL process project named “InvokeServiceOnHTTPS“ with the Synchronous BPEL Process.

• Click on next and accept all the defaults and finish the wizard.

• Right click on the services area and choose “Create Partner Link” from the context menu.

• Name this partner link “SecuredServicePL”.

• Browse the WSDL file from the file system. JDeveloper would ask to make a local copy of the external WSDL file and ask to add partner link in the WSDL. Click on “Yes” on both the dialog boxes.

• Select Partner Link Type and Partner Role and click on “OK” button.

• Add “invoke” activity named “InvokeSecuredWS” and link it with the partner link. Select the operation “getPrice” and create input and output variables.

• Add 2 assign activities to assign the input and out variables. Final BPEL process will look like the following image:

• To deploy the BPEL process project on Oracle BPEL Process manager right click on the BPEL Process Project. From the context menu select “Deploy”, choose the appropriate integration server connection from the Deploy menu and select the appropriate domain.

• Test the BPEL process from the BPEL Console or from any client.

Now you are able to invoke web services exposed over https from Oracle BPEL Process Manager. In next post I would throw some light on how to invoke WS-Security-Compliant Web Services from Oracle BPEL Process Manager.