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.
Approximately one hour
This OBE tutorial covers the following topics:
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.
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:
Before you perform this tutorial, you should:
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.
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 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.
|
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:
|
||||||||||
| 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.
|
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.
|
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.
|
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.
|
||||||||||||||
| 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.
|
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.
|
||||
| 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.
|
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.
|
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. |
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.
|
In this lesson, you learned about:
Place the cursor over this icon
to hide all screenshots.