Creating a Custom Policy Step in Oracle Web Services Manager (Oracle WSM)

Purpose

Oracle Web Services Manager (Oracle WSM) provides an extensibility point to define a custom policy step that can be executed as part of the request or response pipeline. The following Oracle by Example (OBE) tutorial provides details for creating a custom step. The custom step authenticates the user against a fixed set of username/password credentials configured in the policy step pipeline.

Duration

Approximately one hour

Topics

This OBE tutorial covers the following topics:

 Overview
 Prerequisites
 Custom Step Creation: Overview
 Compiling and Creating the Java Archive (JAR) File
 Creating and Registering an Oracle WSM Gateway
 Deploying the Custom Step
 Deploying a Web Service to Oracle Application Server
 Registering the CreditService Web Service to the Gateway
 Adding the Custom Policy Step to the Gateway
 Viewing the Secured Web Service's Web Services Description Language (WSDL)
 Testing the Security Implementation
 Adding Help Page for the Custom Step
 Summary
 Related Information

Viewing Screenshots

 Place the cursor over this icon to load and view all 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 provides an out-of-the-box (readily available with the product) list of common security policy steps (such as authentication, authorization, message encryption, message signing, and so on) that enables you to implement security policies for a registered Web service. Oracle WSM provides the extensibility for a developer to create custom steps. Custom steps are necessary when a specific functionality is not provided with the standard policy steps that come with the product. For example, an application may require the use of a type of authentication that is not available in the Oracle WSM product. In this situation, a custom authentication step must be created.

You can develop a custom step as follows:

  1. Build a JAR file that contains the compiled code of the custom step.
  2. Create an Extensible Markup Language (XML) configuration file for the custom step.
  3. Create a help file for the custom step.

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.
  2. Download and unzip the applications.zip file (contains the application files) into your working directory.

Back to Topic List

 

Custom Step Creation: Overview

In Oracle WSM, the policy is initialized when it is created for the first time, or when changes are made to it and the policy is committed. The init method of a policy step is called when the policy is initialized. You can customize the init method to contain any initialization steps that are necessary for the specific policy. The execute method is called each time a message arrives. This method contains the main logic, which accesses various parts of the message from the message context, and logs the information to a file. You must make sure that this method is thread-safe because multiple requests calling this function may be simultaneously executed by multiple threads. The destroy method would be used to perform clean up operations at the end of the life cycle of the step. This method is called when a policy is updated or during a graceful shutdown of the server.

Oracle WSM provides the following for creating a custom step:

A custom step has two parts:

Note : You can also create the HTML help pages for the custom step.

Back to Topic List

 

Compiling and Creating the JAR File

You need to package the custom step implementation classes in a JAR file. At a minimum, you would need to include the following JAR files to compile the custom step Java code. This is apart from the additional JAR files that your custom code depends upon.

ORACLE_HOME/owsm/lib/extlib/saaj.jar
ORACLE_HOME/owsm/lib/coresv-4.0.jar

1.

Open a command prompt window, navigate to the directory where you have extracted the application files ( %APPLICATION_HOME%), 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

Note: %APPLICATION_HOME% – The directory where the application files are extracted

2.

Change your current working directory to %APPLICATION_HOME%/CustomAuthStep and enter the following command:

ant

Note : The CustomAuthStep.jar file is generated in the %APPLICATION_HOME%/CustomAuthStep/dist/lib directory.

 

Back to Topic List

 

Creating and Registering an Oracle WSM Gateway

You would require an Oracle WSM component (a gateway or an agent) where you can add the custom step. Therefore, create and register an Oracle WSM gateway by using the Web Services Manager Control.

Note : In this tutorial, you use an Oracle WSM gateway to add the custom steps. The same procedure is also applicable for the Oracle WSM server agents and Oracle WSM client agents.

1.

Open any Internet browser and log in to the Web Services Manager Control by entering the following URL in the address bar:

http://localhost:8888/ccore

2.

Log in with the user ID oc4jadmin and password welcome1 (or the password that you specified at the time of SOA Suite installation).

 

3.

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

 

4.

In the Add New Component page, enter the following details and click the Register button:

Basic Parameters

Value

Component Name

MyGateway

Component Type

Gateway

Container Type Oracle Web Services Manager
Component URL http://localhost:8888/gateway

 

5.

Verify that the component has been successfully added. Click OK.

Note : Whenever you create a gateway with the C0003001 component ID, you do not have to explicitly install it. By default, the gateway.component.id property in the gateway-config-installer.properties file is set to C0003001. If the component ID is different, you need to edit the gateway-config-installer.properties file, which is located in the ORACLE_HOME\j2ee\home\applications\gateway\gateway\WEB-INF directory, and replace the value in the gateway.component.id field with the component ID of the gateway you want to install (for example, gateway.component.id=C0003006). Save the configuration file and restart the application server to start the gateway.

 

Back to Topic List

 

Deploying the Custom Step

Your task is to deploy the custom step to Oracle WSM Policy Manager. Execute the following steps to perform this task:

1 .

On the Web Service Manager Control page, expand Policy Management in the navigation menu and select Manage Policies.

 

4.

Click the Steps link in the row for the component ( MyGateway ) for which you want to add the custom step. The Step Management page displays a list of steps.

 

5.

Click the Add New Step button on the Step Management page. The Web Services Manager Control displays the Step Management/Add Step page.

 

6.

Click the Browse button and select the CustomStep.xml step template, which is located in the %APPLICATION_HOME%/CustomAuthStep directory.

Note: The CustomStep.xml is provided with the applications file.

 

7.

Click the Upload button on the Step Management/Add Step page. The Step Management page updates the list of available steps, including the newly added step.

 

8.

Copy the CustomAuthStep.jar file from the %APPLICATION_HOME%/CustomAuthStep/dist/lib directory to the %ORACLE_HOME%/owsm/lib/custom directory.

 

9.

Restart the SOA Suite.

 

Back to Topic List

 

Deploying a Web Service to Oracle Application Server

You use the Oracle Application Server Control tool to deploy the CreditService Web service application. 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 the SOA Suite installation).

 

3.

Click the home link on the Cluster Topology page.

 

4.

Click the Applications tab on the OC4J:home page.

 

5.

Click the Deploy button on the OC4J:home page under the Applications tab.

 

6.

Click the Browse button in the Archive section of the Deploy: Select Archive page. Select the CreditService.ear file located in the %APPLICATION_HOME%/Web service directory. Click the Next button.

 

7.

On the Deploy: Application Attributes page, specify the Application Name as CreditServiceApp and click the Next button.

 

8.

On the Deploy: Deployment Settings page, click the Deploy button.

 

9.

Verify that the application deployment was successful. Click the Return button.

 

Back to Topic List

 

Registering the CreditService Web Service to the Gateway

In this section, you register the CreditService Web service to the gateway that you have just created. By doing so, you are associating the gateway with the Web service that it will protect. To perform this task, execute the following steps:

1.

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

 

2.

Click the Services link of the MyGateway gateway.

 

3.

On the Gateways/List of Services page, click the Add New Service button.

 

4.

On the Add New Service page, enter the following service details and click the Next button.

Service Details

Value

Service Name

CreditService

Service Version 1.0
Service Description Validates a CreditCard
WSDL URL http://localhost:8888/CreditService/ValidateCreditCardServiceSoapHttp?WSDL
Service Protocol Accept the default HTTP(S).
Service Groups Accept the defaults

 

5.

On the Configure Messenger Step for New Service page, verify that the URL matches the URL you provided on the previous page. Accept the default values for the remaining fields and click Finish.

 

6.

On the Services page, click the OK button.

 

7.

On the Gateways/List of Services page, click the Commit link.

 

8.

On the Gateways page, click the OK button.

 

Back to Topic List

 

Adding the Custom Policy Step to the Gateway

Now that you have associated the CreditService Web service with the gateway, you add policies that will be used by the gateway to protect the service. In this section, you add the custom policy step to the policy pipeline of the CreditService Web service. To execute this task, perform the following steps:

1.

Expand Policy Management in the navigation menu and select Manage Policies.

 

2.

Click the Policies link of the MyGateway component.

 

3.

Click the Edit icon of the CreditService(1.0) 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 Extract Credentials from the Select Step Template drop-down list. Click OK.

 

6.

Click the Configure link in the Extract Credentials section.

 

7.

Modify the following value in the Credentials location property field and click OK.

Property Name

Value

Credentials location

WS-BASIC

 

8.

Click the Add Step Below link in the Extract Credentials policy step.

 

9.

In the New Step dialog box, select Custom authenticate step from the Select Step Template drop-down list. Click OK.

 

10.

Click the Configure link in the Custom authenticate step section to view the property details of the Custom authenticate step. The username and password properties of this custom step are used to validate the incoming username/password. In the CustomStep.xml file, they were set to test/test, which you can modify if necessary. Click OK.

 

11.

Scroll down and click the Next button.

 

12.

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

 

13.

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

 

Back to Topic List

 

Viewing the Secured Web Service's WSDL

To test the security policy implementation of the Web service, you should make a request to the Oracle WSM gateway with which the Web service is registered. You should get the WSDL URL of the Web service that is provided by Oracle WSM. Execute the following steps to view the secured WSDL definition of the CreditService Web service exposed by Oracle WSM.

1.

Expand Policy Management in the navigation menu and select Register Services.

 

2.

Click the Services link of the MyGateway gateway.

 

3.

On the Gateways/List of Services page, click the View Details icon of the CreditService service.

 

4.

On the Gateways/View Details page, copy the URL in the Service WSDL URL field. Click OK.

Note: You will use this URL in the next task.

 

Back to Topic List

 

Testing the Security Implementation

You simulate a Web service request to test that the CreditService is correctly secured. You make the request using the username and password that you added to the custom step configuration file ( CustomStep.xml). Execute the following steps to accomplish this task:

1.

Expand Tools in the navigation menu and select Test Page.

 

2.

On the Test Web Service page, paste the URL you copied into the Enter wsdl url text box and click the Submit Query button.

 

3.

On the Test Page/Test Web Service page, select the Include In Header check box in the WS-Security section. Expand the WS-Security node. Enter test in the User Name field and test in the Password field. In the CreditCard section, enter AMEX in the ccType field and 123456789 in the ccNum field. Click the Invoke button.

 

4.

On the Test Result page, click the Formatted XML link to view the result.

 

5.

Verify authentication failure by clicking the Test same WSDL again link. On the resulting page, enter information only for the CreditCard section. Do not select the Include In Header check box for WS-Security. If you select this, provide an incorrect username/password to verify authentication failure. Observe that the authentication fails.

Back to Topic List

 

Adding Help Page for the Custom Step

If you want to add a Help page for the custom step, perform the following task:

1.

Create the HTML Help page for the custom step and save it in the %ORACLE_HOME%/owsm/lib/app/ccore/help/steps directory. Name the file with the step name, replacing the spaces with underscores. For example, if the step name is " Custom authenticate step," then name the Help page " Custom_authenticate_step. html."

 

2.

Restart the SOA Suite.

 

3.

Navigate to the %ORACLE_HOME%/owsm/bin directory and execute the following command from the command prompt:

wsmadmin deploy <application server password> control

This command repackages the Web Services Manager application with the newly created Help page and redeploys it to the application server.

 

4.

Log in to the Web Services Manager Control and verify that help for your custom step is available.

 

Back to Topic List

 

Summary

In this lesson, you learned about:

 Custom Step Creation: Overview
 Compiling and Creating the JAR File
 Creating and Registering an Oracle WSM Gateway
 Deploying the Custom Step
 Deploying a Web service to Oracle Application Server
 Registering the CreditService Web service to the Gateway
 Adding the Custom Policy Step to the Gateway
 Viewing the Secured Web Service's WSDL
 Testing the Security Implementation
 Adding Help Page for the Custom Step

 

Related Information

 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