Securing Oracle SOA Applications by Using Oracle Web Services Manager (Oracle WSM) Agents

Purpose

This OBE tutorial describes and shows how to secure your Oracle SOA applications by using the Oracle Web Services Manager (Oracle WSM) client and server agents. It does not cover securing Oracle SOA applications using Oracle WSM Gateway.

Duration

Approximately 1½ hour

Topics

This OBE tutorial covers the following topics:

 Overview
 Scenario
 Prerequisites
 Deploying the SOA Applications
 Testing the SOA Applications
 Creating and Installing an Oracle WSM Server Agent
 Associating the Server Agent with the Web Service
 Testing the Server Agent
 Creating and Installing an Oracle WSM Client Agent
 Configuring the wsif-wsm-config.xml File to Enable the BPEL Process to Securely Invoke the Web Service
 Testing the Client Agent
 Defining Security Policies for the Server Agent
 Defining Security Policies for the Client Agent
 Testing and Verifying That the CreditService BPEL Process Invokes CreditService Securely
 Summary
 Related Information

Viewing Screenshots

 Place the cursor over this icon to load and view all the screenshots for this tutorial. (Caution: Because this action loads all screenshots simultaneously, the response time may be more depending on your Internet connection.)

Note: Alternatively, you can place the cursor over each individual icon in the following steps to load and view only the screenshot associated with that step.


Overview

Oracle Web Services Manager (Oracle WSM) is a Web services security and management solution that provides a common security infrastructure for all Web service applications. It establishes a comprehensive solution for adding policy-driven best practices to all existing or new Web services and provides the key security and management capabilities necessary to deploy Service-Oriented Architectures (SOA) across different business applications.

In Oracle WSM, the policies are being executed in the policy enforcement points that are categorized into gateways and agents.

What Is a Gateway?

Gateway is an Oracle WSM policy enforcement point that operates as an intermediary (proxy) through which Web service requests are routed. The gateway can mediate requests for a number of different Web services and enforce policies on the request path and the response path of each Web service.

What Are Agents?

Agents are lightweight components that run in the same address space (or the application environment) of the Web service or the Web service client. Agents are of two types: server agents and client agents. Server agents intercept Simple Objects Access Protocol (SOAP) requests and enforce management policies based on the platform where the Web service resides. Client agents are injected into the Web applications that call one or more Web services. The client agent may interact with the Web services directly or interact with the application connected to the Web service.

Back to Topic List

Scenario

John works as an SOA administrator for Mydomain Corporation. In Mydomain, John is responsible for managing and monitoring the SOA applications and Web services. He is also responsible for implementing the security policies to secure the communication channel between two or more SOA applications interacting with each other. The SOA application developers have developed the SOA applications without implementing any programmatic security in the SOA components. Therefore, John requires a security system that would enable him to plug in security without making any changes to the SOA applications and their execution environment. John opts to use Oracle WSM to implement a centralized security system to secure the SOA applications.

Back to Topic List

 

Prerequisites

Before you perform this tutorial, you should:

  1. Download and perform a basic installation of the Oracle SOA Suite (10.1.3.1) for the Windows platform. For installation instructions, refer to the Oracle Application Server Installation Guide.

    Note : The SOA application th at is used for demonstrating this tutorial is dependent on the default HTTP Port (8888) of Oracle Application Server.
  2. Download and unzip the applications.zip file into your working directory.

Back to Topic List

 

Deploying the SOA Applications

You must deploy the SOA applications before implementing security by using Oracle WSM. The applications consist of a Web service and a BPEL process that invokes the Web service. Both the applications need to be deployed in the Oracle Application Server. The following are the details of the applications:

To deploy the CreditService Web service and the CreditServiceBPELProcess BPEL application to Oracle Application Server, execute the following steps:

1.

Open a command prompt window, navigate to the directory where you have extracted the application files, and set the following environmental variables:

%ORACLE_HOME% – The directory where you installed Oracle Application Server
%JAVA_HOME% –- The directory where your JDK is installed

 

2.

Open the build.properties file and ensure that the following properties are configured correctly. If necessary, modify these variables to the proper values for your environment.

Note : Some of these properties will default to the values of the corresponding environment variables as noted below. If you have these variables set up in your environment, you may not have to alter the values in the file.

  • oracleas.http.port – The port on which the Oracle HTTP Server (OHS) is listening.
  • oracleas.admin.port – The Oracle Process Manager and Notification Server (OPMN) request port as specified in opmn.xml. The default value is 6003. You can also check the OPMN request port by using the following command: %ORACLE_HOME%/opmn/bin/opmnctl status -port
  • oracleas.admin.user – The name of the OC4J administrator. The default is " oc4jadmin."
  • oracleas.admin.password – The password specified at the time of installing Oracle Application Server
  • oracleas.deployer.uri – The URI used to perform various administration operations, such as deployment, undeployment, and so on. The file contains different URI depending on the topology of your application: stand-alone OC4J, Managed Single Node, or Managed Cluster. Uncomment the URI that matches your topology.
  • oracleas.oc4j.instance – This is the managed OC4J instance where the application is deployed or undeployed.

3.

To generate, compile, and deploy the application components, enter the following command in the command prompt window.

ant all

Press [Enter] to execute the ant scripts. Ensure that you get a "BUILD SUCCESSFUL" message in the command prompt window.

 

Back to Topic List

 

Testing the SOA Applications

After deploying the applications, you should test whether the applications are functional and are executing without a problem. You can use the BPEL Control tool to check whether the CreditServiceBPELProcess BPEL process successfully invokes the CreditService Web service.

1.

Open any Internet browser and enter the following URL in the address bar:

http://localhost:8888/BPELConsole

Note : Here, the HTTP port for the Oracle Application Server is 8888 (default).

2.

Log in to the BPEL Control by providing the username as oc4jadmin and the password as welcome1 (or the one that you provided when installing Oracle Application Server).

 

3.

On the Oracle BPEL Control: Dashboard page, click the CreditServiceBPELProcess link.

 

4.

On the Oracle BPEL Control: BPEL Processes page, under the Initiate tab, enter AMEX in the cType field and 123456789 in the cNum field. Click the Post XML Message button. You see the boolean value true being returned by the CreditService Web service. Close the Internet browser window.

 

Back to Topic List

 

Creating and Installing an Oracle WSM Server Agent

Your task is to secure the CreditService Web service by using Oracle WSM. Therefore, create and install a server agent that enables you to define the security policies for the Web service.

1.

Open any Internet browser and enter the following URL in the address bar:

http://localhost:8888/ccore

2.

Log in with the user ID oc4jadmin and password welcome1 .

 

3.

On the Web Services Manager Control: Enforcement Points page, click the Add New Component button.

 

4.

Enter service_agent in the Component Name field and select Server Agent from the Component Type drop-down menu. Accept the defaults for the other fields and click the Register button.

.

 

5.

Verify that the component has been successfully added. Click OK. Close the Internet browser window.

 

6.

Modify the server agent deployment properties by editing the agent.properties file located in the %ORACLE_HOME%/owsm/bin directory. Verify the first three property settings and set the fourth property setting to the values shown in the following table:

Property Name

Value

agent.componentType

OC4JServerInterceptor

agent.containerType

OC4J

agent.containerVersion 10.1.3
agent.component.id C0003001

Note : The component ID is automatically specified at the time of creating the component. If you have created any other Oracle WSM components before creating the server agent, the component ID for the server agent is different.

 

7.

Install the server agent by using the wsmadmin command tool located in the %ORACLE_HOME%\owsm\bin directory. Open the command prompt window, navigate to the %ORACLE_HOME%\owsm\bin directory, and execute the following command:

wsmadmin installAgent <application server password>

where < application server password> is the password specified when installing Oracle Application Server.

Confirm that the installation of the server agent was successful. Ensure that you see the "BUILD SUCCESSFUL" message in the command prompt window.

Note : Ensure that the application server is running before executing the command to install the agent.

 

Back to Topic List

 

Associating the Server Agent with the Web Service

Configure the Web Service Agent feature in Oracle Application Server to associate the service_agent (WSM server agent) with the CreditService Web service. To perform this task, execute the following steps:

1.

Open any Internet browser and enter the following URL in the address bar:

http://localhost:8888/em

 

2.

Log in to the Oracle Application Server Control by providing the username as oc4jadmin and the password as welcome1 (or the one that you specified at the time of Oracle Application Server installation).

 

3.

Click the home link on the Cluster Topology page.

 

4.

Click the Web Services tab on the OC4J:home page.

 

5.

Click the ValidateCreditCardServiceSoapHttp link under the Web Services tab.

 

6.

On the Web Service: ValidateCreditCardServiceSoapHttp page, click the Administration link.

 

7.

Enable the Web Services Agent feature. To perform this task, click the Enable/Disable Features button, move the Web Service Agent to the Enabled Features list, and click OK.

 

8.

Click the Edit Configuration icon in the Web Services Agent row.

 

9.

On the Edit Web Services Agent Configuration page, enter C0003001 in the Configuration Directory field. Click OK. The Oracle WSM server agent is now associated with the CreditService Web service.

 

10.

Restart the SOA suite.

Note: Stop the SOA suite by using the Start > Programs > Oracle-AS_home > Stop SOA suite option. Then start it again by using the Start > Programs > Oracle-AS_home > Start SOA suite option.

 

Back to Topic List

 

Testing the Server Agent

Before you define security policy steps on the server agent, you must test whether the agent is installed and working successfully. To perform this task, execute the following steps:

1.

Click the Home tab on the Web Service: ValidateCreditCardServiceSoapHttp page.

2.

Click the Test Service link under the Home tab.

 

3.

Click the Test Web Service button on the Test Web Service: CreditService page.

 

4.

On the CreditService endpoint page, enter AMEX in the ccType field and 123456789 in the ccNum field. Click the Invoke button.

 

5.

Click the Formatted XML link on the Test Result page to view the Web service's response message.

 

6.

Open a new Internet browser window and log in to the Web Services Manager Control.

 

7.

Expand Operational Management in the navigation menu. Click and expand the Overall Statistics menu and select Message Logs.

 

8.

On the Message Logs page, select service_agent in the Component drop-down menu and Last hour in the Time Range drop-down menu. Click the Search button.

 

9.

Click the specific Index to view the request and response message. Close the browser window.

Note : Whenever you create an Oracle WSM component, a default policy gets associated with the component that contains the default log policy step in the request and response pipelines. The log policy step captures the request and the response messages that are visible in the Message Logs section. You learn more about the policy steps in the following sections of this tutorial.

 

Back to Topic List

 

Creating and Installing an Oracle WSM Client Agent

You need to create and install an Oracle WSM client agent that enables the CreditServiceBPELProcess BPEL process to securely invoke the CreditService Web service. You use the wsmadmin tool to install the client agent and configure a wsif-wsm-config.xml file to associate the BPEL process with the client agent. To complete this task, perform the following steps:

1.

Expand Policy Management in the navigation menu and select Manage Policies. On the Web Services Manager Control: Enforcement Points page, click the Add New Component button.

 

2.

Enter bpelClient_agent in the Component Name field and Client Agent in the Component Type drop-down menu. Accept the defaults for the other fields and click the Register button.

 

3.

Verify that the component has been successfully added. Click OK. Close the Internet browser window.

 

4.

Modify the client agent deployment properties by editing the agent.properties file located in the %ORACLE_HOME%/owsm/bin directory. Verify the first four property settings and set the fifth property setting to the values shown in the following table:

Note : The client configuration directory is created under the directory specified by the client.home property.

Property Name

Value

agent.componentType

OC4JClientInterceptor

agent.containerType

OC4J

agent.containerVersion 10.1.3
client.home C:/oracle/client
agent.component.id C0003002

 

5.

Install the client agent by using the wsmadmin command tool located in the %ORACLE_HOME%/owsm/bin directory. Open the command prompt window, navigate to the %ORACLE_HOME%/owsm/bin directory, and execute the following command:

wsmadmin installAgent <application server password>

where < application server password> is the password specified when installing Oracle Application Server.

Note : Confirm that the installation of the client agent was successful. Ensure that you see the "BUILD SUCCESSFUL" message in the command prompt window.

 

Back to Topic List

 

Configuring the wsif-wsm-config.xml File to Enable the BPEL Process to Securely Invoke the Web Service

The BPEL process uses the Web Services Invocation Framework (WSIF) to make outbound calls to partner links, such as a Web service. Use the client agent to enable a BPEL process (or the Enterprise Service Bus service) to invoke a secured Web service. Create the wsif-wsm-config.xml file with information about the location of the client agent, the service name and its associated namespace, and the port name and its associated namespace of the Web service that is to be invoked. For example, in this tutorial, the wsif-wsm-config.xml file is configured to invoke the CreditService Web service. You see the service name, CreditService (defined in the localpart attribute of the < service-qname> element) with its associated namespace (defined in the namespaceURI attribute of the < service-qname> element). Similarly, you see the port information defined in the < wsdl-port> element ( ValidateCreditCardServiceSoapHttp). The < owsm> element specifies the location of the installed client agent. The following code describes the wsif-wsm-config.xml file.

<oracle-webservice-clients>
   <webservice-client>
      <service-qname namespaceURI="http://www.globalcompany.com/ns/credit" localpart="CreditService"/>
      <port-info>
         <wsdl-port namespaceURI="http://www.globalcompany.com/ns/credit" localpart="ValidateCreditCardServiceSoapHttp"/>
          <runtime enabled="owsm">
          <owsm init-home="C:\oracle\client\owsm\config\interceptors\C0003002"/>
          </runtime>
          <operations/>
       </port-info>
    </webservice-client>
</oracle-webservice-clients>

Note : You can locate the Web service details (such as the service name and namespace) by browsing its Web Services Description Language (WSDL) document.


To associate the CreditServiceBPELProcess with the client agent, perform the following steps:

1.

In Windows Explorer, copy the wsif-wsm-config.xml file (provided with the application files in the Configuration directory ) to the %ORACLE_HOME%/j2ee/home/config directory.

 

2.

Using a text editor, edit the %ORACLE_HOME%/j2ee/home/config/wsif-wsm-config.xm l file by modifying the following information for the init-home attribute of the < owsm> element:

<owsm init-home= "<client_home>\owsm\config\interceptors\C0003002"/>

where < client_home> is the directory location that you specified in the agent.properties file at the time of installing the client agent.

 

3.

Restart the SOA suite to implement the configuration changes.

Hint : Click the Start menu and select Programs > SOA > Stop SOA suite. Close the window when the SOA Suite component has stopped. To start the SOA suite, select Start SOA suite.

 

Back to Topic List

 

Testing the Client Agent

Before you define security policy steps on the client agent, you must test whether the agent is installed and working successfully. You should also test whether the wsif-wsm-config.xml file has been correctly configured for the BPEL process to access the Web service. To perform this task, execute the following steps:

1.

Open a new Internet browser and enter the following URL in the address bar:

http://localhost:8888/BPELConsole

 

2.

Log in to Oracle BPEL Control by providing the username as oc4jadmin and the password as welcome1 (or the one that you provided when installing Oracle Application Server).

 

3.

On the Oracle BPEL Control: Dashboard page, click the CreditServiceBPELProcess link.

 

4.

On the Oracle BPEL Control: BPEL Processes page, under the Initiate tab, enter AMEX in the cType field and 123456789 in the cNum field. Click the Post XML Message button. You see the boolean value true being returned by the CreditService Web service. Close the Internet browser window.

 

5.

Open a new Internet browser window and log in to the Web Services Manager Control.

 

6.

Expand Operational Management in the navigation menu. Expand the Overall Statistics menu and select Message Logs.

 

7.

On the Message Logs page, select b pelClient_agent from the Component drop-down menu and Last hour in the Time Range drop-down menu. Click the Search button.

 

8.

Click the specific Index to view the request and response messages. Close the browser window.

Note : Whenever you create an Oracle WSM component, a default policy gets associated with the component that contains the default log policy step in the request and response pipelines. The log policy step captures the request and the response messages that are visible in the Message Logs section. You learn more about the policy steps in the following sections of this tutorial.

 `

 

Back to Topic List

 

Defining Security Policies for the Server Agent

You must define the security policy steps on the Oracle WSM server agent to enable the agent to protect the Web service. Oracle WSM policies form a set of operational tasks that are performed at a specified policy enforcement point (either a gateway or an agent) during the processing of a Web service request or a Web service response. Each operational task is implemented as a policy step that addresses a specific operation, such as authentication, authorization, encryption, security signature, or credential verification. Each policy consists of four pipelines:

You need to create a security policy for the server agent that enables it to receive an encrypted request and sign the response message. To execute this task, perform the following steps:

1.

Log in to the Web Services Manager Control. Expand Policy Management in the navigation menu and select Manage Policies.

 

2.

Click the Policies link of the service_agent component.

 

3.

Click the Edit icon of the Default Policy.

 

4.

In the Pipeline: Request section, click the Add Step Below link in the Log policy step.

 

5.

In the New Step dialog box, select XML Decrypt from the Select Step Template drop-down list. Click OK.

 

6.

Click the Configure link in the XML Decrypt section.

 

7.

Enter the following details in their respective fields and click OK:

Property Name

Value

Keystore location

C:\files\Configuration\owsm_server.jks

Decrypt Keystore Type

jks

Keystore password serverpass
Decryptor's private key alias server
Decryptor's private key password server
Enforce Encryption true

Note : The owsm_server.jks keystore file is provided in the applications files.

The above set of policy steps takes care of decrypting a request message from a client.

 

8.

The following set of policy steps enables the server agent to sign the response message and send it back to the client. In the Pipeline: Response section, click the Add Step Below link in the Log policy step.

 

9.

In the New Step dialog box, select Sign message from the Select Step Template drop-down list. Click OK.

 

10.

Click the Configure link in the Sign message section.

 

11.

Enter the following details in their respective fields and click OK:

Property Name

Value

Keystore location

C:\files\Configuration\owsm_server.jks

Signing Keystore Type

jks

Keystore password serverpass
Signer's private key alias server
Signer's private key password server
Signed content BODY

 

12.

Scroll down and click the Next button.

 

13.

Define the Policy Name as CreditServicePolicy and click the Save button.

 

14.

Click the Commit link to commit the changes to the policy.

 

Back to Topic List

 

Defining Security Policies for the Client Agent

You need to create a security policy profile for the client agent that enables it to send an encrypted request message to the CreditService Web service and receive a signed response message. To execute this task, perform the following steps:

1.

Log in to the Web Services Manager Control. Expand Policy Management in the navigation menu and select Manage Policies.

 

2.

Click the Policies link of the bpelClient_agent component.

 

3.

Click the Edit icon of the Default Policy.

 

4.

In the Pipeline: Request section, click the Add Step Below link in the Log policy step.

 

5.

In the New Step dialog box, select XML Encrypt from the Select Step Template drop-down list. Click OK.

 

6.

Click the Configure link in the XML Encrypt section.

 

7.

Enter the following details in their respective fields and click OK:

Property Name

Value

Keystore location

C:\files\Configuration\owsm_client.jks

Encrypt Keystore Type

jks

Keystore password clientpass
Decryptor's public key alias server_public
Encrypted Content BODY

Note : The owsm_client.jks keystore file is provided in the application files. The above set of policy steps takes care of encrypting a request message.

 

8.

In the Pipeline: Response section, click the Add Step Below link in the Log policy step.

 

9.

In the New Step dialog box, select Verify Signature from the Select Step Template drop-down list. Click OK.

 

10.

Click the Configure link in the Verify Signature section.

 

11.

Enter the following details in their respective fields and click OK:

Property Name

Value

Keystore location

C:\files\Configuration\owsm_client.jks

Verifying Keystore Type

jks

Keystore password clientpass
Signer's public-key alias server_public
Enforce Signing true

 

12.

Click the Add Step Below link in the Verify Signature policy step.

 

13.

In the New Step dialog box, select XML Transform from the Select Step Template drop-down list. Click OK.

Note : The XML Transform policy step enables you to remove the SOAP header part (which contains the security information) from the SOAP response message by implementing an XSL file.

 

14.

Click the Configure link in the XML Transform section.

 

15.

Enter the following information in the XSLTFile Name field and click OK.

Property Name

Value

XSLTFileName

C:\files\Configuration\setwsse.xsl

Note: The setwsse.xsl file is provided in the application files.

 

16.

Scroll down and click the Next button.

 

17.

Define the Policy Name as ClientPolicy and click the Save button.

 

18.

Click the Commit link to commit the changes to the policy.

 

Back to Topic List

 

Testing and Verifying That CreditServiceBPELProcess Invokes CreditService Securely

You need to test the security policy implementation that you have defined by implementing Oracle WSM. To perform this test, execute the CreditServiceBPELProcess BPEL process by using the Oracle BPEL Control. You use the BPEL Control Visual Flow to check for successful execution of the CreditServiceBPELProcess BPEL process. To test message encryption and message signing, you use the Oracle WSM Control and view the message logs for the specific policy enforcement points (server agent and client agent). To complete these tasks, perform the following steps:

1.

Launch Oracle BPEL Control from the Internet browser window by entering the following URL in the address bar. If requested, log in as the oc4jadmin user with welcome1 as the password:

http://localhost:8888/BPELConsole

2.

On the BPEL Control Dashboard page, click the CreditServiceBPELProcess link in the Deployed BPEL Processes section.

 

3.

On the BPEL Processes page, under the Initiate tab, enter AMEX in the cType field and 123456789 in the cNum field. Click the Post XML Message button. You can see a boolean value sent by the Web service as its response.

Note : You can click on the Visual Flow icon for more information about the execution flow of the BPEL process.

 

4.

Log in to the Web Service Manager Control to locate the message logs to view the encrypted and signed messages exchanged between the CreditServiceBPELProcess BPEL process and the CreditService Web service, for messages logged in the last hour for the client agent and the server agent, and to view the request/response messages. Click and expand the Overall Statistics menu located under the Operational Management menu. Select Message Logs under the Overall Statistics menu.

 

5.

Select bpelClient_agent as the Component and Last hour as the Time Range. Click the Search button.

 

6.

Click the message logs to view the contents of the request and response messages.

 

7.

Select service_agent as the Component and Last hour as the Time Range. Click the Search button.

 

8.

Click the message logs to view the contents of the request and response messages.

 

Back to Topic List

 

Summary

In this lesson, you learned about:

 Creating and Installing an Oracle WSM Server Agent
 Associating the Server Agent with the Web Service
 Testing the Server Agent
 Creating and Installing an Oracle WSM Client Agent
 Configuring the wsif-wsm-config.xml File to Enable the BPEL Process to Securely Invoke the Web Service
 Testing the Client Agent
 Defining Security Policies for the Server Agent
 Defining Security Policies for the Client Agent
 Testing and Verifying That CreditServiceBPELProcess Invokes CreditService Securely

 

Related Information

 For more information about Oracle WSM, refer to http://www.oracle.com/technology/products/webservices_manager/index.html
 To ask a question about this OBE tutorial, post a query on the OBE Discussion Forum.

Back to Topic List

 Place the cursor over this icon to hide all screenshots.

 

 

 

Left Curve
Popular Downloads
Right Curve
Untitled Document