| Oracle® Web Services Manager Extensibility Guide 10g (10.1.3.3.0) Part Number E10300-01 |
|
|
View PDF |
| Oracle® Web Services Manager Extensibility Guide 10g (10.1.3.3.0) Part Number E10300-01 |
|
|
View PDF |
This chapter describes the custom authentication step which is provided as a sample with Oracle Web Services Manager (Oracle WSM) Release 3 (10.1.3.1), and describes procedures to compile, deploy, and run the step. Appendix A, "Custom Step Source Code and Step Template" contains the source code (Example A-1) and the step template (Example A-2) for this sample.
This chapter contains the following topics:
Oracle WSM Release 3 (10.1.3.1) includes a custom authentication step. The custom step authenticates the user against a user name and password that must be configured in the policy step pipeline. This step can be configured either in the gateway or the agent policy pipeline.
The sample step demonstrates the use of the following functions from the application programming interface (API):
Stepping Through the Lifecycle Using the init, execute, and destroy Methods
Accessing Data from the Message Context and Logging the Data
Setting Result Status and Authenticated User Name in the Message Context
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 step is called when the policy is initialized. You can put any initialization code in the init method. In the source code for the sample application, the init method creates the PrintWriter object. This object is used by the execute method to log messages.
The execute method is called each time a message arrives. This method contains the main logic, accessing various parts of the message from the message context and logging 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 performs a clean ending to the step's lifecycle. This method is called when a policy is updated or during a graceful shutdown of the server.
The source code for the sample application demonstrates how to use the PrintWriter stream with this method.
The execute method takes an object of type IMessageContext as a parameter. This object contains all the information about the message. It also has access to protocol-specific objects to retrieve protocol-specific information.
The source code for our sample application demonstrates retrieving the user name and password from a SOAP message sent as clear text inside a WS-Security header. For more information, refer to the WS-Security specification.
The client is required to send the user name and password inside the SOAP header. The code retrieves the user name and password from this header after retrieving the SOAP message from the message context. This is one example of sending and retrieving the user name and password; other methods include sending the user name and password in an HTTP header as basic authentication, or sending them in a SOAP message as a custom header.
Processing Stage Information
You can receive processing stage information using the API method messageContext.getProcessingStage().
Client IP address
You can retrieve Client IP information from messageContext by first retrieving the HttpServletRequest object and then calling the getHeader function on this object.
HttpServletRequest httpServletRequest = (HttpServletRequest)
messageContext.getProperty("javax.servlet.request");
String remoteAddr = httpServletRequest.getHeader("Host");
Note:
The source code assumes that the request is being sent through HTTP. The Oracle WSM Test Web Service page also uses HTTP to send requests.User locale
You can receive client user locale information using the API method messageContext.getUserLocale. This can be used to generate locale-specific faults or responses.
SOAP message processing stage information
You can receive processing stage information using the API method messageContext.getRequestMessage.
SOAP message user credentials
The source code for the sample application initializes the result object with a FAILED status:
result.setStatus(IResult.FAILED);
If the user is authenticated, the result status is set to SUCCEEDED:
result.setStatus(IResult.SUCCEEDED);
Custom steps need to set the invocation status only if the step involves authentication or authorization. The source code for the sample application sets one of the following authentication statuses on the InvocationStatus object of the message context.
messageContext.getInvocationStatus().setAuthenticationStatus(InvocationStatus.FAILED)
messageContext.getInvocationStatus().setAuthenticationStatus(InvocationStatus.SUCCEEDED)
The Oracle WSM Monitor uses this information to display authentication graphs or bar charts in the Web Services Manager Control.
The InvocationStatus class includes setInvocationStatus which sets overall status and setServiceStatus which sets service status. These functions are handled by the Oracle WSM runtime; however, the authentication or authorization result is known only by the step implementation and needs to be set in the step itself.
Example A-2 in Appendix A, "Custom Step Source Code and Step Template" lists the step template for the custom authentication step, CustomAuthenticationStep.xml.
The displayType has been set to "password" type (displayType="password", shown in bold in Example 2-1) for the password property. When configuring this step with a user name and password, the text entered in the password field is not displayed in clear text. The text is obfuscated and displayed as a series of asterisks (*). For password security, the password display type is recommended for all fields in your step.
Example 2-1 Defining displayType Properties in the Custom Step Template
<csw:PropertyDefinition name="Password" type="string" isRequired="true" displayType="password">
<csw:DisplayName>Password</csw:DisplayName>
<csw:Description>Password used for authentication</csw:Description>
<csw:DefaultValue>
<csw:Absolute>test</csw:Absolute>
</csw:DefaultValue>
</csw:PropertyDefinition>
You can define the fault code that the custom step throws inside the step definition file of the step. In the custom authentication step, the step throws the AuthenticationFault fault code. Define the fault code in the step template, CustomAuthenticationStep.xml, as follows:
<csw:Faults>
<csw:Fault xmlns:fns="http://www.example.com/ws/Faults">fns:AuthenticationFault</csw:Fault>
</csw:Faults>
Example A-1 in Appendix A, "Custom Step Source Code and Step Template" provides the code for the custom authentication step sample.
The file containing this code, CustomAuthenticationStep.java, can be found in the ORACLE_HOME\owsm\samples\customsteps\customAuthenticationStep directory.
This section describes the procedures to compile and run the custom authentication step. It includes the following topics:
The ORACLE_HOME/owsm/samples/customsteps/ directory contains the following files:
CustomAuthenticationStep.java – This file contains the source code for the custom step.
CustomAuthenticationStep.xml – This is the custom step template file.
build.xml – This is an Ant build script used to build the JAR file.
Perform the following steps to compile the custom authentication step and copy it to the directory where it will be run:
Set the ORACLE_HOME environment variable.
Enter the following commands to navigate to the directory that contains the custom authentication step and compile it:
cd ORACLE_HOME/owsm/samples/customsteps/customAuthenticationStep
ant -f build.xml
These commands generate the customAuthenticationStep.jar file.
Perform the following step to deploy the customAuthenticationStep.jar file:
Copy the customAuthenticationStep.jar file to the ORACLE_HOME/owsm/custom/ directory.
Perform the following steps to deploy the step template:
Log in to the Web Services Manager Control.
Follow the procedure described in "Defining a Custom Step Template", and add the customAuthenticationStepTemplate.xml step template.
Verify that you can view the custom authentication step in the list of available steps.
Restart Oracle Application Server.
Note:
When you copy a new jar file, or make changes to an existing jar file, you must restart Oracle Application Server.Perform the following steps to configure the step for use in a policy:
Add the step to the gateway or agent policy.
Configure the step by setting a user name and password as desired.
For example, you can enter owsmadmin as the user name and oracle as the password.
Save and commit the policy.
You are now ready to execute the policy.
To test the step, you can use any client that can generate a WS-Security header, or you can write your own client. Oracle WSM provides the Test Web Service page for generating a WS-Security header and performing the test. For more information on using the Test Web Service page refer to Oracle Web Services Manager Administrator's Guide.
Perform the following steps to send messages and execute the policy:
Send a message without a security header (do not select the WS-Security "Include in Header" box or enter the values for User Name and Password.).
The step gets executed and you see a "No Username supplied" fault message.
Perform the following steps to send a message with the user name and password in the SOAP header.
Access the Test Web Service page by selecting Tools, then Test Page from the navigation pane of Web Services Manager Control.
Enter the WSDL URL and click Submit Query.
When the page displays additional parameters (Figure 2-1), select the WS-Security Include in Header box and enter the values for User Name and Password.
This allows a SOAP header to be inserted in the SOAP envelope.
Figure 2-1 Test Web Service Page with Additional Parameters
Click Invoke to send the message as a SOAP request to the JAX-RPC Web service end point.
Enter an incorrect password and observe the response.
The Test Result page displays the response from the service and generates the security header shown in Example 2-2:
Example 2-2 WS-Security Header
<soap:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken>
<wsse:Username>owsmadmin</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-username-token-profile-1.0#PasswordText">oracle</wsse:Password>
</wsse:Username Token>
</wsse:Security>
</soap:Header>
Note:
In Example 2-2 the password is in clear text. For production environments you can use a mechanism such as #PasswordDigest instead of #PasswordText, as described in the WS-Security User Name Token profile.After you have sent the test messages, you can examine monitoring data from Web Services Manager Control to view authentication status and overall status:
From the navigation pane of Web Services Manager Control, click Operational Management, then click Snapshot (Figure 2-2).
Examine the Security Statistics authentication graph, and the rate of authentication failures.
Check the overall status of the Web services and view detailed information on Web services execution by clicking Overall Statistics.
For more information on viewing and managing performance of Web services, refer to Chapter 6, "Monitoring Oracle Web Services Manager" in Oracle Web Services Manager Administrator's Guide.
