| Oracle® SOA Suite Developer's Guide 10g (10.1.3.1.0) Part Number B28764-01 |
|
|
View PDF |
| Oracle® SOA Suite Developer's Guide 10g (10.1.3.1.0) Part Number B28764-01 |
|
|
View PDF |
This section describes the procedure for encrypting data using an Oracle Web Services Manager Gateway.
In the SOA Order Booking Application, business processes handle sensitive data which is not secured, as can be verified by reviewing how data is sent within the process flow.
To review how data is sent:
Using the Oracle BPEL Process Manager Console, review the SOA Order Booking Application process flow shown in Figure 10-24:
Scroll down to review the CreditService flow, as in Figure 10-25:
Click on InvokeCreditService for message details, as shown in Figure 10-26:
Oracle BPEL Process Manager sends the user's credit card details, in clear text, to the Credit Validation Service for validation.
To avoid sending this data in clear text, an Oracle Web Services Manager gateway can be set up and used to encrypt data being sent from the Oracle BPEL Process Manager process to the Credit Validation Service. The Oracle Web Services Manager agent will authenticate the user, then decrypt and hand off the message to the partner link.
|
Note: The use of a gateway illustrates just one approach for performing this task with Oracle Web Services Manager. For a comparison of agents and gateways, see Section 10.2.1, "When to Use Agents or Gateways". |
Figure 10-27 shows how an Oracle Web Services Manager Gateway is utilized for this purpose in the SOA Order Booking Application. The gateway encrypts data that clients send to the web service.
Figure 10-27 Encryption with Oracle Web Services Manager
The steps to accomplish Oracle Web Services Manager encryption are as follows:
Register the Oracle Web Services Manager Gateway.
Locate the WSDL for the web service.
Register a policy for the services protected by the gateway.
Redirect web service clients to the gateway.
Create the certificate keystores.
Define the encryption and decryption policy steps.
Test the message encryption.
Oracle Web Services Manager Gateways serve as intermediaries, acting as a proxy through which web service requests are routed.
To register a gateway:
Log in Oracle Web Services Manager to Oracle Web Services Manager the Web Services Manager Control Console.
Click Add New Component.
Figure 10-28 shows a new component named BPEL Gateway:
Note that the Component Type is Gateway, and the Component URL matches the URL of the gateway application that resides on Oracle Enterprise Manager.
Click Register. Figure 10-29 shows the confirmation page which appears:
Make a note of the component ID, and click OK.
Using a text editor, open the gateway configuration file which is located in:
Oracle_Home/owsm/config/gateway/gateway-config-installer.properties
Replace the value of gateway.component.id with the gateway ID generated in Step 3.
Save and close the file.
Use the wsmadmin command-line tool to start the gateway.
This procedure creates a gateway in Oracle Web Services Manager. However, there are as yet no policy steps attached to this gateway.
When you register a gateway, Oracle Web Services Manager adds it to the server system registry. It also assigns a unique component ID number to the gateway; this ID identifies the component for all actions across your deployment, and in metrics collected from the gateway.
Create a systematic naming convention for all your components. Record the "friendly" name for the component along with the following details:
Component ID
Product version number
Component description
Other component-specific details relevant to that policy enforcement point
As noted earlier, a gateway is not operational until you identify the services it will protect and define the security policies to be implemented for each service.
In order to create an Oracle Web Services Manager policy for a web service, it is necessary to know the WSDL location of the service. Since service WSDLs do not reside in BPEL, this information must be retrieved from another source such as a UDDI registry or OC4J.
The procedure is illustrated by obtaining the WSDL for the Credit Validation Service service in the SOA Order Booking Application from the application server.
To locate the service WSDL:
Log in to the Oracle Enterprise Manager 10g Application Server Control Console.
Expand home.
Click the application whose WSDL information is required. In the example, it is the web service named SOADEMO-CREDITSERVICE-CreditService-WS.
On the service's Application Home page, click Web Services.
The list of services is displayed. In the example, the only service listed is ValidateCreditCardServiceSoapHttp. Click Test Service.
Click Test Web Service. This brings you to the web service home page, as shown in Figure 10-30:
The home page displays the list of operations available for the web service, and links to the web service's WSDL and the service's JavaScript stub.
Click the Service Description link, which opens the WSDL for the web service. Figure 10-31 shows this page for the Credit Validation Service:
Your browser's address bar shows the WSDL location URL. Note the address. In the next section, this WSDL address is used to register the web service at an Oracle WSM Gateway.
|
Note: For an alternative approach to web service invocation, see Section 9.7, "Testing the Web Application". |
Earlier, an Oracle Web Services Manager Gateway Oracle Web Services Manager Oracle Web Services Manager was configured as the first step in protecting interactions between the client application and the web service.
A gateway can handle security policies for multiple web services. You must now specify the web service which the gateway Oracle Web Services Manager will secure.
To register the web service at the gateway:
Start at the Web Services Manager Control Console.
Click Policy Management, then click Register Services. The available gateways are displayed.
Locate your gateway in the list, and click the corresponding Services link.
The list of web services for the gateway are displayed. Currently there are no services defined for the example BPELGateway. Click Add New Service.
Provide this information to register the service:
| Field | Value |
|---|---|
| Service Name | Gateway Service |
| Service Version | 1.0 |
| Service Description | BPEL Gateway Service |
| WSDL URL | The WSDL URL saved in Step 8 of "How to Locate the Service WSDL". |
| Service Protocol | http(s) |
Accept the default values for the other fields.
Figure 10-32 shows the service details defined for the Credit Validation Service:
Click Next. A second page appears, displaying the service protocol parameters.
Accept the defaults, and click Finish.
A confirmation page appears, informing you that the service has been added. Click OK.
The list of services defined at the gateway is displayed. The service needs to be committed by clicking the Commit link.
When you receive confirmation that policies have been committed, click OK.
|
Note: Although the commit action updated the gateway with the new service details, no security policy steps have been configured yet. Configuring an encryption policy step for the service at the gateway, and a decryption policy step at the server agent, are the subject of Section 10.4.8, "How to Define Encryption and Decryption Policy Steps". |
From the list of services defined at the gateway, click the View Details icon of the gateway service. The service details page appears, as shown in Figure 10-33:
Make a note of the Service WSDL URL. This WSDL will be used in the next procedure to redirect credit rating service clients to the gateway.
To protect the web service with Oracle Web Services Manager an Oracle Web Services Manager Gateway, it is necessary to ensure that the service cannot be invoked directly. To achieve this, the service WSDL must be updated to point to the gateway.
For example, one can modify the WSDL of the Credit Validation Service so that it points to the gateway that was created earlier (described in "How to Register the Gateway").
|
Note: Security can be extended by disabling the original URL. Publishing the new, secure URL to a Universal Description, Discovery, and Integration (UDDI) registry simplifies service discovery and makes it available for invocation by other applications. |
To redirect clients to the gateway:
Launch JDeveloper.
In the Applications Navigator, locate and expand the application file (for example, SOADEMO/SOAOrderBooking).
Expand Integration Content.
Double-click the .bpel file (for example, SOAOrderBooking.bpel).
Scroll down the Partner Links. Expand the service of interest. Right-click the service icon and select Edit.
In the Edit Partner Link dialog, note the location of the WSDL File for the service.
Open the WSDL file in Oracle JDeveloper (or any text editor). To view the file in the Oracle JDeveloper WSDL Editor, in the Edit Partner Link dialog under WSDL Settings, click the Browse WSDL Files from Local File System icon, locate the file, and click Open.
Figure 10-34 shows a portion of the Credit Validation Service WSDL file:
The location attribute of the import tag contains the web service WSDL URL. Replace this with the gateway service WSDL URL.
The gateway service WSDL URL can be obtained in the Web Services Manager Control Console by clicking Policy Management, then Register Services. Click Services for the relevant gateway, and click View Details for the service.
For example, the URL for the gateway protecting the Credit Validation Service is shown in Figure 10-35:
Copy the service WSDL URL and paste it into the location field in the service WSDL file. Figure 10-36 shows the file after it has been updated:
Save the file. Compile and redeploy the process.
In order to perform encryption Oracle Web Services Manager and decryption, Oracle Web Services Manager keystores that contain the certificates for both the gateway and agent. In this section the java keytool utility is invoked to generate the keystore are needed.
To create a certificate keystore:
Open a command prompt. It does not have to be the BPEL Developer Prompt; any command window will suffice.
Navigate to your JAVA_HOME/bin directory.
Run the keytool command using the parameters needed to create a keystore. The command is one continuous line, even though it may wrap on multiple lines, as shown in Figure 10-37:
|
Note: You can run thekeytool command without any parameters to display command options. |
When specifying the location of the keystore with the -keystore parameter value, a path can be supplied; there is no specific path requirement and the keystore can reside anywhere on the system.
The example in Figure 10-37 creates a keystore named orderbooking.jks in the current C:\Demo directory.
You will be asked a series of questions. After you respond to the questions, the store is created.
Make a note of the information you provide on the command line and in the subsequent dialog, because you will need this information later when the gateway policy steps are defined.
Close the command window.
The preceding discussion of keystores illustrated setting up a single keystore on the gateway (client side). In a realistic scenario, certificate keystores are required on both the client side and the server side.
The process by which message security is implemented drives the specific configuration details. For flexibility, Oracle Web Services Manager provides a range of policy steps. For example, the message can be encrypted and signed in separate policy steps, in which case decryption and signature verification must be performed separately in reverse order.
For more information, see:
The Oracle Web Services Manager Administrator's Guide. The appendix on Oracle Web Services Manager Policy Steps provides details about the usage and context of specific encryption, decryption, and signing steps.
The Oracle Web Services Manager Deployment Guide. The chapter on Integrating with Oracle Business Process Execution Language describes how to install certificates to facilitate encryption and decryption, and signing and verification.
Policy steps must next be set up to 1) encrypt Oracle Web Services Manager the messages Oracle Web Services Manager being sent by the Oracle BPEL Process Manager client to the Oracle WSM Gateway, and 2) decrypt the messages received by the Oracle WSM Server Agent (in the SOA Order Booking Application, this agent "wraps around" the Credit Validation Service).
To define the encryption policy step:
Log in to Oracle Web Services Manager the Web Services Manager Control Console.
Select Policy Management, then click Register Services to list the gateways.
Click the Services link for the gateway of interest. The list of services for the gateway is displayed.
Click the Edit icon for the service of interest. The service details are displayed.
In BPELGateway, which was set up in Section 10.4.1, "How to Register the Gateway", the only configured service is the BPEL Gateway Service.
In Service Policy, click Modify Policy. The policy pipeline page appears.
The request and response pipelines of the policy include, by default, a Log step that enables SOAP messages to be recorded at a policy enforcement point. In the Request pipeline, choose Add Step Below on the Start Pipeline to add a new step below the Log step.
A New Step dialog box appears, as shown in Figure 10-38. From the list, select XML Encrypt:
Click OK in the dialog box. The encryption step appears in the Request pipeline.
Click the Configure link for the XML Encrypt step you just created. The Configure pipeline step detail page appears, as shown in Figure 10-39:
Information that you need to provide on this page includes:
Keystore location (this is the location that was specified when the keystore was created)
Encryption keystore type (jks in the example)
Keystore password
Decryptor's public key alias
Encrypted content (BODY)
Additional details about the encryption
Click OK.
This completes the steps to encrypt the content that is being sent to the web service from the Oracle BPEL Process Manager client.
To define the decryption policy step:
In the Web Services Manager Control Console, display the component list by clicking Policy Management, then clicking Manage Policies.
From the list of Oracle Web Services Manager components, find the server agent associated with the web service. For example, the Authentication Agent is the server agent protecting the Credit Validation Service.
Click Policies and click the Edit icon corresponding to the default policy.
The agent policy appears. Scroll down to the Request pipeline, and click Add Step Below on the Start Pipeline to add a new step above the Log step.
From the New Step list, select XML Decrypt and press OK below the dialog box.
Click the Configure link for the new XML Decrypt step you just created. The Configure pipeline step detail page appears, as shown in Figure 10-40:
Information that you need to provide on this page includes:
Keystore location
Decryption keystore type (jks)
Keystore password
Decryptor's private key alias
Decryptor's private key password
Enforce encryption (true)
Click OK, then click Next, and click Save.
On the Policy Set page, click Commit at the top of the page.
This completes the steps to decrypt the message being received on the web service end.
Encryption and decryption of the content, as messages flow between the Oracle BPEL Process Manager process and the web service, can be observed by opening a TCP tunnel and watching the message traffic.
|
Note: You can also use the Oracle JDeveloper HTTP Analyzer to see the contents of SOAP messages passed when a proxy connects to a web service and the service returns a response. See Section 5.4, "Debugging, Testing and Analyzing Web Services in JDeveloper". |
To observe the message traffic:
Open the BPEL Developer Prompt from the Windows Start menu. For example:
From the Start menu, click All Programs, then click Oracle BPEL Process Manager 10.1.2, and click Developer Prompt.
At the developer prompt, enter the command:
obtunnel
This starts the TCP tunnel.
In the TCPMonitor Console, check that the Port and Host fields have the correct values, for example 1234 and 8888. If they do not, click Stop to set the values, and click Start.
Run the application to initiate message flow. For example, run SOA Order Booking Application to submit a customer order. The flow can be observed in the Oracle BPEL Process Manager Console Flow Viewer under the In-Flight Process Instances.
Look at the TCP tunnel window again. The top window shows that the message body is encrypted. This is how the message went across the network. The Oracle Web Services Manager Server Agent on the other end will decrypt it for the web service.
