10.3 Authenticating Users with an Oracle Web Services Manager Server Agent

10.3.1 How to Register a Server Agent

You use the Web Services Manager Control Console to define Oracle Web Services Manager components such as server agents. The server agent acts as an enforcement point for security policies.

To configure a server agent component in Oracle Web Services Manager:

1. Point your browser to the Web Services Manager Control Console and log in using your single sign-on user name and password.

   The Web Services Manager Control Console is accessed with a URL of the form:

   http://<hostname>:port_number/ccore

   For example:

   http://itapps.globalcompany.com:8888/ccore

2. Click Add New Component.

3. On the Add New Component page, define:

   • Component name

   • Component type

   • Container type

   Figure 10-3 shows how a server agent named the Authentication Agent is defined:

   Figure 10-3 Adding a Server Agent

   
   

   Note that the component type is Server Agent.

4. Click Register. A confirmation page appears, as shown in Figure 10-4:

   Figure 10-4 Oracle WSM Component ID Confirmation

   
   

5. Make a note of this unique component ID for later use, and click OK.

   The new agent appears in the list of components.

10.3.2 What Happens When You Register an Agent

When you register an agent, Oracle WSM adds it to the server system registry. It also assigns a unique component ID to the agent, identifying it for all actions across your deployment.

10.3.3 How to Define the Policy Set for the Server Agent

A policy set consists of the explicit security and management policies that are to be implemented at a server agent. Oracle Web Services Manager offers a large selection of policy steps that can be combined as appropriate for specific security tasks.

For example, the Credit Validation Service can be protected by defining a policy set for the server agent consisting of:Oracle Web Services Manager

• A policy step to extract credentials contained in the SOAP security headers

• A policy step to authenticate the credentials

These policy steps must be defined at the agent's request pipeline.

You use the Web Services Manager Control Console to define the desired policies for the agent. After selecting the agent of interest, you can choose whether to update the default policy or add a new policy. Next, define one or more policy steps for the selected policy.

To define the policy set for the server agent:

1. At the Web Services Manager Control Console, click Policy Management, then click Manage Policies.

2. In the component list, select the agent for which the policy set is to be defined, and click Policies.

   The policy set for the agent is displayed.

   Oracle Web Services Manager provides a default policy for each agent or gateway component, and you have the ability to add additional policies to implement additional policy controls.

3. Click the Edit icon for the Default Policy. The Policy Definition page appears. Figure 10-5 shows the default policy pipeline for Authentication Agent:

   Figure 10-5 Policy Pipeline for the Default Policy

   
   
   

   The Web Services Manager Control Console displays the current contents of the policy, namely the steps in the Pre-Request, Request, Response, and Post-Response pipelines. A log step is enabled for the Request and Response pipelines by default.

4. In the request pipeline, implement credential authentication following the Log policy step. Click Add Step Below.

   A box appears at the appropriate location, allowing you to select a policy step as shown in Figure 10-6:

   Figure 10-6 Inserting a Policy Step at the Request Pipeline

   
   

5. Select Extract Credentials from the list, and click OK.

   The Policy Definition page reappears, showing the newly added Extract Credentials step.

6. Click Configure to define the properties for the Extract Credentials step, as illustrated in Figure 10-7:

   Figure 10-7 Defining Properties for the Extract Credentials Step

   
   
   

   On the Configure Step page shown in this figure:

   • The Enabled property is set to true by default.

   • The credentials location is set to WS-BASIC.

   The WS-BASIC location indicates that credentials are to be extracted from the standard UsernameToken as specified in the WS-I Basic Security Profile.

7. Click OK.

   The Policy Definition page reappears.

8. To add the second step for credential authentication, in the Extract Credentials row, click Add Step Below.

9. In the New Step box, select the step template named File Authenticate, and click OK.

   The request pipeline steps are displayed, and File Authenticate appears as the last step in the pipeline as shown in Figure 10-8:

   Figure 10-8 Request Pipeline for the Server Agent

   
   

10. To define properties for the new step, click Configure in the File Authenticate row.

    The Configure Step page appears, as shown in Figure 10-9:

    Figure 10-9 Defining Properties for the File Authenticate Step

    
    

11. Define these properties for the step:

    • Specify C:\admin\.htpasswd as the Passwd (password) file location.

    • Select md5 as the .htpasswd file format.

    
    

    Note: The step is enabled by default.

    
    

12. Click OK to complete the step definition. The Policy Definition page reappears.

13. Click Next to return to the policy page.

14. Click Save to save the step definitions.

15. Click Commit on the Policy Set page.

10.3.4 What Happens When You Define the Policy Set for the Agent

After you define one or more policies and their respective policy steps, they do not take effect immediately. You can continue to update or amend the policy configuration for the agent as needed, for example, by adding more policy steps to a policy pipeline. Once you are satisfied with the step definitions that have been saved, the agent's policy set is displayed as in Figure 10-10:

Figure 10-10 Committing Policy Changes

"Commit Policy" appears in red on the page, and the Oracle WSM Policy Manager is not updated with the new information until you click Commit. Once this is done, the component's policy set becomes effective, and remains in effect until subsequent changes are made and committed.

10.3.5 How to Set Up a File with User Credentials

In the previous step, Section 10.3.3, "How to Define the Policy Set for the Server Agent", a File Authenticate step was configured. As noted there, file-based authentication is typically used in test environments.

The format of the credential file is the same as the .htpasswd file format used by the Apache Web server. The password can be encoded in four forms: MD5, SHA1, plain text, or some mix of the three forms.

To set up a file with user credentials:

1. Use a text editor such as Notepad or vi to create the file. Add a single user name entry to the file, for example:

   bill:

   Save and close the file.

2. Use the Oracle WSM command-line tool, found at ORACLE_HOME\owsm\bin\wsmadmin, to complete the file.

   The command syntax is:

   wsmadmin md5encode user_name password htpasswdfile

   For example:

   C:\OracleAS_1\wsmadmin md5encode bill billspwd .htpasswd

   See the Oracle Web Services Manager Deployment Guide for details.

10.3.6 How to Install the Server Agent

The server agent must be installed as a J2EE agent. Oracle Web Services Manager provides the wsmadmin command-line Oracle Web Services Manager tool Oracle Web Services Manager for a number of administrative tasks, including agent registration.

To install the server agent as a J2EE agent:

1. At a Oracle Web Services Manager command prompt, navigate to the bin directory of the Oracle Web Services Manager component within your Oracle SOA installation. For example:

   ORACLE_HOME\owsm\bin

2. Using a text editor, edit the agent.properties file.

3. For the agent.component.id, insert the Component ID of the server agent that was registered. Figure 10-11 provides an example:

   Figure 10-11 Editing the agent.properties File

   
   

   Save the file.

4. At the command prompt, run the installAgent command:

   ORACLE_HOME\owsm\bin\wsmadmin installAgent Oracle-AS-password

   where Oracle-AS-password is the OC4J administrator password.

   The command is executed to build and install the J2EE server agent, as shown in Figure 10-12:

   Figure 10-12 Installing the Server Agent

   
   

10.3.7 How to Configure the Web Services Agent in Application Server Control

You must enable the Oracle Web Services Manager agent, Oracle Web Services Manager and associate it with the Oracle WSM Server Agent.

To Configure the web services Agent in Enterprise Manager:

1. Begin at the Oracle Enterprise Manager 10g Application Server Control Console home page.

   Under Members, click the home link.

2. Click Web Services. The list of web services is displayed.

3. Click the link for the ValidateCreditCardServiceSoapHttp web service. The main page for the service is displayed, as illustrated in Figure 10-13:

   Figure 10-13 Web Service Main Page

   
   

4. Click the Administration link to display the management features available for this web service, as shown in Figure 10-14:

   Figure 10-14 Web Service Administration Page

   
   

5. To enable the web services Agent feature, click Enable/Disable Features. The list of available features appears.

6. Move Web Services Agent to the Enabled Features list, as shown in Figure 10-15:

   Figure 10-15 Enabling the Web Services Agent

   
   

7. Click OK. The Web Service:ValidateCreditCardServiceSoapHttp page reappears, with the web services Agent enabled

   Note the confirmation message at the top of the page.

8. The final configuration step involves associating the component ID for the Oracle Web Services Manager Server Agent with this web service agent.

   On the ValidateCreditCardServiceSoapHttp web service management features page, shown in Figure 10-14, click the Edit Configuration icon for the Web Services Agent.

   The Edit Web Services Agent Configuration page appears.

9. In the Configuration Directory box, enter the component ID of the Oracle Web Services Manager Server Agent, as shown in Figure 10-16:

   Figure 10-16 Editing Web Services Agent Configuration

   
   

10. Click OK. A confirmation is displayed on the web service management features page.

10.3.8 What Happens When You Configure the Web Services Agent in Application Server Control

Configuring the web services agent in Application Server Control makes the Oracle WSM Server Agent known to the application server. The integration of Oracle WSM in the Oracle SOA Suite enables you to configure this management information simply by supplying the agent's Oracle WSM component ID. Note that the management information is completely separate from the web service, business logic, and client implementation.

10.3.9 How to Test the Authentication

The final step is to test the agent that you have configured for credential authentication.

To test the authentication:

1. Return to the Applications link of the OC4J home instance and expand the default application.

2. Click the link for the application of interest to display the application home page. In the example, this is the SOADEMO-CREDITSERVICE-CreditService-WS link.

3. Select the Web Services tab. The SOADEMO-CREDITSERVICE-CreditService-WS application contains a single web service, as shown in Figure 10-17:

   Figure 10-17 Available Web Services for Application

   
   

4. Click Test Service. A list of URLs appears, showing the sites that can be used to test the web service. For the Credit Validation Service, there is just one URL as shown in Figure 10-18:

   Figure 10-18 Test Web Service Page

   
   

5. Click Test Web Service. The service's test page is displayed.

6. Expand WS-Security. Input fields, such as the User Name and Password fields in the example, appear.

7. Select the Enable checkbox, and enter the user credentials and credit card information as shown in Figure 10-19:

   Figure 10-19 Entering Information for Web Service Test

   
   

   Click Invoke. A Test Result page appears.

8. You can validate the results by querying the Oracle Web Services Manager Oracle Web Services Manager logs. From the Web Services Manager Control Console, click Operational Management, then click Overall Statistics, and click Message Logs.

9. Click Search to display message logs, as shown in Figure 10-20:

   Figure 10-20 Oracle WSM Message Logs

   
   

   Note that two logs, a request log and a response log, were generated for the Credit Validation Service over the last hour.

10. Clicking the number in the Index column for the request log opens a page which displays the parameters that were passed in, as illustrated in Figure 10-21:

    Figure 10-21 Request Log Entry

    
    

    The response log entry shows that the credentials were validated as true, as in Figure 10-22:

    Figure 10-22 Response Log Entry

    
    

10.3.10 What Happens at Runtime

In the preceding example, Oracle Web Services Manager performed two key actions at runtime:

1. User credentials were extracted.

   Message credentials, typically user name and password combinations, are delivered in various ways: in the transport headers, as SOAP headers, or in the XML body. The example utilized the WS-BASIC soap security header, which extracts credentials from the standard UsernameToken specified in the WS-I Basic Security Profile.

   Oracle Web Services Manager provides other options for credential extraction. See the discussion of the Extract Credentials policy step in the Oracle Web Services Manager Administrator's Guide for more information.

2. The credentials were authenticated.

   In addition to the file-based authentication in the example, Oracle Web Services Manager supports authentication against LDAP directories and security data stores. Authentication may also be presented and verified with an X.509 certificate.

Oracle Web Services Manager provides a variety of credential management, authentication, authorization, message security, and other features. For Oracle Web Services Manager a discussion of available runtime actions, see the appendix for "Oracle WSM Policy Steps" in the Oracle Web Services Manager Administrator's Guide.

Error Handling

If policy execution (such as user authentication) fails, Oracle Web Services Manager returns a SOAP fault to the client.Oracle Web Services Manager

10.3.11 How to Configure Oracle BPEL Process Manager to Send a Username Token

To interact with a secured web service, the client must send SOAP messages containing valid security credentials. To achieve this, you can configure Oracle BPEL Process Manager to send username tokens that include the relevant WS-Security header tags in the bpel.xml file.

The following portion of bpel.xml, shown in Figure 10-23, illustrates how to enable a username token for the CreditValidationService partner link:

Figure 10-23 Enabling a Username Token

Here, credentials for the user jstein with password welcome1 are set by means of the wsseHeaders, wsseUsername, and wssePassword deployment descriptors; these properties will be validated by the authenticating Oracle Web Services Manager Server Agent.