Skip Headers
Oracle® Fusion Middleware Security and Administrator's Guide for Web Services
11g Release 1 (11.1.1.5)

Part Number B32511-05
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

14 Advanced Administration

This chapter includes the following sections:

Registering Web Services and Sources

A key feature of the Web services model is the ability to make Web services widely available and discoverable. UDDI is one approach to publishing and discovery of Web services that centralizes information about businesses and their services in registries. Another emerging alternative standard is the Web Services Inspection Language (WSIL) specification.

Oracle Enterprise Manager Fusion Middleware Control provides support for registering Web services that are published in WSIL documents and UDDI v3 registries. Any service that is available in a WSIL document or a UDDI v3 registry can be registered within Enterprise Manager.

You can also register meta information, or a profile, for sources of services to help you manage your registered services within Enterprise Manager. Once you register a source and assign it a logical name, you do not need to specify connectivity information, such as a URL for a WSDL, in the future. A domain can have multiple registered sources, and each registered source can have multiple registered services. Once you register a source, you can easily look up services that you can register to the source.

Service names and corresponding WSDLs must be unique within a registered single source. Once you have registered a service, an attempt to register another service with the same name, or a different name but the same WSDL URL as another service, is not valid.

Once you register a Web service, you can later, more conveniently, reference the service from a selection list within Enterprise Manager. For example, when testing a Web service as described in "Testing Your Web Services", instead of specifying a WSDL, you can click the Search icon and then select the WSDL from the list of registered services, as shown in Figure 14-1.

Figure 14-1 Selecting From a Registered Service

Description of Figure 14-1 follows
Description of "Figure 14-1 Selecting From a Registered Service"

UDDI Basics

Universal Description Discovery & Integration (UDDI) is an industry initiative that aims to enable businesses to quickly, easily, and dynamically find and carry out transactions with one another. A populated UDDI registry contains cataloged information about businesses; the services that they offer; and communication standards and interfaces they use to conduct transactions.

The owners of Web services publish them to the UDDI registry. Once published, the UDDI registry maintains pointers to the Web Service description and to the service. The UDDI allows clients to search this registry, find the intended service, and retrieve its details. These details include the service invocation point as well as other information to help identify the service and its functionality.

WSIL Basics

WSIL defines an Extensible Markup Language (XML) format for referencing Web service descriptions. These references are contained in a WSIL document, and refer to Web service descriptions (for example, WSDL files) and to other aggregations of Web services (for example, another WSIL document or a UDDI registry).

WSIL documents are typically distributed by the Web service provider. These documents describe how to inspect the provider's Web site for available Web services. Therefore, the WSIL standard also defines rules for how WSIL documents should be made available to consumers of Web services.

The WSIL model decentralizes Web service discovery. In contrast to UDDI registries, which centralize information on multiple business entities and services, WSIL makes it possible to provide Web service description information from any location. Unlike UDDI, WSIL is not concerned about business entity information, and does not require a specific service description format. It assumes that you know who the service provider is and relies on other standards for Web service description, such as WSDL.

Viewing Registered Sources and Web Services

Follow the steps in this section to view and edit a registered source and Web service.

  1. In the navigator pane, expand WebLogic Domain to show the domain in which you want to view the registered sources and Web services.

  2. Select the domain.

  3. Using Fusion Middleware Control, select WebLogic Domain then Web Services and then Registered Services. The Registered Sources and Services page appears, as shown in Figure 14-2.

    Figure 14-2 Viewing Registered Sources and Services

    Description of Figure 14-2 follows
    Description of "Figure 14-2 Viewing Registered Sources and Services"

    In the Sources table, you can view the following information about each registered source:

    • Name—Logical name for the source

    • Description—Description of the source

    • Source URL—Location of the source in URL format

    • Type—Source type: UDDI v3 registry import, WSIL import from file, WSIL import from URL

    • User ID—User ID for the external source

    You can customize the information that is displayed using the View menu. From this section of the page, you can also add new sources, edit or delete sources, register Web services for a source, and publish a Web service from a source to a predefined UDDI registry.

  4. Select a source in the Sources table.

    Each registered source can have multiple registered services. In the Services table, you can view the following information about the registered services imported from the selected source location:

    • Name—Name of the registered service

    • Description—Description of the service

    • Service location—Location of the service in URL format

    You can customize the information that is displayed using the View menu. You can also display the WSDL for the selected service and test the selected Web service.

Registering a Source

You can register Web service sources of the following types:

  • UDDI v3 registry import

  • WSIL import from URL

  • WSIL import from file

Follow the steps in this section to register a source.

To register a source

  1. In the navigator pane, expand WebLogic Domain to show the domain in which you want to register a Web service source.

  2. Select the domain.

  3. Using Fusion Middleware Control, select WebLogic Domain then Web Services and then Registered Services. The Registered Sources and Services page appears, as shown in Figure 14-2.

  4. Click Add to register a new source. The Register New Source page appears, as shown in Figure 14-3.

    Figure 14-3 Register New Source Page

    Description of Figure 14-3 follows
    Description of "Figure 14-3 Register New Source Page"

  5. Enter the following information for the new source.

    • Name—A logical name for the source.

    • Description—A description of the source.

    • Type—choose from one of three options: UDDI v3 registry import, WSIL import from URL, or WSIL import from File

      Additional information that you need to enter differs based on the option you select.

  6. If you selected UDDI v3 registry import, enter the following information:

    • In the Source URL field, enter the UDDI inquiry URL, for example, http://somehost/uddi/inquiry.

    • To allow the services to be published to a UDDI source (which is an external UDDI registry), select the Enable box and complete the fields as follows:

      • In the Publication URL field, enter URL location of the registry to which you want to publish the service.

      • In the Security URL field, enter the URL location of the security port required to access the registry.

      • In the User ID and Password fields, enter the security credentials required to access the registry.

  7. If you selected WSIL import from URL, enter the following information:

    • In the Source URL field, enter the location of the WSIL in URL form.

    • If a username and password are required to access the WSIL, select the Enable box in the Basic Authorization field. In the User ID and Password fields, enter the username and password.

  8. If you selected WSIL import from File, click Browse (next to the WSIL File field) to select the WSIL file to be imported.

  9. Click OK to register the source.

Registering Web Services from a UDDI Source

Follow the steps in this section to register Web services from a registered UDDI source.

  1. In the navigator pane, expand WebLogic Domain to show the domain in which you want to register a Web service.

  2. Select the domain.

  3. Using Fusion Middleware Control, select WebLogic Domain then Web Services and then Registered Services. The Registered Sources page displays, as shown in Figure 14-1.

  4. Select the UDDI source from which you want to register services. Note that the Type for a UDDI source is specified as UDDI v3 registry import.

  5. Select Register Web Services.

    The Register New Service page displays, as shown in Figure 14-4.

    Figure 14-4 Register New Service from UDDI Source

    Description of Figure 14-4 follows
    Description of "Figure 14-4 Register New Service from UDDI Source"

    The Register New Service page displays the source information, in read-only format, and a list of the services that are available in UDDI that you can register.

    You can filter the list of available services that are displayed using the Service Name and Service Key fields. For example, to find calculator services, enter calc in the Service Name field. Only services that contain the calc string, such as calculator services are displayed. The search is not case-sensitive.

    In the Services available in UDDI section of the page, you can view service details from UDDI for each service in the table by clicking the View Service Details icon. The Service Details from UDDI window displays information about the service such as the Service Name, Service Description, Service WSDL, Service Key, Business Key, and Service Location, among others.

    You can edit the details of a service by clicking the Edit icon, which allows you to change the name and description of the selected service.

  6. In the Services available in UDDI section of the page, select the service or services that you want to register from the source and click Register.

    A confirmation message displays indicating that the service was registered successfully.

Registering Web Services from a WSIL Source

Follow the steps in this section to register Web services from a registered WSIL source.

  1. In the navigator pane, expand WebLogic Domain to show the domain in which you want to register a Web service.

  2. Select the domain.

  3. Using Fusion Middleware Control, select WebLogic Domain then Web Services and then Registered Services. The Registered Sources and Services page displays, as shown in Figure 14-1.

  4. Select the WSIL source from which you want to register services. Note that the Type for a WSIL source is specified as either WSIL import from File or WSIL import from URL.

  5. Select Register Web Services.

    The Register New Service page displays, as shown in Figure 14-5.

    Figure 14-5 Register New Service from WSIL Source

    Description of Figure 14-5 follows
    Description of "Figure 14-5 Register New Service from WSIL Source"

    The Register New Service page displays the Source information, in read-only format, and a list of available services, if any, in the WSIL that you can register, shown in the Services Available in WSIL table. If there are any WSIL references in the WSIL, they are listed in the References Available in WSIL table.

    In the Services Available in WSIL table, you can edit the details of a service by clicking the Edit icon, which allows you to change the name and description of the selected service.

  6. To register a service available from the current WSIL, select the service in the Services Available in WSIL table and click Register.

    A confirmation message displays indicating that the service was registered successfully.

  7. If the current WSIL also references other WSIL URLs or references, expand References Available in WSIL to display them. You can register the referenced Web services as well.

    To register a service from a referenced WSIL instead of the current WSIL, click the Process icon for the reference in the References Available in WSIL table.

    If the WSIL parses successfully, a new source is registered and the current WSIL source is replaced by the referenced WSIL. The services available in the referenced WSIL source are listed in the Services Available in WSIL table. You can then register services from the referenced WSIL.

    Note:

    For each new source created, _n is appended to the parent source name. For example, if the parent source name is wsil_file_1, then referenced new sources are named wsil_file_1_1, wsil_file_1_2) with source type WSIL URL. The new sources are listed in the Sources table in the Registered Sources and Services page.

    If the WSIL does not parse successfully, an error message displays. Usually, in such cases, the system successfully registers the new source for the selected WSIL reference. However, because the system could not parse the WSIL document, the error message displays. Close the error dialog and click OK to return to the Registered Sources and Services page.

    WSIL parsing can fail if the reference is bad or it needs authorization credentials. You can enable authorization for the WSIL source as described in "Registering a Source".

    Note:

    When the system fails to retrieve Web services from a registered source, because of connection or other failures, the Register New Service page is displayed with read only information for the source, but does not show any Web services. In such cases, click OK in the error dialog, if an error dialog is displayed, then click OK in the Register New Service page to return to the Registered Sources and Services page. To troubleshoot, you can then view the registered sources through other means. For example, if the source is a:

    • WSIL URL source, copy the URL to a browser address bar to view its contents.

    • WSIL file source, examine the WSIL file using an XML editor.

    • UDDI source, try to access the UDDI registry directly to investigate.

    You can also review any related Enterprise Manager error logs.

Deleting a Web Service or Web Service Source

Follow the steps in this section to delete a Web service or a Web service source.

  1. In the navigator pane, expand WebLogic Domain to show the domain in which you want to delete a Web service.

  2. Select the domain.

  3. Using Fusion Middleware Control, select WebLogic Domain then Web Services and then Registered Services. The Registered Sources and Services page displays, as shown in Figure 14-2.

  4. Do one of the following:

    • To delete a source, select the source from the Sources table and click Delete.

      A confirmation message displays. Click OK to delete the source.

    • To delete a service from a source, select the source in the Sources table.

      The registered Web services are displayed in the Services table.

      Select the service to be deleted from the Services table and click Delete.

      A confirmation message displays. Click OK to delete the service.

Publishing Web Services to UDDI

You can publish Web services to UDDI from a registered UDDI source and from the Web services summary page for ADF, WebCenter, and Java EE applications. Registered UDDI sources are listed in the Registered Sources and Services page, which includes all sources and services registered in a domain. The Web services summary page lists the Web services in an application. The following procedures describe both methods.

Note:

You need to use a proxy to publish a service to UDDI, since this requires access to URLs outside of your firewall. For more information about the required proxy settings, see "Configuring the Proxy Server for UDDI".

Note:

If your services are already in Oracle Enterprise Repository (OER) then you should use the OER Exchange Utility to publish those services to Oracle Service Registry.

To publish a Web service to UDDI from a registered source:

  1. Navigate to the Registered Sources and Services page as described in "Viewing Registered Sources and Web Services".

  2. Select the source row in the Sources table and then Publish to UDDI.

    Figure 14-6 Registered Sources and Services Page with Publish to UDDI Selected

    Description of Figure 14-6 follows
    Description of "Figure 14-6 Registered Sources and Services Page with Publish to UDDI Selected"

  3. In the Publish Service to UDDI window, enter the information about the service to be published:

    • Service Name is the name of the Web service to be published to the UDDI registry. This field is required.

    • Service Description is a description of the selected Web service.

    • Service Definition Location is the URL location of the service definition. This field is required.

    • UDDI Source is the name of the UDDI source from which the service is to be registered. This field is read only.

    • Business Name is the name of the data structure in the UDDI registry. It is assumed that the business has already been registered in the UDDI. Choose the Business name from the list. This field is required.

      Figure 14-7 Publish Service to UDDI Window from a UDDI Source

      Description of Figure 14-7 follows
      Description of "Figure 14-7 Publish Service to UDDI Window from a UDDI Source"

  4. Click OK in the Publish Service to UDDI window.

    The system verifies that the service specified has a valid WSDL and that the UDDI registry has accepted the new entry or updated an existing one. If it is successful, a confirmation message displays and the service is published to the registry. Once the service is published in the UDDI, it becomes available to be registered to a source, as described in "Registering Web Services from a UDDI Source".

    Any errors during the operation will result in an error message.

    Note that you can only register the service to a source if it uses a unique WSDL.

To publish a Web service to UDDI from an application:

  1. Navigate to the Web Services summary page as described in "Navigating to the Web Services Summary Page for an Application".

  2. From the Web Service Details section of the page, select the service to be published.

  3. Select Actions, then Publish to UDDI. See Figure 14-8.

    Figure 14-8 Web Services Summary Page with Publish to UDDI Selected

    Description of Figure 14-8 follows
    Description of "Figure 14-8 Web Services Summary Page with Publish to UDDI Selected"

  4. In the Publish Service to UDDI dialog box (Figure 14-9), enter the information about the service to be published:

    • Service Name is the name of the Web service to be published to the UDDI registry. This field is required.

    • Service Description is a description of the selected Web service.

    • Service Definition Location is prepopulated with the URL location of the service definition (This field is read-only.)

    • UDDI Source is a logical name for the UDDI registry source. Choose the UDDI source from the list. This field is required.

      Note:

      The list contains the UDDI sources registered in the domain that have been enabled for publishing. For more information about registered sources, see "Registering Web Services and Sources".
    • Business Name is the name of the data structure in the UDDI registry. It is assumed that the business has already been registered in the UDDI. Choose the business name from the list. This field is required.

    Figure 14-9 Publish Service to UDDI Dialog Box

    Description of Figure 14-9 follows
    Description of "Figure 14-9 Publish Service to UDDI Dialog Box"

  5. Click OK to connect to the external UDDI registry and register the Web service.

    Upon successfully registering the service, a confirmation message displays. Any errors during the operation will result in an error message.

Configuring the Proxy Server for UDDI

To access URLs outside of your firewall, you must use a proxy to publish a service to UDDI.

Before starting Oracle WebLogic, you must set the Java system properties defined in Table 14-1. You can set them as environment variables, or in Oracle WebLogic startup files.

Table 14-1 Java System Properties Used to Specify the Proxy Server for UDDI

Property Description

proxySet=true

Flag that specifies that the WebLogic proxy properties should be used.

http.proxyHost=proxyHost

Name of the host computer on which the proxy server is running.

http.proxyPort=proxyPort

Port to which the proxy server is listening.

http.nonProxyHosts=hostname | hostname | ...

List of hosts that should be reached directly, bypassing the proxy. Separate each host name using a | character.


For example:

set PROXY_SETTINGS="-DproxySet=true -Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80 -Dhttp.nonProxyHosts=localhost|${HOST}|*.us.oracle.com" 

Auditing Web Services

Auditing describes the process of collecting and storing information about security events and the outcome of those events. An audit provides an electronic trail of selected system activity.

An audit policy defines the type and scope of events to be captured at run time. Although a very large array of system and user events can occur during an operation, the events that are actually audited depend on the audit policies in effect at run time. You can define component- or application-specific policies, or audit individual users.

You configure auditing for system components, including Web services, and applications at the domain level using the Audit Policy page. You can audit SOA, ADF, and WebCenter services.

Figure 14-10 Audit Policy Page

Description of Figure 14-10 follows
Description of "Figure 14-10 Audit Policy Page"

The audit policies table, at the center of the page, displays the audits that are currently in effect. The table includes the following information:

The following table summarizes the events that you can audit for Web services and the relevant component.

Table 14-2 Auditing Events for Web Services

Enable auditing for the following Web service events . . . Using this system component . . .
  • User authentication.

  • User authorization.

  • Policy enforcement, including message integrity, message confidentiality, and security policy.

Oracle Web Services Manager—Agent

  • Web service requests sent and responses received.

  • SOAP faults incurred.

Oracle Web Services

  • Oracle WSM policy creation, deletion, or modification.

  • Assertion template creation, deletion, or modification.

Oracle Web Services Manager

  • Oracle WSM policy attachment.

Oracle Web Services Manager— Policy Attachment


You can also audit the events for a specific user, for example, you can audit all events by an administrator.

For more information about configuring audit policies, see "Configuring and Managing Auditing" in Oracle Fusion Middleware Application Security Guide.

The following sections describe how to define audit policies and view audit data:

Configuring Audit Policies

Follow the steps in this section to configure audit policies.

  1. In the Navigator pane, expand WebLogic Domain.

  2. Click the domain for which you want to manage assertion templates.

  3. From the WebLogic Domain menu select Security > Audit Policy.

    The Audit Policy Settings page is displayed.

  4. Select and audit level from the Audit Level menu.

    Valid audit levels include:

    • None—Disables auditing.

    • Low—Audits a small scope of events. The subset of events is predefined individually for each component. For example, for a given component, Low may collect authentication and authorization events only.

    • Medium—Audits a medium scope of events (which is a superset of the events collected at the Low level). For example, for a given component, Medium may collect authentication, authorization, and policy authoring events.

    • Custom—Enables you to provide a custom auditing policy.

    You can view the components and applications that are selected for audit at each level in the audit policies list. For all audit levels other than Custom, the information in the audit policies list is greyed out, as you cannot customize other audit level settings.

  5. If you selected the Custom audit level, perform one of the following steps:

    • Select the information that you want to audit by clicking the associated checkbox in the Enable Audit column.

      You can audit at the following levels of granularity: All events for a component, all events within a component event group, an individual event, or a specific outcome of an individual event (such as success or failure).

      At the event outcome level, you can specify an edit filter. Filters are rules-based expressions that you can define to control the events that are returned. For example, you might specify an Initiator as a filter for policy management operations to track when policies were created, modified, or deleted by a specific user. To define a filter for an outcome level, click the Edit Filter icon in the appropriate column, specify the filter attributes, and click OK. The filter definition appears in the Filter column.

      Deselect the checkbox for a component at a higher level to customize auditing for its subcomponents. You can select all components and applications by checking the checkbox adjacent to the column name.

    • To audit only failures for all system components and applications, Select Failures Only.

      If selected, all checkboxes in the Enable Audit column are cleared.

  6. If required, enter a comma-separated list of users in the Always Audit Users text box.

    Specified users will always be audited, regardless of whether auditing is enabled or disabled, and at what level auditing is set.

  7. Click Apply.

    To revert all changes made during the current session, click Revert.

Managing Audit Data Collection and Storage

To manage the data collection and storage of audit information, you need to perform the following tasks:

  • Set up and manage an audit data repository.

    You can store records using one of two repository modes: file and database. It is recommended that you use the database repository mode. The Oracle Business Intelligence Publisher-based audit reports only work in the database repository mode.

  • Set up audit event collection.

For more information, see "Managing the Audit Store" in Oracle Fusion Middleware Application Security Guide.

Viewing Audit Reports

For database repositories, data is exposed through pre-defined reports in Oracle Business Intelligence Publisher.

A number of predefined reports are available, such as: authentication and authorization history, Oracle WSM policy enforcement and management, and so on. For details about generating and viewing audit reports using Oracle Business Intelligence Publisher, see "Using Audit Analysis and Reporting" in Oracle Fusion Middleware Application Security Guide.

For file-based repositories, you can view the bus-stop files using a text editor and create your own custom queries.

Managing the WSDL

In some cases, you might not want the Web service WSDL to be accessible to the public. You can enable or disable public access to the WSDL from the Web Service Endpoint page.

Note:

In some cases, a Web service client needs to access a WSDL during invocation. If public access to the WSDL is disabled, the client will need to have a local copy of the WSDL.

To manage the WSDL:

  1. Navigate to the Web Service endpoint configuration page, as described in "Configuring the Web Service Endpoint".

  2. On the Configuration tab, set the WSDL Enabled field to True or False to enable of disable public access to your WSDL, respectively.

  3. Click Apply.

Adding Security to a Running Client

Security policies can be attached to a running client using Oracle Enterprise Manager Fusion Middleware Control. You do not have to redeploy the client application to attach or detach policies from the client. See Chapter 8, "Attaching Policies to Web Services" for more information on how to attach policies using Fusion Middleware Control.

Configuring Platform Policy Properties

You can manage properties for the following components from the Platform Policy Configuration page:

To manage policy accessor, policy cache, policy interceptor, and identity extension properties:

  1. In the navigator pane, expand WebLogic Domain to view the domains.

  2. Select the domain for which you want to manage properties.

  3. Select WebLogic Domain> Web Services > Platform Policy Configuration.

    The Platform Policy Configuration page appears, as shown in Figure 14-11.

    Figure 14-11 Platform Policy Configuration Page

    Description of Figure 14-11 follows
    Description of "Figure 14-11 Platform Policy Configuration Page"

  4. Select the tab corresponding to the component for which you want to define properties:

Configuring a Web Service on a Remote Policy Manager and Tuning the Policy Cache

By default, the Oracle Web Services Manager (WSM) supports an auto-discovery feature that it uses to locate and connect to an Oracle WSM Policy Manager within the same WebLogic domain. In certain scenarios auto-discovery may not work as expected.

Note:

When the Oracle WSM Policy Manager is deployed on a server that is configured to use SSL, the auto-discovery mechanism will only attempt to connect to Policy Managers on other SSL-configured servers. To ensure that the secure connection is maintained, Policy Managers deployed on servers that are not configured for SSL are ignored.

You may want to disable the auto-discovery feature, for example, in the following scenarios:

For Oracle Infrastructure Web service policies, on the Platform Policy Configuration page:

To configure a Web service on a remote Oracle WSM Policy Manager and tune the policy cache:

  1. To access an Oracle WSM Policy Manager that is in a different domain—for example, if the Oracle WSM Policy Manager is in a domain that is different from the Web service client—enable cross-domain security between WebLogic Server domains, as described in "Enabling Cross Domain Security Between WebLogic Server Domains" in Securing Oracle WebLogic Server.

    Cross domain security establishes trust between two WebLogic domain pairs by using a credential mapper to configure communication between these WebLogic domains.

  2. Access the Platform Policy Configuration page, as described in "Configuring Platform Policy Properties".

  3. Select the Policy Accessor tab.

  4. Click Add to define a remote JNDI provider.

    In the Add Property window, specify the following values:

    1. In the Name field, enter the JNDI provider URL property as java.naming.provider.url.

    2. In the Value field, enter the JNDI provider's URL for the remote domain.

      This specifies the location of a running Policy Manager in a different domain in order to access that Policy Manager. If this property is not specified, the auto-discovery feature attempts to look up the Policy Manager in the same domain.

    3. Click OK.

  5. Click Add to define a corresponding csf-key credential property. In the Add Property window, specify the following values:

    1. In the Name field, enter the name of the JNDI provider's csf-key credential property as jndi.lookup.csf.key.

    2. In the Value field, enter the csf-key credentials.

      Because the Policy Manager is security enabled, the csf-key specifies the java.naming.security.principal and java.naming.security.credentials when using the JNDI URL to look up a Policy Manager.

    3. Click OK.

    For more information on storing, retrieving, and deleting credentials, see "Adding Keys and User Credentials to the Credential Store"

  6. Select the Policy Cache tab.

  7. To modify the policy cache property for Web service endpoints, select it and then click Edit. In the Edit Property window, you can edit the Value field to change the default amount for each property.

    1. cache.tolerance – Amount of time (in milliseconds) between refreshes of the policy cache. This ensures that the policy set retrieved from the Web service endpoint policy cache is the most current version (that is, it has not exceeded the cache.tolerance value). If it is determined that the policy set is stale, the updated policy set is retrieved from the Oracle WSM Policy Manager and refreshed in the Web service endpoint policy cache. The default is 60000 milliseconds (1 minute).

      Note: The refresh delay amount for Web service endpoints is aggregated with the value of the cache.refresh.repeat property (if any) on the Policy Accessor tab for the Oracle WSM Policy Manager. Therefore, you should verify whether this additional value produces the desired refresh delay when combined with the cache.refresh.repeat amount. For more information, see "Configuring Web Service Policy Retrieval".

    2. To add another property, click Add, and in the Add Property window, specify the necessary values.

    3. Click OK.

  8. To modify an existing property, select it and then click Edit.

  9. To delete an existing property, select it and then click Delete.

  10. Click Apply to apply the property updates.

Configuring Web Service Policy Retrieval

The Policy Accessor tab also enables you to configure the retrieval of Oracle WebLogic Web service policies from a repository. This includes specifying the repository accessor type (for example, classpath, local, or remote), repository location (JARs, directory, or host and port), account information (for a remote repository), retry logic (for high availability), and cache tuning.

  1. Access the Platform Policy Configuration page, as described in "Configuring Platform Policy Properties".

  2. Select the Policy Accessor tab.

  3. Click Add to add a policy retrieval property.

  4. Use the following table to specify the available property names and values in the Add Property window:

    Table 14-3 Properties in Add Property Window

    Element Description

    java.naming.provider.url

    JNDI URL that specifies the location of a running Oracle WSM Policy Manager in another domain. By default, this property is not specified. If this property is not specified, Oracle WSM auto-discovery attempts to look up the Policy Manager in the same domain.

    jndi.lookup.csf.key

    If the location of the Oracle WSM Policy Manager is provided in the java.naming.provider.url property, the jndi.lookup.csf.key provides credential configuration. Because the Oracle WSM Policy Manager is security enabled, the jndi.lookup.csf.key specifies the java.naming.security.principal and java.naming.security.credentials when using the JNDI URL to look up a Oracle WSM Policy Manager. By default, this property is not specified.

    You should configure this property when:

    • You want to specify an explicit account to connect with the Oracle WSM Policy Manager rather than the system account, OracleSystemUser, that is used by Oracle WSM by default.

    • The Authentication Provider and LDAP directory that is configured does not support system accounts used by Oracle WebLogic, but which Oracle WSM relies on by default. Therefore, a different account in the LDAP directory must be used.

    • There is no concept of default system accounts in a particular application server, and so the system cannot rely on system accounts.

    For more information on modifying the default user, see "Modifying the Default User".

    cache.refresh.initial

    Number of milliseconds to wait before initial cache refresh. The default is 600000 milliseconds (10 minutes).

    cache.refresh.repeat

    Number of milliseconds to wait between cache refreshes. The default is 600000 milliseconds (10 minutes).

    missing.retry.delay

    Number of milliseconds to wait before trying to retrieve a missing document. The default is 15000 milliseconds.

    usage.record.delay

    Number of milliseconds to wait before sending usage data. The default is 30000 milliseconds.

    failure.retry.count

    Number of times to retry after communication failure. The default is 2 retry attempts.

    failure.retry.delay

    Number of milliseconds to wait between retry attempts. The default is 5000 milliseconds.

    oracle.wsm.policymanager.accessor.IRepositoryAccessor

    Type of repository accessor class. The supported value is remote (Java EE).


  5. To modify an existing property, select it and then click Edit.

  6. To delete an existing property, select it and then click Delete.

  7. Click Apply to apply the property updates.

Tuning Web Service Security Policy Enforcement

The BindingSecurityInterceptor property on the Policy Interceptors tab allows you to tune security policy enforcement by adjusting the default message timestamp skews between system clocks, the time-to-live for nonce messages in the policy cache, and the message expiration time.

Perform the following steps to tune the security policy enforcement:

  1. Access the Platform Policy Configuration page, as described in "Configuring Platform Policy Properties".

  2. Select the Policy Interceptors tab.

  3. Select the BindingSecurityInterceptor security property on the list.

  4. To modify a BindingSecurityInterceptor security property, select it and then click Edit. In the Edit Property window, you can edit the Value field to change the default amount for each property.

    1. agent.clock.skew – Tolerance of time differences, in seconds, between client and server machines. For example, when timestamps are sent across in a message to a service that follows a different time zone, this property allows for the specified time tolerance. The default value is 300 seconds. Increase agent.clock.skew when:

      • The server's clock is ahead of the client's clock: If the server's clock is ahead of the client's clock then increase the agent.clock.skew. For example, if the server's clock is ahead of the client's clock by 10 minutes, then increase the server's agent.clock.skew to 10 minutes.

      • The client's clock is ahead of the server's clock: If the client's clock is ahead of the server's clock then increase the agent.clock.skew. For example, if the client's clock is ahead of the server's clock by 10 minutes, then increase the server's agent.clock.skew to 10 minutes.

    2. agent.nonce.ttl – Total time-to-live, in seconds, for nonce in the cache when nonce is sent across in a message. This property caches the nonce and once this duration is over, the nonce is removed from the cache. The default value is 28800 seconds.

    3. agent.expire.time – Duration of time, in seconds, before a message expires after its creation. This property is used in cases where a timestamp is sent across in the SOAP header to verify if the timestamp has expired or not. The default value is 300 seconds.

      If the message expires when received by the service even when there is no time difference between the client's and service's clocks, then the message expiry time must be increased. The message expiry time is derived from the values of agent.expiry.time and the expiry time in the incoming message, and is the lesser of the two. For example, if the server's agent.expiry.time is set to 5 minutes and expiry time in the incoming message expiry time is 6 minutes, then the agent.expiry.time at the service side must be increased. On the other hand, if the server's agent.expiry.time is 5 minutes and the incoming message expiry time is 3 minutes, then the expiry time in the incoming message (that is, at the client side) must be increased. A higher value of the agent.expiry.time may lead to a security vulnerability

    4. Click OK.

  5. To delete an existing property, select it and then click Delete.

  6. Click Apply to apply the property updates.

Defining Identity Extension Properties

The properties on the Identity Extension tab enable you to specify whether to enforce Web service policies by publishing the X509 certificate in the WSDL. If there is no need to publish the X509 certificate (for example, with SSL), you can override the default setting to avoid publishing the certificate. In addition, if the X509 is published, you can also specify whether to ignore the hostname verification feature.

For more information, see "Using Service Identity Certification Extension".

Defining a Trusted Distinguished Name List for SAML Signing Certificates

The Trusted SAML clients and Trusted STS servers tabs enable you to define a list of trusted distinguish names (DNs) for SAML signing certificates.

By default, Oracle WSM checks the incoming issuer name against the list of configured issuers, and checks the SAML signature against the configured certificates in the Oracle WSM keystore. If you define a trusted DNs list, Oracle WSM also verifies that the SAML signature is signed by the particular certificate(s) that is associated with that issuer.

Configuration of the trusted DNs list is optional; it is available for users that require more fine-grained control to associate each issuer with a list of one or more signing certificates. If you do not define a list of DNs for a trusted issuer, then Oracle WSM allows signing by any certificate, as long as that certificate is trusted by the certificates present in the Oracle WSM keystore.

Imporant Notes:

To defined a trusted DNs list for SAML signing certificates:

  1. Configure the trusted SAML issuers, as described in "Configuring SAML".

    Optionally, you can override the SAML issuer when attaching the policy. For more information, see "Attaching Client Policies Permitting Overrides".

  2. Access the Platform Policy Configuration page, as described in "Configuring Platform Policy Properties".

  3. Select the Trusted SAML clients or Trusted STS servers tab, depending on whether you want to define a trusted DNs list for trusted SAML clients or trusted STS servers.

  4. Add one or more trusted issuers within the Trusted Issuers section of the page.

    Use the Add button to add a new trusted issuer. For example: www.oracle.com.

  5. Select the trusted issuer for which you want to define a DN list in the Trusted Issuers section of the page.

  6. Add one or more trusted DNs in the Trusted SAML clients or Trusted STS servers area of the page. Use a string that conforms to RFC 2253. For example: CN=abc.

    For more information about RFC 2253, see http://www.ietf.org/rfc/rfc2253.txt.

Setting Up the Java Object Cache

To protect against replay attacks, the wss_username_token_client_policy and wss_username_token_service_policy policies provide the option to require a nonce in the username token. A nonce is a unique number that can be used only once in a SOAP request and is used to prevent replay attacks.

The nonce is cached to prevent its reuse. However, in a cluster environment you must take steps to synchronize this cache across the Managed Servers. Otherwise, a request sent to a Web service running on one server can be replayed and sent to another Managed Server, where it will be processed. Oracle WSM uses an instance of Java Object Cache (JOC) to cache the nonce.

You use the ORACLE_HOME/bin/configure-joc.py Python script to configure the JOC on all of the Managed Servers in distributed mode. The script runs in WLST online mode and expects the Administration Server to be up and running.

Note:

After configuring the Java Object Cache, restart all affected Managed Servers for the configurations to take effect.

Running the configure-joc.py Script

To enable the JOC in distributed mode, perform the following steps:

  1. Connect to the Administration Server using the command-line Oracle WebLogic Scripting Tool (WLST), for example:

    ORACLE_HOME/oracle_common/common/bin/wlst.sh
    $ connect()
    

    Enter the Oracle WebLogic Administration user name and password when prompted.

  2. After connecting to the Administration Server using WLST, start the script using the execfile command, for example:

    wls:/mydomain/serverConfig>execfile('ORACLE_HOME/bin/configure-joc.py')
    
  3. Configure JOC for all the Managed Servers for a given cluster.

    Enter 'y' when the script prompts whether you want to specify a cluster name, and also specify the cluster name and discover port, when prompted. This discovers all the Managed Servers for the given cluster and configures the JOC for each Managed Server. The discover port is common for the entire JOC configuration across the cluster. For example:

    Do you want to specify a cluster name (y/n) <y>
    Enter Cluster Name : Spaces_Cluster
    Enter Discover Port : 9988
    

    Here is a walkthrough for using configure-joc.py for HA environments:

    execfile('ORACLE_HOME/bin/configure-joc.py')
    .
    Enter Hostnames (eg host1,host2) : SOAHOST1, SOAHOST2
    .
    Do you want to specify a cluster name (y/n) <y>y
    .
    Enter Cluster Name : Spaces_Cluster
    .
    Enter Discover Port : 9988
    .
    Enter Distribute Mode (true|false) <true> : true
    .
    Do you want to exclude any server(s) from JOC configuration (y/n) <n> n
    

The script can also be used to perform the following JOC configurations:

  • Configure JOC for all specified Managed Servers.

    Enter 'n' when the script prompts whether you want to specify a cluster name, and also specify the Managed Server and discover port, when prompted. For example:

    Do you want to specify a cluster name (y/n) <y>n
    Enter Managed Server and Discover Port (eg WLS_Spaces1:9988, WLS_Spaces2:9988) : WLS_Spaces1:9988,WLS_Spaces2:9988
    
  • Exclude JOC configuration for some Managed Servers.

    The script allows you to specify the list of Managed Servers for which the JOC configuration "DistributeMode" will be set to 'false'. Enter 'y' when the script prompts whether you want to exclude any servers from JOC configuration, and enter the Managed Server names to be excluded, when prompted. For example:

    Do you want to exclude any server(s) from JOC configuration (y/n) <n>y
    Exclude Managed Server List (eg Server1,Server2) : WLS_Spaces1,WLS_Spaces3
    
  • Disable the distribution mode for all Managed Servers.

    The script allows you to disable the distribution to all the Managed Servers for a specified cluster. Specify 'false' when the script prompts for the distribution mode. By default, the distribution mode is set to 'true'.

Verify JOC configuration using the CacheWatcher utility. For more information, see "Running CacheWatcher" in Oracle Fusion Middleware High Availability Guide.

You can configure the Java Object Cache (JOC) using the HA Power Tools tab in the Oracle WebLogic Administration Console as described in "Using HA Power Tools" in the Oracle Fusion Middleware High Availability Guide.

Modifying the Default User

The Oracle WSM Agent run time uses the OracleSystemUser account by default to communicate to the server.

To configure a different default user, perform the following steps:

Configure an Authentication Provider

To configure an authentication provider, perform the following steps:

  1. Configure an authentication provider, as described in "Configure Authentication and Identity Assertion providers" in Oracle WebLogic Server Administration Console Help.

    • Select the name of the realm you are configuring (for example, myrealm).

    • In the Create a New Authentication Provider page, enter the name for Authentication Provider (for example, OID) and select the type Oracle Internet Directory Authenticator.

    • In the Settings section, set Control Flag to OPTIONAL.

    In the Provider Specific tab, enter the following:

    • Host: the LDAP provider URL

    • Port: port number

    • Principal: administrator user details (the new default user)

      For example, CN=orcladmin,CN=Users,DC=us,DC=oracle,DC=com

    • Credential: password for LDAP

    • Confirm Credential: password for LDAP

    • User Base DN

      For example, CN=Users,DC=us,DC=oracle,DC=com

    • Group Base DN

      For example, CN=Groups,DC=us,DC=oracle,DC=com

  2. Restart WebLogic Server.

Configure the Credential Store Provider

Configure the credential store provider as described in "Adding Keys and User Credentials to the Credential Store" with the following parameters:

Configure the Platform Policy Configuration

To configure the Platform Policy, perform the following steps:

  1. Log into Fusion Middleware Control with the new default user account.

  2. In the navigator pane, expand WebLogic Domain to view the domains.

  3. Select the domain for which you want to manage properties.

  4. Select WebLogic Domain > Web Services > Platform Policy Configuration.

    The Platform Policy Configuration page appears.

  5. Select the Policy Accessor tab.

  6. Click Add in the Policy Access Properties section.

  7. In the Add New Configure Property dialog, enter the following:

    • Enter the name jndi.lookup.csf.key. This property provides credential configuration (java.naming.security.principal and java.naming.security.credentials) and is used when an account in the LDAP directory is configured to connect with the Oracle WSM Policy Manager.

    • Enter the value (in this example, OID).

    Note:

    The csf-key that you specify in this step must match the csf-key specified for the Policy Manager administrative user in the credential store. For more information, see "Configure the Credential Store Provider".
  8. Click OK.

  9. Click Apply and restart WebLogic Server.

Modify the User's Group or Role

Oracle WSM Policy Manager uses the logical role (policy.Accessor) to secure EJBs that are accessed by the Oracle WSM Agent runtime to access the policies. By default, the policy.Accessor role is mapped to the groups OracleSystemGroup and Administrators. Oracle WSM Agent run time uses the OracleSystemUser identity to access wsm-pm. The new default user must either be included in the Administrator or OracleSystemGroup (if the groups exist), or be mapped to the logical role policy.Accessor (if the Administrator or OracleSystemGroup groups do not exist).

To ensure the user has the required role, perform the following steps:

  1. If the Administrator or OracleSystemGroup groups exist in the LDAP or identity store, perform the following:

    1. In LDAP, add the user that you would like to use as a default administrative user.

    2. In WebLogic Server Administration Console, ensure that the user exists in the Administrator group. For more information, see "Configure Authentication and Identity Assertion providers" in Oracle WebLogic Server Administration Console Help.

  2. If the Administrator or OracleSystemGroup groups do not exist in the LDAP or identity store, map the new user to the required logical role and redeploy the wsm-pm application using the modified deployment plan. To map the new user or existing users (belonging to a group other than Administrator or OracleSystemGroup), perform the following steps:

    1. Create a deployment plan for deploying wsm_pm.ear. Example 14-1 describes a sample deployment plan. A sample deployment plan, shipped with WebLogic, is available in the ORACLE_HOME/modules/oracle.wsm.pm_11.1.1/prov folder. Modify the section @to_be_replaced@ with the new user.

      Example 14-1 Sample Deployment Plan

      <?xml version='1.0' encoding='UTF-8'?>
      <deployment-plan xmlns="http://xmlns.oracle.com/weblogic/deployment-plan"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://xmlns.oracle.com/weblogic/deployment-plan
       http://xmlns.oracle.com/weblogic/deployment-plan/1.0/deployment-plan.xsd">
        <application-name>oracle.wsm.pm_11.1.1</application-name>
        <variable-definition>
          <variable>
            <name>SecurityRoleAssignment_ejbRole_PrincipalName</name>
            <value>@to_be_replaced@</value>
          </variable>
        </variable-definition>
        <module-override>
          <module-name>wsm-pmserver-wls.jar</module-name>
          <module-type>ejb</module-type>
          <module-descriptor external="false">
            <root-element>weblogic-ejb-jar</root-element>
            <uri>META-INF/weblogic-ejb-jar.xml</uri>
            <variable-assignment>
                   <name>SecurityRoleAssignment_ejbRole_PrincipalName</name>
              <xpath>/weblogic-ejb-jar/security-role-assignment/[role-name="policy.Accessor"]
      /principal-name</xpath>
                   <operation>replace</operation>
          </variable-assignment>
          </module-descriptor>
        </module-override>
      </deployment-plan>
      
    2. Redeploy the EAR.

      For more information, see "Deploying an Application with a Deployment Plan" in Deploying Applications to Oracle WebLogic Server.

Changing the JMS System User for Asynchronous Web Services

By default, the JMS System User is set as the OracleSystemUser. For most users, this default value is sufficient. However, if you need to change this value to a custom user in your security realm, you can do so by changing the value of the user in Oracle Enterprise Manager Fusion Middleware Control and in the WebLogic Server Administration Console as described in the following procedure.

To change the JMS System User:

  1. Access the Configuration tab on the Web Service Endpoint page for the asynchronous Web service as described in "Configuring Asynchronous Web Services".

  2. Enter the name of the custom user in the JMS System User field and click Apply. See Figure 14-12.

    Note:

    The custom user must exist in the security realm and have the permissions required to access the JMS resources.

    Figure 14-12 Setting the JMS System User for Asynchronous Web Services

    Description of Figure 14-12 follows
    Description of "Figure 14-12 Setting the JMS System User for Asynchronous Web Services"

  3. Access the WebLogic Server Administration Console. To do so from Fusion Middleware Control, select the domain in the navigator pane. From the WebLogic Domain menu, select WebLogic Server Administration Console.

  4. Log into the WebLogic Server Administration Console using a valid username and password with the required administrative privileges.

  5. Click Deployments in the Domain Structure pane and navigate to the corresponding service_AsynchRequestProcessorMDB or service_AsynchResponseProcessorMDB MDBs. In these MDB names, service is the name of the asynchronous service for which you are changing the user name.

  6. In the Change Center, select Lock & Edit.

  7. Select the MDB name for the request or response MDB. (You will need to update the user name for both the request and response MDBs.) In the Settings page, select the Configuration tab.

  8. In the Enterprise Bean Configuration section of the page, enter the custom user name in the Run As Principal Name field and click Save. See Figure 14-13.

    Note that the user name you enter in this field must match the user name you entered for the JMS System User in Fusion Middleware Control.

    Figure 14-13 WebLogic Server Administration Console Update for JMS System User

    Description of Figure 14-13 follows
    Description of "Figure 14-13 WebLogic Server Administration Console Update for JMS System User"

    The configuration changes need to be saved in a new deployment plan.

  9. Use the Save Deployment Plan Assistant to save the new deployment plan.

  10. Repeat steps 7 and 8 for the second MDB. The changes are automatically saved to the new deployment plan.

  11. In the Change Center, click Activate Changes.

  12. Redeploy the application. For more information, see Chapter 5, "Deploying Web Services Applications."