14 Managing Oracle Web Services Manager Domain Configuration

This chapter describes how to configure the OWSM environment for authentication, message protection, and policy access for the domain. You can perform this configuration using either Fusion Middleware Control or WLST. Both methods are described.

This chapter includes the following sections:

14.1 Overview of OWSM Domain Configuration

OWSM provides the capability for an administrator to configure and manage the OWSM environment from a central location using the WSM Domain Configuration page in Fusion Middleware Control. From this page you can specify the Policy Manager connection information, cache refresh rates, nonce timeout, clock skew, OWSM keystore configuration, login modules, trusted SAML issuers, and other similar configuration parameters.

WLST commands also provide the ability to configure OWSM from the command line or using scripts. For more information about the WLST commands, see "About Managing OWSM Domain Configuration Properties Using WLST".

OWSM configurations are stored as documents in the OWSM Repository. When you install Fusion Middleware and create a domain that includes OWSM, the following configuration documents are created by default:

  • Bootstrap configuration document—Contains bootstrap information that is used to connect to the Policy Manager. If you modify the domain configuration (using Fusion Middleware Control or WLST) for a property that is also specified in the bootstrap configuration document, then the value specified in the bootstrap configuration is used only for the initial Policy Manager connection. For any subsequent access, the value in the domain configuration document is used.

    The bootstrap configuration document is stored in the domain_home/config/fmwconfig/wsm-config.xml file, where domain_home is the directory in which you installed your domain. By default this directory is Oracle_Home/user_projects/domains/base_domain.

  • Token issuer trust document—Contains the default trusted SAML issuer, www.oracle.com. This document is read-only. As you add trusted issuers and define DN lists, additional trust documents are created and stored in the repository.

  • Default configuration document—Contains all of the properties valid for the context with their default values. When you modify the default configuration, a configuration document for the domain is created and saved in the repository.

Note that the configuration performed using the WSM Domain Configuration page or using the custom configuration WLST commands applies at the domain level only, not to the application level.

In most cases, changes made to the OWSM configuration do not require a server restart. In certain situations, however, such as changing the keystore configuration or keystore type, changes to the configuration require a server restart. Additionally, if you modify any cache properties (such as cache.refresh) and you want the changes to go into effect immediately, you should restart the server.

14.2 Navigating to the WSM Domain Configuration Page

You manage the configuration of OWSM using the WSM Domain Configuration page. From this page you can view general information about the domain, and configure authentication, message security, and policy access properties. This topic describes the procedure to navigate to the WSM Domain Configuration page.

To navigate to the WSM Domain Configuration page:

  1. From the navigation pane, expand WebLogic Domain and select the domain to be configured.
  2. From the WebLogic Domain menu, select Web Services, then WSM Domain Configuration.

14.3 Viewing the General OWSM Domain Configuration Using Fusion Middleware Control

The General tab on the WSM Domain Configuration page provides basic information about the domain such as domain name and platform type, and enables you to provide a display name and description for the domain. This section describes the procedure to view this general information.

Version information about the domain is also shown, including the version number of the configuration, timestamp for the last update to the configuration, and the name of the user who last updated the domain.

Note:

Version information is updated only if you use a database-based OWSM Repository.

To view general information about the domain:

  1. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  2. Select the General tab.
  3. View the basic information about the domain, including Name, Platform Type, and Version Information.
  4. Optionally, provide a Display Name and Description for the configuration.
  5. Click Apply.

14.4 Configuring Domain-Level Authentication Using Fusion Middleware Control

The Authentication tab on the WSM Domain Configuration page provides the ability to configure SAML trust, the lifetime to be used for the issued token, and subject properties for JAAS subjects that are created after OWSM authentication. You can also configure SAML, SAML2, Kerberos, X509, and custom login modules.

The configuration details are described in the following sections:

14.4.1 SAML Trusted Issuers and DN Lists Using Fusion Middleware Control

The SAML Trust section on the Authentication tab enables you to define SAML trusted issuers and a list of trusted distinguished names (DNs) for SAML signing certificates.

The following topics provide information to help you configure SAML trusted issuers and DN lists:

To complete these tasks using WLST, see "Configuring SAML and JWT Trusted Issuers, DN Lists, and Token Attribute Rules Using WLST".

14.4.1.1 Overview of SAML Trusted Issuers and DN Lists

The list of SAML issuers that you define using the Authentication page becomes the default list that is applicable to all web services in this domain. In addition, when you add an issuer using this method, it does not require a restart of the domain.

By default, OWSM checks the incoming issuer name against the list of configured issuers, and checks the SAML signature against the configured certificates in the OWSM keystore. If you defined a trusted DNs list for a trusted issuer, OWSM also verifies that the SAML signature is signed by a certificate whose DN belongs to the trusted DN list.

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 OWSM allows signing by any certificate, as long as all the intermediate certificates and the CA certificate in the certificate chain for the signing certificate are present in the OWSM keystore. If the signing certificate is self-signed, it must be in the keystore itself.

Important Notes:

  • Using the Trusted STS and Trusted Clients tables in the SAML Trust section, you define the DNs of the signing certificates, not the certificates themselves.

  • The CA and intermediate certificates for the signing certificate must be in the OWSM keystore regardless of whether the signing certificate is in the keystore or passed in the message.

  • For two-way SSL:

    • The certificate needs to be imported into the trust store for the Java EE container.

    • The DN of the client SSL certificates are used for validation and must be present in the trusted DNs list.

  • In all cases, the signing certificates must be trusted by the certificates present in the OWSM keystore.

14.4.1.2 Adding SAML Issuers and Defining a Trusted DN List Using Fusion Middleware Control

Use the following procedure to add SAML issuers, define a trusted DN list for SAML signing certificates, or to add a DN to the DN list for an issuer:

  1. Access the WSM Domain Configuration page, as described in Navigating to the WSM Domain Configuration Page
  2. Select the Authentication tab.
  3. In the SAML Trust section of the page, shown in Figure 14-1, do one of the following:
    • To add a trusted issuer and define a trusted DN list for trusted STS servers, click Add in the Trusted STS table. Use this list for SAML HOK and SAML bearer.

    • To add a trusted issuer and define a trusted DN list for trusted clients, click Add in the Trusted Clients table. Use this list for SAML sender vouches.

  4. In the Issuer Name column, enter a trusted issuer, for example www.example.com. The default value for the predefined SAML client policies is www.oracle.com.
  5. In the Issuer DN column, enter the DN list for the trusted issuer. Use a string that conforms to RFC 2253. For example, the trusted DN for the trusted issuer www.oracle.com is CN=weblogic, OU=Orakey Test Encryption Purposes Only, O=Oracle, C=US. To add more than one DN for an issuer, separate each DN with a semicolon (;), as shown in Figure 14-1.

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

    Figure 14-1 SAML Trust Section of Authentication Tab



  6. Optionally, configure token attribute rules for the trusted DN, as described in "Configuring Token Attribute Rules for Trusted Issuers Using Fusion Middleware Control".
  7. Optionally, add additional trusted issuers and DN lists. To do so, repeat steps 3 through 6.
  8. To add a DN to the DN list for a trusted issuer, select the trusted issuer in the table and append the DN to the list of DNs in the Issuer DN column. Be sure to separate each DN by a semicolon (;).
  9. When you have finished configuring the necessary issuers and DN lists, click Apply.
14.4.1.3 Deleting Trusted Issuers, DNs, or DN Lists Using Fusion Middleware Control

You can delete issuers, a DN, or a DN list by performing one of the following actions:

  • To delete a trusted issuer and the DN list, select the row containing the issuer to be deleted and click Delete.

  • To delete a DN from the DN list, select the row for the trusted issuer and delete the DN from the list.

  • To delete a DN list, clear the Issuer DN field for the DN to be deleted. Note that any configured token rules are also deleted.

14.4.2 Configuring JWT Trusted Issuers and DN Lists Using Fusion Middleware Control

The JWT Trust section on the Authentication tab enables you to define JWT trusted issuers and a list of trusted distinguished names (DNs) for JWT signing certificates.

The following topics provide information to help you configure JWT trusted issuers and DN lists:

To delete issuers, a DN, or a DN list, "Deleting Trusted Issuers, DNs, or DN Lists Using Fusion Middleware Control".

To complete these tasks using WLST, see "Configuring SAML and JWT Trusted Issuers, DN Lists, and Token Attribute Rules Using WLST".

14.4.2.1 About JWT Trusted Issuers and DN Lists

The list of JWT issuers that you define using the Authentication page becomes the default list that is applicable to all web services in this domain. In addition, when you add an issuer using this method, it does not require a restart of the domain.

By default, OWSM checks the incoming issuer name against the list of configured issuers, and checks the JWT signature against the configured certificates in the OWSM keystore. If you defined a trusted DNs list for a trusted issuer, OWSM also verifies that the JWT signature is signed by a certificate whose DN belongs to the trusted DN list.

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 OWSM allows signing by any certificate, as long as all the intermediate certificates and the CA certificate in the certificate chain for the signing certificate are present in the OWSM keystore. If the signing certificate is self-signed, it must be in the keystore itself.

14.4.2.2 Adding JWT Issuers and Defining a Trusted DN List Using Fusion Middleware Control

This section describes the procedure to add JWT issuers, define a trusted DN list for JWT signing certificates, or to add a DN to the DN list for an issuer.

To add JWT issuers, define a trusted DN list:

  1. Access the WSM Domain Configuration page, as described in Navigating to the WSM Domain Configuration Page.
  2. Select the Authentication tab.
  3. In the JWT Trust section of the page, shown in Figure 14-1, click Add in the Trusted Issuer table, to add a trusted issuer and define a trusted DN list.
  4. In the Issuer Name column, enter a trusted issuer, for example www.example.com. The default value for the predefined JWT client policies is www.oracle.com.
  5. In the Issuer DN column, enter the DN list for the trusted issuer. Use a string that conforms to RFC 2253. For example, the trusted DN for the trusted issuer www.oracle.com is CN=weblogic, OU=Orakey Test Encryption Purposes Only, O=Oracle, C=US. To add more than one DN for an issuer, separate each DN with a semicolon (;), as shown in Figure 14-1.

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

    Figure 14-2 JWT Trust Section of Authentication Tab



  6. Optionally, configure token attribute rules for the trusted DN, as described in "Configuring Token Attribute Rules for Trusted Issuers Using Fusion Middleware Control".
  7. Optionally, add additional trusted issuers and DN lists. To do so, repeat steps 3 through 6.
  8. To add a DN to the DN list for a trusted issuer, select the trusted issuer in the table and append the DN to the list of DNs in the Issuer DN column. Be sure to separate each DN by a semicolon (;).
  9. When you have finished configuring the necessary issuers and DN lists, click Apply.

14.4.3 Configuring Token Attribute Rules for Trusted Issuers Using Fusion Middleware Control

There are increasing requirements to control which users and user attributes are accepted and processed for a particular trusted SAML or JWT token issuer. Token attribute rules allow you to define additional security constraints for the trusted STS server and for the trusted SAML client. Token attribute rules can be defined on top of a trusted DN. For each trusted DN configured for an issuer, a token attribute rule can be configured and applied.

Each rule has two parts: a name ID and an attributes part for user attributes that a DN for a trusted issuer can assert. The name ID and each attribute in the attributes part can contain a filter with multiple values or value patterns to provide constraints for the value of the name ID or the attribute that the DN can assert.

To define token attribute rules using Fusion Middleware Control:

  1. Define a DN list for a trusted issuer as described in "SAML Trusted Issuers and DN Lists Using Fusion Middleware Control".
  2. Select the Issuer DN in the table and click Configure Token Rule.
  3. In the Token Rule page, click Add to add attributes and filters for the DN.

    The Attribute field is prepopulated with the value name-id.

    Note:

    Only the first row is prepopulated with the value name-id in the Attribute field. When you click Add for subsequent rows, you need to enter a value in the Attribute field.

  4. In the Filters field, enter the attribute filter values to create the token attribute rule.

    The value that you add in the Filter field can be a complete name, such as yourTrustedUser. You can also enter a name pattern with a wildcard character (*), such as yourTrusted*. If you specify multiple attribute filters, each filter should be separated by a semicolon (;).

  5. To edit an existing attribute rule or filter, select the appropriate field in the table and make the required changes.
  6. To delete an attribute rule, select the row containing the rule to be deleted and click Delete.
  7. Click OK to save your changes and return to the WSM Domain Configuration page.
  8. When you have finished configuring the necessary changes, click Apply.

14.4.4 Configuring the Lifetime for the Issued Token Using Fusion Middleware Control

You can specify the lifetime to be used for the issued token when the request message is sent to the Security Token Service (STS).

If the STS sends the token with a different expiry, the runtime looks at the actual expiry of the token and only caches the token for that time. For more information, see "Understanding Token Lifetime and Token Caching".

The default for this property is 28800000 milliseconds (8 hours). To modify the default value, do one of the following:

  • Enter the desired value directly into the Issued Token Lifetime field.

  • Use the up/down arrows to increase or decrease the default value.

14.4.5 Configuring the SAML and SAML2 Login Modules Using Fusion Middleware Control

You can configure the SAML and SAML2 login modules from the OWSM Domain Configuration page.

The SAML policies have associated login modules, as determined by the assertions that make up the policy. When you attach a SAML policy to a web service, you can edit the login module and make any needed changes.

You can configure the following SAML login modules from the OWSM Domain Configuration page:

  • saml.loginmodule—The SAML login module is a Java Authentication and Authorization Service (JAAS) login module that accepts SAML assertions for a login. The SAML login module enables the web services to run using the login context of the principal created from the SAML assertion.

  • saml2.loginmodule—The SAML2 login module is a JAAS login module that accepts SAML2 assertions for a login. The SAML2 login module enables the web services to run using the login context of the principal created from the SAML2 assertion.

Note:

The configuration performed on this page takes precedence over any configuration performed in the OPSS login module page.

To configure the SAML login modules in OWSM:

  1. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  2. Select the Authentication tab.
  3. In the SAML or SAML2 Login Module section of the page, set the following properties as appropriate for your environment:
    • Allow Virtual User—Select this property to allow the SAML subject to be treated as a virtual user. If enabled, the user is not mapped to the actual user in the identity store. The subject is populated only with the username from the SAML subject. Because the subject is treated as a virtual user, identity store configuration is not required and the Authentication Provider is not invoked for all SAML policies in the domain using this login module.

      If this property is not enabled (the default), the username in the SAML subject is mapped to the actual user in the identity store. The user roles and subject are created with username and roles specified in the identity store.

    • Domain Name Mapping Attribute—If the Name Identifier Format is set to X509SubjectName in the SAML client policy, you can specify which part of the certificate DN to use for asserting the user against the identity store. The default for this property is CN.

    • Add Assertion To Subject—Specify if the SAML assertion should be added to the authenticated subject as a private credential. The default is true. If you set this property to false (clear the checkbox), then the assertion is not added to the authenticated subject.

  4. Click Apply.

For details about setting these properties using WLST, see "Configuring the SAML and SAML2 Login Modules Using WLST".

14.4.6 Configuring the Kerberos Login Module

The Kerberos policies have an associated JAAS login module that authenticates users using Kerberos protocols. The Kerberos login module has optional properties that you can configure in OWSM. The configuration specified in the OWSM configuration takes precedence over any Kerberos login module configuration in OPSS.

To configure the Kerberos login module in OWSM:

  1. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  2. Select the Authentication tab.
  3. In the Kerberos section of the page, set the following properties as appropriate for your environment:
    • Keytab file location—Specify the file name of the keytab to get the secret key for the principal. The default value is ./krb5.keytab.

    • Principal—Specify the name of the principal to be used. The principal represents a specific entity to which a set of credentials are assigned. It can be a simple username, such as testuser, or a service name such as HOST/localhost. You can use the principal option to set the principal when there are credentials for multiple principals in the keytab or when you want a specific ticket cache only. The default value is HOST/localhost@EXAMPLE.COM.

    • Class Name—Specify the login module to be used by OWSM. If no value is specified, at runtime one of the following default values will be used for the Kerberos login module Class Name, depending on the platform on which you are running:

      • com.sun.security.auth.module.Krb5LoginModule (Oracle)

      • com.ibm.security.auth.module.Krb5LoginModule (IBM)

    • Use Keytab—Specifies whether the module will get the principal's key from the keytab. If the keytab is not set, then the module will locate the keytab from the Kerberos configuration file. If it is not specified in the Kerberos configuration file, then it will look for the file <user.home><file.separator>krb5.keytab.

      Select the checkbox to set to true, that is, to get the principal's key from the keytab.

    • Store Key—Specifies whether the principal's key is stored in the Subject's private credentials.

      Select the checkbox to set to true, that is, to store the principal's key in the Subject's private credentials.

    • Do Not Prompt for Credentials—Specifies whether you will be prompted for the password if credentials cannot be obtained from the cache or keytab. When this property is selected, authentication will fail if credentials can not be obtained from the cache or keytab.

      Select the checkbox to set to true, that is, to be prompted for the password if credentials cannot be obtained from the cache or keytab.

  4. Click Apply.

For details about setting these and other Kerberos login module properties using WLST, see "Configuring the Kerberos Login Module Using WLST".

14.4.7 Configuring Subject Properties Using Fusion Middleware Control

The JAAS subject that is created after OWSM authentication is populated with usernames and roles, including the authenticated role, anonymous role, and application roles.

For more information about these roles, see "Understanding Users and Roles" in Securing Applications with Oracle Platform Security Services.

OPSS supports subject properties for these roles that can be configured in OWSM and passed to OPSS with each invocation. The configuration defined in OWSM applies to all subjects created in OWSM only. It does not affect any subjects created using the OPSS login modules.

To configure subject properties in OWSM:

  1. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  2. Select the Authentication tab.
  3. In the Subject Properties section of the page, set the following properties as appropriate for your environment:
    • Remove Anonymous Role from Subject—Specify whether the anonymous role is removed from the subject created in OWSM. By default, this property is disabled (set to false), indicating that the subject will retain the anonymous role after authentication.

      Select the checkbox (set to true) to specify that the anonymous role will be removed from the subject after authentication.

    • Authenticated Role to Subject—Specify whether the authenticated role is included in the subject created in OWSM. By default, this property is enabled (set to true) to indicate that the authenticated role is included in the subject.

      Clear the checkbox (set to false) if the authenticated role is not to be included in the Subject.

    • Application Role to Subject—Specify whether the application role is added to the subject created in OWSM. By default, this property is enabled (set to true), indicating that the application role is added to the subject.

      Clear the checkbox (set to false) to specify that the application role is not added to the subject.

  4. Click Apply.

For details about setting these properties using WLST, see "Configuring Subject Properties Using WLST".

14.4.8 Configuring the X509 Login Module Using Fusion Middleware Control

The X509 login module has optional properties that you can configure in OWSM. The configuration specified in the OWSM configuration takes precedence over any X509 login module configuration in OPSS.

To configure the X509 login module:

  1. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  2. Select the Authentication tab.
  3. In the X509 section of the page, set the following property as appropriate for your environment:
    • Domain Name Mapping Attribute—Enter the desired mapping attribute for a login using DN. The default for this property is CN, but you can specify any part of the certificate DN to use for asserting the user against the identity store. The value that you specify is passed to OPSS with each invocation of the login module. The DN string should conform to RFC 2253.

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

  4. Click Apply.

14.4.9 Creating Custom Login Modules

You can create custom login modules in the OWSM configuration system using Fusion Middleware Control.

For details about creating a login module, see the Java Authentication and Authorization Service (JAAS) LoginModule Developer's Guide at http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASLMDevGuide.html.

To create a custom login module:

  1. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  2. Select the Authentication tab.
  3. In the Custom Login Module section of the page, click Create.
  4. In the Create Login Module page, enter a name and the classname for the login module in the Name and Class fields, respectively. Optionally provide a description of the login module in the Description field.

    For example, to configure the Keystore login module, enter Keystore Login Module in the Name field and com.sun.security.auth.module.KeyStoreLoginModule in the Class field.

  5. To add custom properties, click Add and provide a name and value for the property. Repeat until you have added all the required properties. To delete a property, select the row and click Delete.

    For example, if you are configuring the Keystore Login Module, you can add a keyStoreAlias property, as shown in Figure 14-3.

    Figure 14-3 Custom Login Module Page

    Description of Figure 14-3 follows
    Description of "Figure 14-3 Custom Login Module Page"
  6. Click OK to create the login module.
  7. Click Apply.

14.5 Domain-Level Message Security Configuration Using Fusion Middleware Control

The Message Security tab on the WSM Domain Configuration page provides the ability to configure the OWSM keystore, tune security policy enforcement, specify if the public certificate should be published in the WSDL, and configure hostname verification and secure conversation.

The configuration details are described in the following sections:

14.5.1 OWSM Keystore Configuration Using Fusion Middleware Control

OWSM provides support for KSS, JKS, HSM, and PKCS11 keystores. After you create the keystores, you need to configure OWSM so that it can access and use the keystore.

Note:

There is one OWSM keystore per domain, and it is shared by all web services and clients running in the domain.

Note that there is one OWSM keystore per domain, and it is shared by all web services and clients running in the domain.

The following sections describe how to configure OWSM for each keystore type:

14.5.1.1 Configuring OWSM to Use the KSS Keystore

You can configure OWSM to use the KSS keystore using the Fusion Middleware Control.

To configure OWSM to use the KSS keystore, perform the following steps:

  1. Create the keystore as described in "Understanding OPSS Keystore Service for Message Protection".
  2. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  3. Select the Message Security tab.
  4. In the Keystore section of the page, select KSS as the Keystore Type.

    The KSS keystore settings are displayed, as shown in Figure 14-4.

    Figure 14-4 KSS Keystore Section of Message Security Page



  5. Enter the path to the keystore using the format kss://stripeName/keystoreName. For example: kss://owsm/keystore.

    Note:

    This field is case sensitive.

  6. Specify the sign and encrypt alias as follows:
    • For the Sign Alias, select the alias name from the menu. The value you select here must match the value in the keystore. For example, orakey.

    • For the Encrypt Alias, select the alias name from the menu. The value you select here must match the value in the keystore. For example, orakey.

    Note:

    The alias names are only available in the menus if they exist in the keystore specified in the Path field. If the aliases do not exist in the keystore, the menu is blank.

  7. Click Apply to accept the changes.
  8. If you are configuring the keystore for the first time, a server restart is not required. If, however, you are changing the keystore or keystore configuration, you must restart the server.

Note:

If you do not use the default keystore name for the KSS keystore (kss://owsm/keystore), you must grant permission to the wsm-agent-core.jar in OPSS. For more information about granting permissions, see "Setting the Java Security Policy Permission" in Securing Applications with Oracle Platform Security Services.

14.5.1.2 Configuring OWSM to Use the JKS Keystore

You can configure OWSM to use the JKS Keystore using Fusion Middleware Control.

When you configure OWSM to use the JKS keystore, entries are created in the credential store for the credential map oracle.wsm.security, and any keys that you define. (For details about configuring the credential store, see "Adding Keys and User Credentials to Configure the Credential Store".)

To configure OWSM to use the JKS keystore:

  1. Create the keystore as described in "Understanding Java Keystore for Message Protection".
  2. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  3. Select the Message Security tab.
  4. In the Keystore section of the page, select JKS as the Keystore Type.

    The JKS keystore settings are displayed, as shown in Figure 14-5.

    Figure 14-5 JKS Section of Message Security Key Store Page



  5. In the left column, provide the path to the keystore, the keystore key, and the keystore password as follows:
    • In the Path field, enter the path and name for the keystore that you created as described in "Generating Private Keys and Creating the Java Keystore". For example, if you named the keystore default-keystore.jks, enter ./default-keystore.jks. The location in this example is relative to the domain_name/config/fmwconfig directory. Alternatively, you can specify the absolute path to the keystore. If you used a different name or location for the keystore, enter those values instead.

    • Do one of the following:

      • If a keystore password key exists in the credential store, select it from the Key menu. If you select a key from the menu, the Password fields are disabled and the credentials associated with the selected key will be used.

      • If the keystore password key is not displayed in the Key menu, enter a keystore password key in the Key field. Note that you may need to clear the Key field before entering a new value. In the Password and Confirm fields, enter the password for the keystore. The key that you specify here will be stored in the credential store as the credential store key and the password that you enter will be associated with that key in the credential store. This password must match the password you used when you created the keystore using the keytool utility, as described in "Generating Private Keys and Creating the Java Keystore", for example password. For more information, see "How OWSM Locates Keystore And Key Passwords for the JKS and PKCS11 Keystores" in Understanding Oracle Web Services Manager.

  6. Configure the signature key as follows:
    • If a signature key exists in the credential store, select it from the Key menu. If you select a key from the menu, the Sign Alias and Password fields are disabled and the credentials associated with the selected key will be used.

    • If the signature key is not listed in the Key menu, enter a name for the signature key in the Key field. Note that you may need to clear the Key field before entering a new value. Specify an alias name in the Sign Alias field, and the password for the alias in the Password and Confirm fields. The values you specify here must match the values in the keystore. For example, orakey and password.

  7. Configure the encryption key as follows:
    • If an encryption key exists in the credential store, select it from the Key menu. If you select a key from the menu, the Encrypt Alias and Password fields are disabled and the credentials associated with the selected key will be used.

    • If the encryption key is not listed in the Key menu, enter a name for the encryption key in the Key field. Note that you may need to clear the Key field before entering a new value. Specify an alias name in the Encrypt Alias field, and the password for the alias in the Password and Confirm fields. The values you specify here must match the values in the keystore. For example, orakey and password.

      Note:

      The alias and password for the signature and encryption keys define the string alias and password used to store and retrieve the keys in the credential store. For more information, see "How OWSM Uses the Credential Store" in Understanding Oracle Web Services Manager.

  8. Click Apply to submit the changes.
  9. If you are configuring the keystore for the first time, a server restart is not required. If, however, you are changing the keystore or keystore configuration, you must restart the server.
14.5.1.3 Configuring OWSM to Use HSM Keystores

Hardware Security Modules (HSM), such as SafeNet Luna SA, can be integrated with OWSM to provide a secure way to store keys and off-load cryptographic processing. You can use Fusion Middleware Control to configure OWSM to use the HSM keystore.

To configure OWSM to use the HSM keystore:

  1. Install and configure SafeNet Luna as described in "Using Hardware Security Modules With OWSM".
  2. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  3. Select the Message Security tab.
  4. In the Key Store section of the page, select HSM as the Keystore Type.

    The HSM keystore settings are displayed, as shown in Figure 14-6.

    Figure 14-6 HSM Settings for OWSM Keystore Configuration



  5. In the Provider type field, enter luna.
  6. In the Sign Alias and Encrypt Alias fields, enter an alias for the signature and encryption keys. (Note that Luna SA does not require passwords to access the keystore and private keys.)

    Note:

    For HSMs, only a signature key alias is required so all *csf.key (keystore.sig.csf.key and keystore.enc.csf.key) properties should have a direct alias and not credential store keys. This information is also applicable to configuration overrides of *csf.key properties.

  7. Click Apply to accept the changes.
  8. If you are configuring the keystore for the first time, a server restart is not required. If, however, you are changing the keystore or keystore configuration, you must restart the server.
14.5.1.4 Configuring OWSM to Use the PKCS11 Keystore

You can use Fusion Middleware Control to configure OWSM to use the PKCS11 keystore.

To configure OWSM to use the PKCS11 keystore:

  1. Create the keystore as described in "About Configuring OWSM for Oracle SPARC T5 and SPARC T4 Cryptographic Acceleration".
  2. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  3. Select the Message Security tab.
  4. In the Keystore section of the page, select PKCS11 as the Keystore Type.

    The PKCS11 keystore settings are displayed, as shown in Figure 14-7.

    Figure 14-7 PKCS11 Section of Message Security Key Store Page



  5. Do one of the following:
    • If a keystore password key exists in the credential store, select it from the Key menu. If you select a key from the menu, the Password fields are disabled and the credentials associated with the selected key will be used.

    • If the keystore password key is not listed in the Key menu, enter a keystore password key in the Key field. Note that you may need to clear the Key field before entering a new value. In the Password and Confirm fields, enter the password for the keystore. The key that you specify here will be stored in the credential store as the credential store key and the password that you enter will be associated with that key in the credential store. This password must match the password you used when you created the keystore, for example password. For more information, see "How OWSM Locates Keystore And Key Passwords for the JKS and PKCS11 Keystores" in Understanding Oracle Web Services Manager.

  6. Configure the signature key as follows:
    • If a signature key exists in the credential store, select it from the Key menu. If you select a key from the menu, the Sign Alias and Password fields are disabled and the credentials associated with the selected key will be used.

    • If the signature key is not listed in the Key menu, enter a name for the signature key in the Key field. Note that you may need to clear the Key field before entering a new value. Specify an alias name in the Sign Alias field, and the password for the alias in the Password and Confirm fields. The values you specify here must match the values in the keystore. For example, orakey and password.

  7. Configure the encryption key as follows:
    • If an encryption key exists in the credential store, select it from the Key menu. If you select a key from the menu, the Encrypt Alias and Password fields are disabled and the credentials associated with the selected key will be used.

    • If the encryption key is not listed in the Key menu, enter a name for the encryption key in the Key field. Note that you may need to clear the Key field before entering a new value. Specify an alias name in the Encrypt Alias field, and the password for the alias in the Password and Confirm fields. The values you specify here must match the values in the keystore. For example, orakey and password.

      Note:

      The alias and password for the signature and encryption keys define the string alias and password used to store and retrieve the keys in the credential store. For more information, see "How OWSM Uses the Credential Store" in Understanding Oracle Web Services Manager.

  8. Click Apply to submit the changes.
  9. If you are configuring the keystore for the first time, a server restart is not required. If, however, you are changing the keystore or keystore configuration, you must restart the server.

14.5.2 Configuring Security Policy Enforcement Using Fusion Middleware Control

The Security Settings section of the Message Security tab allows you to tune the configuration of 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.

To configure security policy enforcement:

  1. Navigate to the WSM Domain Configuration page. See Navigating to the WSM Domain Configuration Page.
  2. Select the Message Security tab.

    Figure 14-8 Security settings in Message Security page



  3. In the Security Settings section of the page, set the following properties as required for your environment:
    • Allow XPath Transformations—Specify whether OWSM will accept all types of XPath transformations. By default, OWSM only accepts the XPath transformation ancestor-or-self::*[namespace-uri()='<namespace>' and local-name()='<name>'] inside the signature (in the incoming SOAP message).

      Enable this property to allow and accept all types of XPath transformations. The default is disabled. Note that enabling this property may result in XPath based Denial of Service attacks or other similar XPath based security vulnerabilities.

    • Nonce Time To Live – Specify the total time-to-live 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 28800000 milliseconds (8 hours).

      You should configure this property to:

      • Decrease the time-to-live amount to ensure that there is less memory being consumed in the server because nonce is removed after the reduced time period.

      • Increase the time-to-live amount so that nonce is cached longer in the server, thereby ensuring the uniqueness/freshness of the message for a longer time period.

      To set this property, enter a new value in the field, or click the up/down arrows to increase or decrease the default value.

      Note:

      For username token settings in a policy, you must enable both the Creation Time Required and Nonce Required properties to prevent replay attacks. If only Nonce Required is enabled, then nonce will be cached forever to prevent replay attacks. Additionally, you must set the value of Nonce Time to Live to be equal to or greater than the value set for Message Expiration Time.

    • Clock Skew – Specify the tolerance of time differences, in milliseconds, between client and server machines. For example, when timestamps are sent in a message to a service that follows a different time zone, this property allows for the specified time tolerance. The default value is 360000 milliseconds (6 minutes).

      Note:

      This property must have a value greater than or equal to 1 second. If the value is less than 1 second, then the property does not work as expected.

      To adjust the clock skew, enter a new value in the field or click the up/down arrows to increase or decrease the default value.

      You should configure this property as follows:

      • Increase the clock skew when the client and web service are running on different systems and their system clocks are not in sync, which could result in the service rejecting messages from the client, with an error indicating the timestamp validation failed. Increasing the clock skew accounts for the difference in clocks between the client and the web service. For example, if the difference between the web service clock and the client clock is 10 minutes, increase the Clock Skew on the system hosting the web service to 10 minutes (600000 milliseconds).

      • Decrease the clock skew if you want to narrow the window in which the web service is willing to accept messages from clients to avoid replay attacks.

    • Message Expiration Time— Specify the 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. It is also used to control the timestamp expiry window on the client side when the message is created. The value specified here applies to all message protection and SAML assertion timestamp elements. The default value is 300000 milliseconds (5 minutes).

      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 expiration time must be increased. The message expiration time is derived from the values of Message Expiration Time and the expiry time in the incoming message, and is the lesser of the two.

      For example, if the server's Message Expiration Time is set to 5 minutes and the incoming message expiry time is 6 minutes, then the effective timestamp validation window is only 5 minutes and the incoming message is only be valid in that 5 minute window. In this case, you need to increase the Message Expiration Time at the service side. (Increasing the timestamp expiry on the incoming message will not fix the problem because the message expiration time is derived from both values and is the lesser of the two.)

      On the other hand, if the server's Message Expiration 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.

      Note:

      A higher value of the Message Expiration Time may lead to a security vulnerability.

    • Signature Cache Enable—If enabled, OWSM will cache the primary signature of SOAP messages in the signature cache for a stipulated time. If a message comes in this time with the same signature, it will be rejected as a duplicate message. To get this functionality include-timestamp flag in the policy should be true. If it is not true, OWSM will not know that the coming message is duplicate, and the message will be accepted as genuine.

      By default this property is disabled. You can enable it by selecting this check box. You can also enable it through WLST.

  4. Click Apply to apply the property updates.

14.5.3 Configuring Identity Extension Properties Using Fusion Middleware Control

The properties in the Identity section of the Message Security 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 about the service identity certificate extension and hostname verification, see "Understanding Service Identity Certificate Extensions".

Note:

Service identity certificate extension does not set the encryption key from which the public key is derived. You must first specify this key as described in "Overview of Configuring Keystores for Message Protection".

To enable or disable service identity certificate extension and hostname verification:

  1. Set the encryption key from which the public key is derived, as described in "Overview of Configuring Keystores for Message Protection".

    If you use a service side override to override the encryption key or keystore for a web service, the certificate corresponding to the overridden key is used.

  2. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  3. Select the Message Security tab.
  4. In the Identity section of the page, set the following properties as required for your environment:
    • Ignore Hostname Verification – Specify whether to ignore the hostname verification feature per domain. By default this property is disabled (true). However, you can enable hostname verification by setting the property to false.

    • Ignore Identity WSDL— Specify whether to enable or disable the consumption of the X509 Certificate from a client-side WSDL for the domain. By default, this property is enabled (false), which means that the certificate from the WSDL will be used by the client run time for encryption. You can disable the consumption of the X509 Certificate by changing the default setting to true.

  5. Click Apply to apply the property updates.

14.5.4 Secure Conversation Configuration for the Domain Using Fusion Middleware Control

You can use the Message Security tab on the WSM Domain Configuration page to configure secure conversation for the domain.

The following topics provide information to help you configure secure conversation:

14.5.4.1 About Secure Conversation

OWSM implements the Web Services Trust and Web Services Secure Conversation specifications, which together provide secure communication between web services and their clients. You can use WS-SecureConversation to increase the performance and security of your web services.

For more detailed information about secure conversation, see "Understanding Secure Conversation" in Understanding Oracle Web Services Manager.

WS-SecureConversation is configurable at the domain level, and at the policy level. If you use the predefined WS-SecureConversation policies provided with OWSM, WS-SecureConversation is already enabled. However, many of the predefined assertion templates provide secure conversation functionality, and policies based on these assertion templates can be configured to use secure conversation. For details about configuring secure conversation at the policy level, see "About Configuring Secure Conversation".

14.5.4.2 Configuring Secure Conversation with Fusion Middleware Control

You can follow the procedure in this section to configure secure conversation at the domain level.

To configure secure conversation at the domain level:

  1. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  2. Select the Message Security tab.
  3. In the WS Secure Conversation section of the page, optionally configure the following properties as required for your environment:
    • Secure Conversation Token Lifetime—Specify the default number of milliseconds after which the secure conversation session should expire. The security context is shared by the client and web service for the lifetime of a communication session. This is the time after which the SCT is expired. The default is 1800000 milliseconds (30 minutes).

    • Secure Conversation Token Lifetime for Reauthentication—Specify the default number of milliseconds after which secure conversation of reauthenticate use cases should expire. The reauthenticate lifetime session should usually have a larger value because the session is shared across multiple users. When reauthentication is true and the session is shared among many users, you can set this to a larger value. The default is 28800000 milliseconds (8 hours).

    • Encrypt RM protocol message body—(Applies to web service client only.) Specify whether the WS-RM protocol messages should be encrypted. By default, this property is disabled. If enabled, the body of protocol request messages such as createSequence() and terminateSequence() are encrypted.

      The response message body for protocol messages depends on the request message body: if the request message from the client is encrypted for protocol messages, the web service sends the response encrypted, and vice versa.

  4. Click Apply to apply the property updates.

14.6 OWSM Policy Access Configuration Using Fusion Middleware Control

The Policy Access tab on the WSM Domain Configuration page provides the ability to configure the Policy Manager connection for auto-discovery, and whether SSL should be used for the connection. You can also manage the policy cache and configure high availability by tuning the retry logic.

The configuration details are described in the following sections:

14.6.1 Understanding Configuring the Policy Manager Connection Using Fusion Middleware Control

The Policy Manager section of the Policy Access tab enables you to configure auto-discovery of the Policy Manager, specify an alternate Policy Manager URL and credential store key and credentials to access the Policy Manager, and modify the refresh configuration and inventory delay settings.

The following topics provide information to help you configure a Policy Manager connection:

14.6.1.1 About Auto-Discovery and Connecting to the Policy Manager

OWSM uses an auto-discovery feature to locate and connect to an OWSM Policy Manager. By default, the auto-discovery logic will always connect to the Policy Manager in the local domain using non-secure protocol. If the auto-discovery logic cannot connect to a Policy Manager using non-secure protocol because the non-secure port is disabled, it will attempt to connect to a Policy Manager using secure protocol. However, when using auto-discovery, you can specify whether to use SSL to secure the connection. If you do so, the auto-discovery logic will only connect to Policy Managers using secure protocol and will not try to connect to any Policy Managers deployed on non-SSL servers, even if the SSL-enabled server goes down.

Auto-discovery is supported only in WebLogic domains hosting an OWSM Policy Manager instance. For more information about auto-discovery, see "Cross-Component Wiring for Auto-Discovery of Policy Manager".

You may want to disable auto-discovery in the following scenarios:

  • Your domain is split into two or more networks, especially if a firewall exists between them.

  • You are running on a non-WebLogic application server that does not support the auto-discovery feature, such as WebSphere Application Server.

  • You prefer to override the default settings.

14.6.1.2 Configuring a Connection to the Policy Manager Using Fusion Middleware Control

To configure the Policy Manager connection:

  1. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".

  2. Select the Policy Access tab and make the following changes in the Policy Manager section of the page.

  3. Specify the credential store key to use to obtain a principal (and its credentials) authorized to access an OWSM Policy Manager instance. You should configure this property when:

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

    • The Authentication Provider and LDAP directory that is configured does not support system accounts used by Oracle WebLogic, but which OWSM 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 "About Modifying the Default User".

    To specify the credential store CSF key, do one of the following:

    • If the desired CSF key exists in the credential store, select it from the PM CSF Key menu. If you select a key from the menu, the Credential and Password fields are disabled and the credentials associated with the selected key will be used.

    • If the CSF key is not listed in the PM CSF Key menu, enter a name for the CSF key in the PM CSF Key field. Note that you may need to clear the PM CSF Key field before entering a new value. In the Credential field, enter the username to be used to access the Policy Manager instance. In the Password and Confirm fields, enter the password for the username provided in the credential field.

    If you do not specify a PM CSF key, then the OracleSystemUser principal (standard for WebLogic Server environments) is used.

  4. Specify whether the auto-discovery feature of the Policy Manager should be used and, if so, whether SSL is required. If Auto Discover is enabled, the checkbox for specifying whether SSL should be used is active.

    By default, auto-discovery is enabled and SSL is disabled. In this case, the auto-discovery logic always attempts to connect to the Policy Manager using non-secure protocol. If it is unable to do so because the non-secure port is disabled, it will attempt to connect to a Policy Manager using secure protocol.

    To use auto-discovery with SSL, verify that Auto Discover is selected, then select Use SSL Only. If SSL is enabled, then the auto-discovery logic will only connect to Policy Managers using secure protocol and will not try to connect to any Policy Managers deployed on non-SSL servers, even if the SSL-enabled server goes down.

    Auto-discovery is supported only in WebLogic domains hosting an OWSM Policy Manager instance.

    To disable the auto-discovery feature, clear the Auto Discover checkbox. If disabled, the Edit icon is enabled and you can manually enter a URL to access a Policy Manager instance as described in the next step.

  5. If auto-discovery is disabled, specify a URL that specifies the location of the Policy Manager. To do so:

    1. Clear the Auto Discover checkbox, if you have not already done so.

    2. Click Edit in the PM URL field.

    3. In the Edit PM URLs window, click the + sign.

    4. Enter the URL for the Policy Manager in the blank field.

      The following protocols are valid:

      file://location_of_mds_home — Repository is accessed directly as an MDS instance (supported only in Java SE).

      classpath://JAR_location — JAR file containing the predefined policies and assertion templates is accessed using the classpath location.

      Note:

      Because classpath mode is a read-only Policy Manager mode, only design time policy attachments will be in effect. No post-deployment policy attachments or global policy sets will be in effect in this mode.

      If you do not provide a value in the URL field, OWSM uses auto-discovery in the same domain using non-secure protocol.

  6. Adjust the Refresh Rate and the Inventory Record Delay if required:

    • The Refresh Rate specifies the number of milliseconds to wait between configuration refreshes. The default is 600,000 milliseconds (10 minutes).

    • The Inventory Record Delay specifies the number of milliseconds to wait before sending inventory data. The default is 60,000 milliseconds (1 minute).

    Enter a new value in the field or click the up/down arrows to increase or decrease the default value.

  7. Click Apply to apply the property updates.

14.6.2 About Refreshing Configuration Cache in OWSM Manually by using Fusion Middleware Control

OWSM has background threads to refresh configuration and documents cache automatically at regular time intervals. This interval is specified in the following properties: refresh.repeat and cache.refresh.repeat. You can disable this automatic refresh by setting the value of configuration property auto.refresh to disabled. Then, you can manually refresh the configuration and documents cache when required.

14.6.2.1 Disabling Automatic Refresh Option in OWSM by using Fusion Middleware Control
You can disable the automatic refresh option in OWSM by setting the value of configuration property Auto Refresh to Disabled. To disable the automatic refresh option:
  1. Navigate to the WSM Domain Configuration page as described in Navigating to the WSM Domain Configuration Page
  2. Select the Policy Access tab, and in the Policy Manager section of the page, set the value of the Auto Refresh to Disabled.

    Figure 14-9 Disabling Auto Refresh Option to Manually Refresh Configuration Cache in OWSM



  3. Click Apply to apply the changes.
14.6.2.2 Checking Status of Automatic Refresh in OWSM by using Fusion Middleware Control
To check the status of the automatic refresh:
  1. Navigate to the WSM Domain Configuration page as described in Navigating to the WSM Domain Configuration Page
  2. Select the Policy Access tab.

    The Auto Refresh option in the Policy Manager section displays the status of the automatic refresh in OWSM.

    Figure 14-10 Policy Access Tab in WSM Domain Configuration Page Showing the Status of Auto Refresh



14.6.2.3 Refreshing the OWSM Cache Manually by using Fusion Middleware Control
To refresh the configuration and documents cache manually:
  1. Navigate to the WSM Domain Configuration page as described in Navigating to the WSM Domain Configuration Page
  2. Select the Policy Access tab.

    Figure 14-11 Policy Access Tab in WSM Domain Configuration Page



  3. In the Policy Manager section, click Refresh to refresh the Configuration Cache in all the servers.

    Note:

    The manual refresh impacts refresh of OWSM configuration and documents only (like policy and policy sets).

    The Information dialog box appears showing the refresh status of the servers.

    Figure 14-12 Refresh Status of Servers



14.6.3 Configuring SSL for the Policy Manager Connection Using Fusion Middleware Control

The properties in the SSL Setup section of the Policy Access tab enable you to configure the type of SSL, if any, to be used for the communication between the OWSM runtime and the Policy Manager.

To configure SSL:

  1. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  2. Select the Policy Access tab.
  3. In the SSL Setup section of the page, specify the type of SSL to be used, if any. Choose one of the following options:
    • Oneway—With one-way SSL, the server is required to present a certificate to the client but the client is not required to present a certificate to the server. If one-way SSL is enabled, you must provide the following credentials required to access the trust keystore:

      • Truststore Path—Enter a fully qualified path to the trust keystore.

      • Key—Select the CSF key to use to obtain the credential of the truststore. If the required key is not listed in the menu, you can enter it in this field. Note that you may have to clear the field before entering the new value.

      • Password/Confirm—Enter/reenter the password to access the truststore. These fields are disabled if you select an existing CSF key from the Key menu. In this case, the credentials associated with the selected key will be used

    • Two-way—With two-way SSL, the server presents a certificate to the client and the client presents a certificate to the server. If two-way SSL is enabled, you must provide the following credentials for the truststore and the keystore:

      • Truststore Path—Enter a fully qualified path to the trust keystore.

      • Key—Select the CSF key to use to obtain the credential of the truststore. If the required key is not listed in the menu, you can enter it in this field. Note that you may have to clear the field before entering the new value.

      • Password/Confirm—Enter/reenter the password to access the truststore. These fields are disabled if you select an existing CSF key from the Key menu. In this case, the credentials associated with the selected key will be used.

      • KeyStore—Enter a fully qualified path to the Java keystore.

      • Key—Select the keystore key to use to obtain the credential of the keystore.If the required key is not listed in the menu, you can enter it in this field. Note that you may have to clear the field before entering the new value.

      • Password/Confirm—Enter/reenter the password to access the keystore. These fields are disabled if you select an existing CSF key from the Key menu and the credentials associated with the selected key will be used.

      • SSL Alias—Enter the keystore alias.

    • None—Do not use SSL.

  4. Click Apply to apply the property updates.

14.6.4 High Availability Configuration and Cache Management Using Fusion Middleware Control

The properties in the Cache Management section of the Policy Access tab enable you to manage the policy cache and configure high availability by tuning the retry logic.

The following topics provide information to help you configure high availability and manage the policy cache:

14.6.4.1 About High Availability and Cache Management

The configuration management system will periodically reconnect to the Policy Manager (for example, to handle situations when the connection information changes). If the Policy Manager is down when the runtime attempts to reconnect, then it will use the value of the connect.retry.delay property to determine when it tries again. You can set this property as described in "Configuring the Policy Manager Connection Using WLST".

If the initial connection is made, but the OWSM Repository is not operating properly, then services will start in a "non-operational" state. You can adjust the values of the Failure Retry Count and the Failure Retry Delay properties to determine how may times the Agent will attempt to communicate with the Policy Manager, which in turn accesses the repository, and the time interval between retries. When the repository becomes available, then the services will become operational.

The Initial Cache Refresh and Cache Refresh Time properties can be adjusted to affect how often the Agent attempts to contact the Policy Manager to refresh documents that it has already cached. The Missing Documents Retry Delay property indicates how often the Agent will attempt to connect to the Policy Manager to retrieve a document that it could not retrieve. If a document or group of related documents (such as policy sets) cannot be retrieved because communication with the Policy Manager fails (for example, because it went down), then the Missing Documents Retry Delay property will still affect how often it attempts to communicate with the Policy Manager until it is fixed.

14.6.4.2 Configuring High Availability and Managing the Cache Using Fusion Middleware Control

To configure high availability and manage the policy cache:

  1. Navigate to the WSM Domain Configuration page as described in "Navigating to the WSM Domain Configuration Page".
  2. Select the Policy Access tab.
  3. In the Cache Management section of the page, configure the following properties as required for your environment:
    • Failure Retry Delay—Specify the number of milliseconds to wait between retry attempts. The default is 5000 milliseconds.

    • User Record Delay—Specify the number of milliseconds to wait before sending usage data. The default is 30000 milliseconds.

    • Failure Retry Count—Specify the number of times to retry after a communication failure. The default is 2 retry attempts.

    • Missing Documents Retry Delay—Specify the number of milliseconds to wait before trying to retrieve a missing document. The default is 15000 milliseconds.

    • Initial Cache Refresh—Specify the number of milliseconds to wait before initial cache refresh. The default is 600000 milliseconds (10 minutes).

    • Cache Refresh Time—Specify the number of milliseconds to wait between cache refreshes. The default is 600000 milliseconds (10 minutes).

    To set these properties, enter a new value in the field, or click the up/down arrows to increase or decrease the default value.

  4. Click Apply to apply the property updates.

14.7 About Managing OWSM Domain Configuration Properties Using WLST

You can use WLST to view and set domain-level configuration properties for OWSM, including authentication, message security, and policy access. You can set most of these configuration properties using the setWSMConfiguration command.

The following sections provide details:

Additional commands are provided to configure trusted issuers and the message protection keystore. Procedures for using those commands are provided in the following sections:

For reference information about these WLST commands, see "Web Services Custom WLST Commands" in WLST Command Reference for Infrastructure Components.

14.7.1 Viewing OWSM Domain Configuration Using WLST

You can display all of the configuration properties, with their values and groups, as specified in the current configuration document in the repository. If a property is not defined in the configuration document, then the default value defined for the product is displayed.

To view the OWSM domain configuration:

  1. Connect to the running instance of the server in the domain for which you want to view the configuration as described in "Accessing the Web Services Custom WLST Commands" in Administering Web Services.
  2. Use the displayWSMConfiguration() command to display the OWSM domain configuration.
    displayWSMConfiguration([context=None])
    

    For example, to display the configuration for the domain specified by the context wls/base_domain, enter the following command:

    wls:/new_domain/serverConfig> displayWSMConfiguration('/wls/base_domain')
    
    NAME: "allow.all.xpaths" CATEGORY: "Agent" SOURCE: "default"Value: false
    
    NAME: "use.unified.fault.code" CATEGORY: "Agent" SOURCE: "default"Value: true
    
    NAME: "client.clock.skew" CATEGORY: "Agent" SOURCE: "default"Value: 0
    
    NAME: "compliance.check" CATEGORY: "Agent" SOURCE: "default"Value: true
    
    NAME: "clock.skew" CATEGORY: "Agent" SOURCE: "default"Value: 360000
    
    NAME: "expire.time" CATEGORY: "Agent" SOURCE: "default"Value: 300000
    
    .
    .
    .
    

Note that the output displayed above shows the source of the configuration property settings as default, indicating the setting is from the default configuration document for the product. If you have modified a setting, it is saved in a configuration document for your domain, and will be reflected in the SOURCE field. For example:

NAME: "remove.anonymous.role" CATEGORY: "SubjectProperties" SOURCE: "/WLS/base_domain"
Value: true

14.7.2 Setting OWSM Domain Configuration Properties Using the setWSMConfiguration Command

You can set the domain-level configuration properties using the setWSMConfiguration command.

You do not need to use the setWSMConfiguration command in the context of a session.

To modify the configuration properties for the OWSM domain using the setWSMConfiguration command:

  1. Connect to the running instance of the server in the domain to be configured as described in "Accessing the Web Services Custom WLST Commands" in Administering Web Services.
  2. Optionally, use the displayWSMConfiguration() command to view the current configuration for the domain as described in "Viewing OWSM Domain Configuration Using WLST".
  3. Use the setWSMConfiguration() command to set the desired configuration properties.
    setWSMConfiguration (context,category,name,[group=None],[values=None])
    

    In this command:

    • context—Specifies the context of the configuration document to be modified. If a context is not provided or is set to None, then the configuration document associated with the currently connected domain is used.

    • category—The category of the property. The category is verified against the default set of properties to ensure it is acceptable for the context. This field is required.

    • name—The name of the property. The name is verified against the default set of properties to ensure it is acceptable for the context. This field is required

    • group—The group containing the set of values to add in the configuration document. If the group exists, and this value is set to None, the group is removed. This field is optional.

    • values—The array of values to set for a property or group in the configuration document. This field is optional.

    For example, to modify the default SAML2 login module properties, you can specify the following commands:

    wls:/base_domain/serverConfig> setWSMConfiguration(None,'SAML2LoginModule','add.assertion.to.subject',None,['false'])
    
    A new property "add.assertion.to.subject" within category "SAML2LoginModule" has been added.
    The values "[false]" have been added to property "add.assertion.to.subject" within category "SAML2LoginModule".
    Configuration properties associated with the context "/wls/base_domain" has been created.
    
    wls:/base_domain/serverConfig> setWSMConfiguration(None,'SAML2LoginModule','allow.virtual.user',None,['false'])
     
    A new property "allow.virtual.user" within category "SAML2LoginModule" has been added.
    The values "[false]" have been added to property "allow.virtual.user" within category "SAML2LoginModule".
    Configuration properties associated with the context "/WLS/base_domain" has been updated.

    Refer to the subsequent sections for the list of configuration properties for each type of configuration.

14.8 Configuring Domain-Level Authentication Using WLST

You can use WLST to set domain level authentication properties for OWSM, including the ability to configure SAML trust, JWT trust, the lifetime to be used for the issued token, and subject properties for JAAS subjects that are created after OWSM authentication. You can also configure SAML, SAML2, Kerberos, X509, and custom login modules.

The configuration details are described in the following sections:

14.8.1 Configuring SAML and JWT Trusted Issuers, DN Lists, and Token Attribute Rules Using WLST

SAML and JWT trusted issuers and DN lists are stored in trust configuration documents in the OWSM repository. To configure trusted issuers and DN lists, you must create a new document or edit an existing document in the repository.

When using WLST to create, modify, and delete token issuer trust documents, you must execute the commands in the context of a session. Each session applies to a single trust document only.

For more information about trusted issuers, DN lists, and token attribute rules, see the following topics:

  1. Connect to the running instance of the server in the domain for which you want to view the configuration as described in "Accessing the Web Services Custom WLST Commands" in Administering Web Services.
  2. Start a repository session using the beginWSMSession command.

    The beginWSMSession command is used to create a session in which the repository will be modified. All creation, modification, or deletion commands must be performed in the context of a session. A session can only act on a single document.

    For example:

    wls:/base_domain/serverConfig> beginWSMSession()
    
    Session started for modification.
    
  3. List the token issuer trust documents in the repository using the listWSMTokenIssuerTrustDocuments command.
    listWSMTokenIssuerTrustDocuments(name='*', detail='false')
    

    When used without any arguments, all the token issuer trust documents in the repository are listed. If you set the detail argument to true, the display name and the status of the document are also displayed.

    For example:

    wls:/base_domain/serverConfig> listWSMTokenIssuerTrustDocuments(detail='true')
     
    List of Token Issuer Trust Documents in the Repository:
     
    Name         : oracle-default
    Display Name : i18n:oracle.wsm.resources.resdesc.ResourceDescriptionBundle_property-TokenIssuerTrust_displayName
    Status       : DOCUMENT_STATUS_COMMITTED
    
  4. Do one of the following:
    • If a token issuer trust domain document does not exist for your domain, create one using the createWSMTokenIssuerTrustDocument command. The name argument is required. Typically, the name of the document should use the following format: tokenissuertrust<ServerType><domainName>, for example, tokenissuertrustWLSbase_domain.

      createWSMTokenIssuerTrustDocument(name, displayName)
      

      For example:

      wls:/base_domain/serverConfig> createWSMTokenIssuerTrustDocument('tokenissuertrustWLSbase_domain')
       
      New Token Issuer Trust document named "tokenissuertrustWLSbase_domain" created.
      Run the setWSMConfiguration command where category = "TokenIssuerTrust", 
      property name = "name" and value = "tokenissuertrustWLSbase_domain", for the new
      document to be used in the domain configuration.
      
      wls:/base_domain/serverConfig> setWSMConfiguration (None,'TokenIssuerTrust','name',None,['tokenissuertrustWLSbase_domain'])
      
      The values "[tokenissuertrustWLSbase_domain]" have been added to property "name" within category "TokenIssuerTrust".
      Configuration properties associated with the context "/WLS/base_domain" has been updated.
      
    • If the token issuer trust document already exists for your domain, select the document for modification using the selectWSMTokenIssuerTrustDocument command. The name argument is required.

      selectWSMTokenIssuerTrustDocument(name)
      

      For example:

      wls:/base_domain/serverConfig> selectWSMTokenIssuerTrustDocument('tokenissuertrustWLSbase_domain')
       
      Token Issuer Trust document named "tokenissuertrustWLSbase_domain" selected in the session.
      
  5. Optionally, specify a display name for the document using the setWSMTokenIssuerTrustDisplayName command. The display name is optional but can be useful for describing the documents. Note that if you specified a display name for the document when you created it, you can use this command to change the display name if desired.
    setWSMTokenIssuerTrustDisplayName(displayName)
    

    For example:

    wls:/base_domain/serverConfig> setWSMTokenIssuerTrustDisplayName('base_domain Trust Document')
     
    Display Name of the document changed from null to base_domain Trust Document.
    
  6. Add the trusted issuers and define trusted keys or a trusted DN list using the setWSMTokenIssuerTrust command.
    setWSMTokenIssuerTrust(type, issuer, [trustedKeys=None])
    

    In this command:

    • type indicates the types of the tokens issued by the issuer and how the issuer signing certificates are identified with trustedKeys. Supported type values are shown in the following table.

      Use this type value... For this token type... With this key type... And this key identifier type

      dns.sv

      SAML SV

      X509 certificate

      DN

      dns.hok

      SAML HOK or Bearer

      X509 certificate

      DN

      dns.alias.sv

      SAML SV

      X509 certificate

      alias

      dns.alias.hok

      SAML HOK or Bearer

      X509 certificate

      alias

      dns.jwt

      JWT

      X509 certificate

      DN

    • issuer is the name of the trusted issuer, such as www.oracle.com.

    • trustedKeys is an optional argument used to specify the trusted key identifiers or DN list or aliases for the issuer.

    This command behaves as follows:

    • If the trusted issuer already exists for the type specified, and you provide a list of DNs or aliases for the trustedKeys argument, the previous list is replaced with the new list. If you enter an empty set ([]) for the trustedDNs argument, then the list of DN values are deleted for the issuer.

    • If the trusted issuer does not exist for the type specified and you specify a value for the trustedKeys argument, the issuer is created with the associated DN list. If you do not set the trustedKeys argument, a new issuer is created with an empty DN list.

    In the following example, www.example.com is set as a trusted issuer. A DN list is not specified:

    wls:/base_domain/serverConfig> setWSMTokenIssuerTrust("dns.sv","www.example.com",[])
     
    New issuer - "www.example.com" added to the document.
    The issuer and trusted DN values have been updated successfully.
    

    In the following example, CN=weblogic, OU=Orakey Test Encryption Purposes Only, O=Oracle, C=US' and CN=orcladmin, OU=Doc, O=Oracle, C=US' are set as DNs in the dns.sv DN list for the www.oracle.com trusted SAML issuer:

    wls:/base_domain/serverConfig> setWSMTokenIssuerTrust('dns.sv','www.oracle.com', 
    ['CN=weblogic, OU=Orakey Test Encryption Purposes Only, O=Oracle',
    'CN=orcladmin, OU=Doc, O=Oracle, C=US'])
     
    New issuer - "www.oracle.com" added to the document.
    Issuer set with the given trusted keys.
    The issuer and trusted DN values have been updated successfully.
    
  7. Display the trusted issuer and DN list using the displayWSMTokenIssuerTrust command.
    displayWSMTokenIssuerTrust(type, issuer=None)
    

    When you specify a value for the type and issuer arguments, the DN lists for the issuer are displayed. If you do not specify an issuer name, all of the trusted issuers for the given type are listed.

    For example, to view the DN lists for the www.oracle.com trusted issuer:

    wls:/base_domain/serverConfig> displayWSMTokenIssuerTrust('dns.sv', 'www.oracle.com')
     
                    List of trusted key(s) for this issuer:
     
                            Key Identifier : CN=weblogic, OU=Orakey Test Encryption Purposes Only, O=Oracle, C=US
                            Key Type       : x509certificate
                            Value Type     : dn
     
                            Key Identifier : CN=orcladmin, OU=Doc, O=Oracle, C=US
                            Key Type       : x509certificate
                            Value Type     : dn
    

    To view all of the trusted issuers for the type dns.sv:

    wls:/base_domain/serverConfig> displayWSMTokenIssuerTrust('dns.sv')
     
    List of trusted issuers for this type:
     
    www.example.com
    www.oracle.com
                    List of trusted key(s) for this issuer:
     
                            Key Identifier : CN=weblogic, OU=Orakey Test Encryption Purposes Only, O=Oracle, C=US
                            Key Type       : x509certificate
                            Value Type     : dn
     
                            Key Identifier : CN=orcladmin, OU=Doc, O=Oracle, C=US
                            Key Type       : x509certificate
                            Value Type     : dn
    
  8. Optionally, add additional security constraints by using the setWSMTokenIssuerTrustAttributeFilter command to define token attribute rules for a trusted DN. The attribute rule can be applied to a subject name ID.
    setWSMTokenIssuerTrustAttributeFilter(dn, attr-name, [filters])
    

    In this command:

    • dn represents the DN of the token signing certificate.

    • attr-name represents the name of the attribute to assert, using the format name-id for the subject name ID.

    • filters represents the list of filters for the attribute with the format ['value1,'value2','value3'...]. Each value can be an exact name or a name pattern with a wildcard "*" character. When name-id is specified for the attr-name argument, then the value of the subject name ID in the incoming SAML assertion must match one of the specified values to go through. If no values are specified, then any value for the subject name ID will go through.

    This command behaves as follows:

    • If the attribute specified by the attr-name argument already exists with a list of filter values and you provide a new list of values for the filters argument, the previous list is replaced with the new list. If you enter an empty set ([]) for the filters argument, then the existing list of filter values is deleted.

    • If the attribute specified by the attr-name argument does not exist and you specify a list of values for the filters argument, the attribute is created and added to the document with the specified filter values. If you do not provide a value for the filters argument, an error is thrown.

    In this example, the name IDs yourTrustedUser and jdoe are set as trusted users for the weblogic trusted DN:

    wls:/base_domain/serverConfig> setWSMTokenIssuerTrustAttributeFilter('CN=weblogic, OU=Orakey Test Encryption Purposes Only, O=Oracle, C=US',
    'name-id', ['yourTrustedUser','jdoe'])
     
    New TokenAttributeRule added for DN: CN=weblogic, OU=Orakey Test Encryption Purposes Only, O=Oracle, C=US.
    
  9. Optionally, delete a token attribute rule using the deleteWSMTokenIssuerTrustAttributeRule command.
    deleteWSMTokenIssuerTrustAttributeRule(dn)
    

    For example, to delete the token attribute rule associated with the weblogic trusted DN:

    wls:/base_domain/serverConfig> deleteWSMTokenIssuerTrustAttributeRule('CN=weblogic, OU=Orakey Test Encryption Purposes Only,
    O=Oracle, C=US')
     
    Token Attribute Rule(s) for DN: CN=weblogic, OU=Orakey Test Encryption Purposes Only, O=Oracle, C=US, deleted successfully.
    

    Note:

    This command deletes the attribute rule. To delete only the list of filter values for an attribute in an attribute rule, use the setWSMTokenIssuerTrustAttributeFilter command and enter an empty set ([]) for the filters argument.

  10. Write the current contents of this session to the OWSM Repository using the commitWSMSession command.

    For example:

    wls:/base_domain/serverConfig> commitWSMSession()
    The tokenissuertrust tokenissuertrustWLSbase_domain is valid.
    Creating tokenissuertrust tokenissuertrustWLSbase_domain in repository.
    Session committed successfully.
    

Alternatively, you can choose to cancel any changes by using the abortWSMSession command, which discards any changes that were made to the repository during the session.

For more information about these commands, see "Token Issuer Trust Configuration Commands" in WLST Command Reference for Infrastructure Components.

14.8.2 Deleting a Token Issuer Trust Document Using WLST

Follow the procedure in this section to delete an token issuer trust document from the repository.

To delete an token issuer trust document from the repository:

  1. Connect to the running instance of the server in the domain for which you want to view the configuration as described in "Accessing the Web Services Custom WLST Commands" in Administering Web Services.
  2. Start a repository session using the beginWSMSession command.

    For example:

    wls:/base_domain/serverConfig> beginWSMSession()
    
    Session started for modification.
    
  3. List the token issuer trust documents in the repository using the listWSMTokenIssuerTrustDocuments command.
    listWSMTokenIssuerTrustDocuments(name='*', detail='false')
    

    When used without any arguments, all the token issuer trust documents in the repository are listed. If you set the detail argument to true, the display name and the status of the document are also displayed.

    For example:

    wls:/base_domain/serverConfig> listWSMTokenIssuerTrustDocuments(detail='true')
     
    List of Token Issuer Trust Documents in the Repository:
    Name         : oracle-default
    Display Name : i18n:oracle.wsm.resources.resdesc.ResourceDescriptionBundle_property-TokenIssuerTrust_displayName
    Status       : DOCUMENT_STATUS_COMMITED
    
    Name         : tokenissuertrustWLSbase_domain
    Display Name : base_domain Trust Document
    Status       : DOCUMENT_STATUS_COMMITED
    List of Token Issuer Trust Documents in the Repository:
    
  4. Delete the desired token issuer trust document using the deleteWSMTokenIssuerTrustDocument command. The name argument is required.
    deleteWSMTokenIssuerTrustDocument(name)
    

    For example:

    wls:/base_domain/serverConfig> deleteWSMTokenIssuerTrustDocument('tokenissuertrustWLSbase_domain')
    Token Issuer Trust document named "tokenissuertrustWLSbase_domain" deleted from the repository.
    
  5. Write the contents of the current session to the repository using the commitWSMSession command.
    wls:/base_domain/serverConfig> commitWSMSession()
     
    Deleting tokenissuertrust tokenissuertrustWLSbase_domain from repository.
     
    Session committed successfully.
    

    Alternatively, you can choose to cancel any changes by using the abortWSMSession command, which discards any changes that were made to the repository during the session.

14.8.3 Configuring the Lifetime for the Issued Token Using WLST

You can specify the lifetime to be used for the issued token when the request message is sent to the Security Token Service (STS).

If the STS sends the token with a different expiry, the runtime looks at the actual expiry of the token and only caches the token for that time. For more information, see "Understanding Token Lifetime and Token Caching".

To configure the lifetime of the issued token using WLST, use the setWSMConfiguration command as described in "Setting OWSM Domain Configuration Properties Using the setWSMConfiguration Command".

Use the following settings for this configuration property:

  • Category: IssuedToken

  • Name: lifetime

  • Default: 28800000ms (8 hours)

For example, to change the default value to 25200000 ms (7 hours), use the following command:

wls:/base_domain/serverConfig> setWSMConfiguration (None,'IssuedToken','lifetime',None,['25200000'])
 
A new property "lifetime" within category "IssuedToken" has been added.
The values "[25200000]" have been added to property "lifetime" within category "IssuedToken".
Configuration properties associated with the context "/WLS/base_domain" has been updated.

14.8.4 Configuring Subject Properties Using WLST

This topic describes the OWSM domain-level configuration properties that you can set for the subject properties. To configure subject properties for the domain, use the setWSMConfiguration command.

This command is described in "Setting OWSM Domain Configuration Properties Using the setWSMConfiguration Command".

For more information about subject properties, see "Configuring Subject Properties Using Fusion Middleware Control".

Table 14-1 lists the OWSM domain-level configuration properties that you can set for the subject properties.

Table 14-1 Subject Domain Configuration Properties

Category Property Name Default Description

SubjectProperties

add.application.roles

true

Flag that specifies if the application roles will be added to the subject created in OWSM. If true, the application roles are added to the subject.

If set to false, then the application roles are not added to the subject.

SubjectProperties

add.authenticated.role

true

Flag that specifies if the authenticated role will be added to the Subject created in OWSM. If true, the authenticated role is added to the subject.

If set to false, the authenticated role is not added to the subject.

SubjectProperties

remove.anonymous.role

false

Flag that specifies if the anonymous role will be removed from the subject created in OWSM. If false, then the anonymous role is added to the subject.

If set to true, the anonymous role is removed from the subject.

14.8.5 Configuring the SAML and SAML2 Login Modules Using WLST

You can use the setWSMConfiguration command to configure the SAML and SAML2 login modules by using WLST.

The command is described in "Setting OWSM Domain Configuration Properties Using the setWSMConfiguration Command".

For more information about these login modules, see "Configuring the SAML and SAML2 Login Modules Using Fusion Middleware Control".

Table 14-2 lists the OWSM domain-level configuration properties that you can set for the SAML and SAML2 login modules.

Table 14-2 SAML and SAML2 Login Module Domain Configuration Properties

Category Property Name Default Value Description

SAML2LoginModule

SAMLLoginModule

add.assertion.to.subject

true

Flag that specifies if the SAML assertion should be added to the authenticated subject as a private credential.

If you set this property to false, then the assertion is not added to the authenticated subject.

SAML2LoginModule

SAMLLoginModule

allow.virtual.user

false

Flag that specifies that the SAML subject is allowed to be treated as a virtual user. If set to true, the user is not mapped to the actual user in the identity store. The subject is populated only with the username from the SAML subject. Because the subject is treated as a virtual user, identity store configuration is not required and the Authentication Provider is not invoked for all SAML policies in the domain using this login module.

If this property is set to false, the username in the SAML subject is mapped to the actual user in the identity store. The user roles and subject are created with username and roles specified in the identity store.

SAML2LoginModule

SAMLLoginModule

dn.mapping.attribute

CN

Part of the certificate DN to use for asserting the user against the identity store if the Name Identifier Format is set to X509SubjectName in the SAML client policy.

SAML2LoginModule

SAMLLoginModule

custom

N/A

Use this property to set custom properties to the OPSS login module.

SAMLLoginModule

dns.hok

www.oracle.com

Defines the list of trusted issuers for the dns.hok token. The DN of the endorser of the SAML token will be checked in the SAML issuer list. Use this property for SAML HOK and SAML bearer.

SAMLLoginModule

dns.sv

www.oracle.com

Defines the list of trusted issuers for the dns.sv token. The DN of the endorser of the SAML token will be checked in the SAML issuer list. Use this property for SAML sender vouches.

14.8.6 Configuring the Kerberos Login Module Using WLST

You can use the setWSMConfiguration command to configure the Kerberos login module using WLST.

The command is described in "Setting OWSM Domain Configuration Properties Using the setWSMConfiguration Command".

Table 14-3 lists the OWSM domain-level configuration properties that you can set for the Kerberos login module.

Table 14-3 Kerberos Login Module Domain Configuration Properties

Category Property Name Default Description

KerberosLoginModule

class name

N/A

The login module to be used by OWSM. If no value is specified, at runtime one of the following default values will be used for the Kerberos login module Class Name, depending on the platform on which you are running:

  • com.sun.security.auth.module.Krb5LoginModule (Oracle)

  • com.ibm.security.auth.module.Krb5LoginModule (IBM)

KerberosLoginModule

do.not.prompt

true

Specifies whether you will be prompted for the password if credentials cannot be obtained from the cache or keytab. When set to true, authentication will fail if credentials can not be obtained from the cache or keytab.

KerberosLoginModule

key.tab

./krb5.keytab

The file name of the keytab to get the secret key for the principal

KerberosLoginModule

principal

HOST/localhost@EXAMPLE.COM

The name of the principal to be used. The principal represents a specific entity to which a set of credentials are assigned. It can be a simple username, such as testuser, or a service name such as HOST/localhost. You can use the principal option to set the principal when there are credentials for multiple principals in the keytab or when you want a specific ticket cache only.

KerberosLoginModule

store.key

true

Specifies whether the principal's key is stored in the Subject's private credentials.

KerberosLoginModule

use.key.tab

true

Specifies whether the module will get the principal's key from the keytab. If the keytab is not set, then the module will locate the keytab from the Kerberos configuration file. If it is not specified in the Kerberos configuration file, then it will look for the file <user.home><file.separator>krb5.keytab.

KerberosLoginModule

custom

N/A

Use to provide custom properties to the OPSS login module. You can set different groups in this property and these groups will have a single value.

14.8.7 Configuring the X509 Login Module Using WLST

You can use the setWSMConfiguration command to configure the X509 login module.

The command is described in "Setting OWSM Domain Configuration Properties Using the setWSMConfiguration Command".

Table 14-4 lists the domain-level configuration properties that you can set for the X509 login module.

Table 14-4 X509 Login Module Domain-Level Configuration Properties

Category Property Name Default Description

X509LoginModule

dn.mapping.attribute

CN

Specifies which part of the certificate DN to use for asserting the user against the identity store. The value that you specify is passed to OPSS with each invocation of the login module.

x509LoginModule

custom

N/A

Use to provide custom properties to the OPSS login module. You can set different groups in this property and these groups will have a single value.

14.8.8 Configuring Custom Login Modules Using WLST

You can configure other login modules, and create custom login modules in the OWSM configuration system using the setWSMConfiguration command.

The command is described in "Setting OWSM Domain Configuration Properties Using the setWSMConfiguration Command".

For details about creating a login module, see the Java Authentication and Authorization Service (JAAS) LoginModule Developer's Guide at http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASLMDevGuide.html.

Table 14-5 lists the configuration properties for other login modules that are provided by default.

Table 14-5 Other Login Module Domain Configuration Properties

Category Property Name Default Description

DigestLoginModule

custom

N/A

Use to provide custom properties to the OPSS login module. You can set different groups in this property and these groups will have a single value.

UsernameAssertionLoginModule

custom

N/A

Use to provide custom properties to the OPSS login module. You can set different groups in this property and these groups will have a single value.

UsernameAuthLoginModule

custom

N/A

Use to provide custom properties to the OPSS login module. You can set different groups in this property and these groups will have a single value.

WSSDigestLoginModule

custom

N/A

Use to provide custom properties to the OPSS login module. You can set different groups in this property and these groups will have a single value.

14.9 About Configuring Domain-Level Message Security Using WLST

You can use WLST to set domain-level message security properties for OWSM, including the ability to configure the OWSM keystore, tune security policy enforcement, specify if the public certificate should be published in the WSDL and the hostname verified, and secure conversation.

The configuration details are provided in the following sections:

14.9.1 Configuring the OWSM Keystore Using WLST

OWSM provides support for KSS, JKS, HSM, and PKCS11 keystores. After you create the keystores, you need to configure OWSM so that it can access and use the keystore. You can configure the OWSM keystore using the configureWSMKeystore command.

Note that there is one OWSM keystore per domain, and it is shared by all web services and clients running in the domain.

To configure the OWSM keystore:

  1. Create the desired keystore as described in the following sections:
  2. Connect to the running instance of the server in the domain to be configured as described in "Accessing the Web Services Custom WLST Commands" in Administering Web Services.
  3. Optionally, use the displayWSMConfiguration() command to view the current configuration for the domain as described in "Viewing OWSM Domain Configuration Using WLST".

    The keystore configuration properties are in the KeystoreConfig category.

  4. Use the configureWSMKeystore command to configure the OWSM keystore properties.
    configureWSMKeystore(context, keystoreType,location, keystorePassword, signAlias, signAliasPassword, cryptAlias, cryptAliasPassword)
    

    In this command:

    • context represents the configuration document to be modified. If a configuration document associated with the context does not exist, it is created automatically.

    • keystoreType represents the keystore type category of the property. Valid keystore types are JKS, KSS, PKCS11, and LUNA. The default is KSS.

    • location represents the location of the keystore. For JKS, it is the absolute location of the keystore or the location relative to the fmwconfig directory. For KSS, the format of the location should be kss://stripeName/keystoreName. The default is kss://owsm/keystore. This argument is not required for LUNA and PKCS11 keystores.

    • keystorePassword represents the keystore password for the configured keystore. It is required for JKS and PKCS11 keystores.

    • signAlias represents the alias of the signature key. The value that you specify here must match the value in the keystore. For example, orakey.

    • signAliasPassword represents the password for the signature key alias. It is required for JKS and PKCS11 keystores.

    • cryptAlias represents the alias of the encryption key. The value that you specify here must match the value in the keystore. For example, orakey

    • cryptAliasPassword represents the password for the encryption key alias. It is required for JKS and PKCS11 keystores.

      Note:

      This command sets the CSF key under the default map name oracle.wsm.security in the credential store. To differentiate between several CSF entries in the credential store, the domain name will be appended to sign-csf-key and enc-csf-key.

    The following examples provide sample commands for configuring the different keystore types:

    • KSS Keystore

      wls:/base_domain/serverConfig> configureWSMKeystore('/wls/new_domain',keystoreType='KSS', 
      location='kss://owsm/keystore', signAlias='orakey', cryptAlias='orakey')
       
      Successfully configured property "keystore.type".
      Successfully configured property "location".
      Successfully configured property "keystore.pass.csf.key".
      Successfully configured property "keystore.sig.csf.key".
      Successfully configured property "keystore.enc.csf.key".
      
    • JKS Keystore

      wls:/base_domain/serverConfig> configureWSMKeystore('/wls/new_domain',keystoreType='JKS', 
      location='./default-keystore.jks', keystorePassword='password',signAlias='orakey',
      signAliasPassword='password',cryptAlias='orakey',cryptAliasPassword='password')
       
      Successfully configured property "keystore.type".
      Successfully configured property "location".
      Successfully configured property "keystore.pass.csf.key".
      Successfully configured property "keystore.sig.csf.key".
      Successfully configured property "keystore.enc.csf.key".
      
    • PKCS11 Keystore

      wls:/base_domain/serverConfig> configureWSMKeystore('/wls/new_domain',keystoreType='PKCS11',
      keystorePassword='password',signAlias='orakey', signAliasPassword='password',
      cryptAlias='orakey',cryptAliasPassword='password')
       
      Successfully configured property "keystore.type".
      Successfully configured property "location".
      Successfully configured property "keystore.pass.csf.key".
      Successfully configured property "keystore.sig.csf.key".
      Successfully configured property "keystore.enc.csf.key".
      
    • HSM Luna SA Keystore

      wls:/base_domain/serverConfig> configureWSMKeystore('/wls/new_domain',keystoreType='LUNA',signAlias='orakey', cryptAlias='orakey')
       
      Successfully configured property "keystore.type".
      Successfully configured property "location".
      Successfully configured property "keystore.pass.csf.key".
      Successfully configured property "keystore.sig.csf.key".
      Successfully configured property "keystore.enc.csf.key".
      
  5. If you are configuring the keystore for the first time, a server restart is not required. If, however, you are changing the keystore or keystore configuration, you must restart the server.

14.9.2 Configuring Security Policy Enforcement Using WLST

You can use the setWSMConfiguration command to configure security policy enforcement.

The command is described in "Setting OWSM Domain Configuration Properties Using the setWSMConfiguration Command".

Table 14-6 lists the OWSM domain-level configuration properties that you can set for security policy enforcement.

Table 14-6 Security Policy Enforcement Domain-Level Configuration Properties

Category Property Name Default Description

Agent

allow.all.xpaths

false

Specifies whether OWSM will accept all types of XPath transformations. By default, OWSM only accepts the XPath transformation ancestor-or-self::*[namespace-uri()='<namespace>' and local-name()='<name>'] inside the signature (in the incoming SOAP message).

Set this property to true to allow and accept all types of XPath transformations. Note that enabling this property may result in XPath based Denial of Service attacks or other similar XPath based security vulnerabilities.

Agent

use.unified.fault.code

true

Specifies whether OWSM will send InvalidSecurity fault codes for all types of errors. If a web service sends different fault codes for different types of errors (such as FailedAuthentication, InvalidSecurityToken, FailedCheck, and so on) there is a possibility of an XML encryption attack.

Note: This applies only to security-related faults that originated from OWSM. It does not apply to business faults coming from web services.

To avoid these types of attacks, OWSM will send only InvalidSecurity fault codes for all types of errors when this property is set to true (the default).

Set this property to false if it is required to send different fault codes for the different scenarios. Oracle does not recommend changing this setting to false as it might lead to an XML encryption attack.

Agent

client.clock.skew

0

Tolerance of time, in seconds, that is used to calculate the NotBefore and NotOnOrAfter conditions for SAML token generation. Together, these conditions define the lower and upper boundaries to limit the validity of the token.

Agent

compliance.check

true

This property enables compliance checking for various security related configurations/checks and enforces that the incoming message complies to the security requirement of the receiving party. This setting applies to the request message coming to service and the response message coming to the client. It checks for encryption and signature algorithms, encrypted and signed elements and parts, attachment compliance, timestamp compliance, and so on. Setting this property to false allows you to skip all of these compliance checks, but this is strongly discouraged.

Agent

clock.skew

360000

Tolerance of time differences 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.

Note: This property must have a value greater than or equal to 1 second. If the value is less than 1 second, then the property does not work as expected.

For more information about this property, see the description for the Clock Skew property in "Configuring Security Policy Enforcement Using Fusion Middleware Control".

Agent

expire.time

300000

Duration of time 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.

For more information about this property, see the description for the Message Expiration Time property in "Configuring Security Policy Enforcement Using Fusion Middleware Control".

Agent

nonce.ttl

28800000

Total time-to-live 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.

For more information about this property, see the description for the Nonce Time To Live property in "Configuring Security Policy Enforcement Using Fusion Middleware Control".

Agent

signature.cache.enable

false

If enabled, OWSM will cache the primary signature of SOAP messages in the signature cache for a stipulated time. If a message comes in this time with the same signature, it will be rejected as a duplicate message. To get this functionality include-timestamp flag in the policy should be true. If it is not true, OWSM will not know that the coming message is duplicate, and the message will be accepted as genuine.

By default this property is disabled. You can enable it in the WSM Domain Configuration page. You can also enable it through WLST.

14.9.3 Configuring Identity Extension Properties Using WLST

You can use the setWSMConfiguration command to configure identity settings.

The command is described in "Setting OWSM Domain Configuration Properties Using the setWSMConfiguration Command".

For more information about the service identity certificate extension and hostname verification, see "Understanding Service Identity Certificate Extensions".

Note:

Service identity certificate extension does not set the encryption key from which the public key is derived. You must first specify this key as described in "Overview of Configuring Keystores for Message Protection".

Table 14-7 lists the OWSM domain-level configuration properties that you can set for service identity.

Table 14-7 Identity Domain-Level Configuration Properties

Category Property Name Default Description

Identity

ignore.hostname.verification

true

Specifies whether to ignore the hostname verification feature per domain. By default this property is disabled (true). However, hostname verification can be enabled by setting the property to false.

Identity

ignore.identity.wsdl

false

Specifies whether to enable or disable the consumption of the X509 Certificate from a client-side WSDL, per domain. By default, this property is enabled (false), which means that the certificate from the WSDL will be used by the client runtime for encryption. The consumption of the X509 Certificate can be disabled by changing the default setting to true.

14.9.4 Configuring Secure Conversation for the Domain Using WLST

You can use the setWSMConfiguration command to configure domain-level secure conversation.

The command is described in "Setting OWSM Domain Configuration Properties Using the setWSMConfiguration Command".

For more information about domain-level secure conversation, see "Secure Conversation Configuration for the Domain Using Fusion Middleware Control".

Table 14-8 lists the OWSM domain-level configuration properties that you can set for secure conversation.

Table 14-8 Secure Conversation Domain-Level Configuration Properties

Category Property Name Default Description

SecureConversation

token.lifetime

1800000

The default number of seconds after which the secure conversation session should expire.

SecureConversation

token.lifetime.reauth

28800000

The default number of seconds after which secure conversation session of re-authenticate use cases should expire. The reauthenticate lifetime session should usually have a larger value because the session is shared across multiple users. When reauthentication is true and the session is shared among many users, you can set this to a larger value.

SecureConversation

rm.encrypt.body

false

(Applies to web service client only.) Specifies whether the WS-RM protocol messages should be encrypted. If set to true, the body of protocol request messages such as createSequence() and terminateSequence() are encrypted.

The response message body for protocol messages depends on the request message body: if the request message from the client is encrypted for protocol messages, the web service sends the response encrypted, and vice versa.

14.10 About Configuring Policy Access Using WLST

You can use WLST to set domain-level message policy access for OWSM, including the ability to configure the Policy Manager connection for auto-discovery, and whether SSL should be used for the connection. You can also manage the policy cache and configure high availability by tuning the retry logic.

The configuration details are provided in the following sections:

14.10.1 Configuring the Policy Manager Connection Using WLST

You can use the setWSMConfiguration command to configure the Policy Manager connection.

The command is described in "Setting OWSM Domain Configuration Properties Using the setWSMConfiguration Command".

For additional information about the Policy Manager connection, see "Understanding Configuring the Policy Manager Connection Using Fusion Middleware Control".

Table 14-9 lists the OWSM domain-level configuration properties that you can set for the Policy Manager connection.

Table 14-9 Policy Manager Connection Domain-Level Configuration Properties

Category Property Name Default Description

ConfigManager

connect.retry.delay

60000

Number of milliseconds to wait before the Agent attempts to establish a connection to the Policy Manager after a failure.

ConfigManager

keystore.csf.key

keystore-csf-key

CSF key to use to obtain credential of the keystore. Required for two-way SSL.

ConfigManager

keystore.path

kss://owsm/keystore

Keystore path relative to the domain configuration directory.

If the keystore path is provided as kss://owsm/keystore, then the absolute path of the keystore is computed as kss://<stripe>/<keystore>.

If the keystore path is provided as tmp/my.keystore.jks, then the absolute path of the keystore is computed as /domain_config_directory/fmwconfig//tmp/my.keystore.jks.

Required for two-way SSL.

ConfigManager

keystore.ssl.alias

mykey

Keystore alias. Required for two-way SSL.

ConfigManager

keystore.type

KSS

Type of keystore. Default value is KSS. Required for two-way SSL.

ConfigManager

pm.csf.key

CSF key to use to obtain a principal (and its credentials) authorized to access an OWSM Policy Manager instance. If not specified, then the OracleSystemUser principal (standard for WebLogic Server environments) is used.

ConfigManager

pm.url

URL that specifies the location of the policy accessor. The following entries are valid:

  • file://location_of_mds_home — Repository is accessed directly as an MDS instance (supported only in Java SE)

  • classpath://JAR_location — JAR file containing the predefined policies and assertion templates is accessed using the classpath location

    Note: Because classpath mode is a read-only Policy Manager mode, only design time policy attachments will be in effect. No post-deployment policy attachments or global policy sets will be in effect in this mode.

  • auto—Enables auto-discovery of the Policy Manager using non-secure protocol. If the auto-discovery logic cannot connect to a Policy Manager using non-secure protocol because the non-secure port is disabled, it will attempt to connect to a Policy Manager using secure protocol.

  • auto-ssl—Enables auto-discovery of the Policy Manager using secure protocol. If SSL is enabled, then the auto-discovery logic will only connect to Policy Managers using secure protocol and will not try to connect to any Policy Managers deployed on non-SSL servers, even if the SSL-enabled server goes down.

Note: If you do not provide a value for pm.url, OWSM uses auto-discovery in the same domain using non-secure protocol. If the auto-discovery logic cannot connect to a Policy Manager using non-secure protocol because the non-secure port is disabled, it will attempt to connect to a Policy Manager using secure protocol.

ConfigManager

refresh.repeat

600000

Number of milliseconds to wait between configuration refreshes.

ConfigManager

ssl.twoway

false

Specifies if SSL connection should be one-way or two-way. Set to true for two-way SSL.

ConfigManager

truststore.csf.key

keystore-csf-key

CSF key to use to obtain credential of the keystore. Required for one-way and two-way SSL.

ConfigManager

truststore.path

kss://owsm/keystore

Truststore path relative to the domain configuration directory.

If the truststore path is provided as kss://owsm/keystore, then the absolute path to the truststore is computed as kss://<stripe>/<keystore>.

If the truststore path is provided as tmp/my.truststore.jks, then the absolute path to the truststore is computed as /domain_config_directory/fmwconfig//tmp/my.truststore.jks.

Required for one-way and two-way SSL.

14.10.2 Updating Bootstrap Configuration Properties Using the setWSMBootstrapConfig Command

You can use the setWSMBootstrapConfig command to update the bootstrap configuration document (domain_home/config/fmwconfig/wsm-config.xml ).

To do so, complete the following steps:

  1. Connect to the running instance of the server in the domain to be configured. See Accessing the Web Services Custom WLST Commands in Administering Web Services.
  2. Run the setWSMBootstrapConfig command to update the desired configuration properties.
    setWSMBootstrapConfig (domainName, domainHome, propertyCategory, propertyName, propertyValue, [raiseError='true|false'])
    

    In this command:

    • domainName—Specify the domain name.

    • domainHome—Specify the root directory of the domain.

    • propertycategory—The category of the property.

    • propertyname—The name of the property. Specify one of the following supported property:

      • pm.url:URL that specifies the location of the OWSM Policy Manager instance. Supported pm.url protocol are as follows:

        File - This is supported only in Java SE. The OWSM repository will be accessed directly as a Plain Old Java Object (POJO) or OWSM Policy Manager.

        http/https - If the URL protocol is http or https, then the repository will be accessed through the OWSM Policy Manager’s RESTful APIs.

        Note:

        If the URL protocol is https then you must configure the following properties:
        • truststore.path

        • truststore.csf.key

        • ssl.twoway

        • keystore.path

        • keystore.ssl.alias

        • keystore.type

        • keystore.ssl.alias

        t3/t3s - If the URL protocol is t3 or t3s then the repository will be accessed through the OWSM Policy Manager’s EJB APIs.

        Note:

        If the pm.url is not configured explicitly, then by default OWSM repository is accessed as OWSM Policy Manager’s EJB APIs. This is recommended approach for WebLogic domain.
      • pm.csf-key: CSF key to use to obtain a principal (and its credentials) authorized to access an OWSM Policy Manager instance.

    • propertyvalues—The values to set for a property in the configuration document.

    • raiseError - Optional. When set to true, it raises exception in case of known errors. When set to false, it returns a boolean false value in case of known errors. By default, it's set to true.

    Example:

    setWSMBootstrapConfig ('base_domain', '/ORACLE_HOME/domains/base_domain', 'ConfigManager', 'pm.url', ['t3://localhost:7001'])

14.10.3 About Refreshing Configuration Cache in OWSM Manually by using WLST

OWSM has background threads to refresh configuration and documents cache automatically at regular time intervals. This interval is specified in the following properties: refresh.repeatand cache.refresh.repeat. You can disable this automatic refresh by setting the value of configuration property auto.refresh to disabled. Then, you can invoke the WLST command refreshWSMCache() to refresh this cache manually when required.

14.10.3.1 Disabling Automatic Refresh Option in OWSM by using WLST

You can disable the automatic refresh of OWSM cache by setting the value of the configuration property auto.refresh to disabled.

To disable the automatic refresh of OWSM cache:
  1. Connect to the running instance of the server in the domain to be configured as described in "Accessing the Web Services Custom WLST Commands" in Administering Web Services.
  2. Disable the OWSM auto-refresh threads by running the following command:
    WLST>  setWSMConfiguration('<context>','ConfigManager','auto.refresh',None,['disabled'])
    
    Example:
    WLST>  setWSMConfiguration(None,'ConfigManager','auto.refresh',None,['disabled'])
    WLST>  setWSMConfiguration('/WLS/myDomain','ConfigManager','auto.refresh',None,['disabled'])
14.10.3.2 Checking Status of Automatic Refresh in OWSM by using WLST

You can check the status of automatic refresh setting of OWSM cache by using the WLST command displayWSMConfiguration().

To check the status of automatic refresh:
  1. Connect to the running instance of the server in the domain to be configured as described in "Accessing the Web Services Custom WLST Commands" in Administering Web Services.
  2. Run the following command:
    WLST>  displayWSMConfiguration()
    
    Example:
    WLST>  displayWSMConfiguration()
    WLST>  displayWSMConfiguration('/WLS/myDomain')
    In the output look for the value of auto.refresh as disabled with the following syntax:
    NAME: "auto.refresh" CATEGORY: "ConfigManager" SOURCE: "<context>" Value: <value>
14.10.3.3 Refreshing the OWSM Cache Manually by using WLST

You can invoke the WLST command refreshWSMCache() to refresh this cache manually when required.

To refresh the OWSM cache manually:
  1. Connect to the running instance of the server in the domain to be configured as described in "Accessing the Web Services Custom WLST Commands" in Administering Web Services.
  2. Run the refreshWSMCache() command.

    This WLST updates the documents and configuration cached by OWSM.

14.10.4 Configuring High Availability and Cache Management Using WLST

You can use the setWSMConfiguration command to configure high availability and cache management.

The command is described in "Setting OWSM Domain Configuration Properties Using the setWSMConfiguration Command".

For more information about tuning the connection using these properties, see "High Availability Configuration and Cache Management Using Fusion Middleware Control".

Table 14-10 lists the OWSM domain-level configuration properties that you can set for high availability and cache management.

Table 14-10 High Availability and Cache Management Domain Configuration Properties

Category Property Name Default Description

BeanAccessor

cache.refresh.initial

600000

The number of milliseconds to wait before initial cache refresh.

Note: This property must have a value greater than or equal to 5 second. If the value is less than 5 second, then the property does not work as expected.

BeanAccessor

cache.refresh.repeat

600000

The number of milliseconds to wait between cache refreshes

Note: This property must have a value greater than or equal to 5 second. If the value is less than 5 second, then the property does not work as expected. A lower value will also overload the system.

BeanAccessor

failure.retry.count

2

The number of times to retry after a communication failure.

BeanAccessor

failure.retry.delay

5000

The number of milliseconds to wait between retry attempts.

BeanAccessor

jndi.connection.timeout

30000

The number of milliseconds to wait before timing out for waiting for the connection to the configured Policy Manager using the java.naming.provider.url.

BeanAccessor

missing.retry.delay

15000

The number of milliseconds to wait before trying to retrieve a missing document.

BeanAccessor

usage.record.delay

30000

The number of milliseconds to wait before sending usage data.