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

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

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

10 Setting Up Your Environment for Policies

This chapter describes how to set up your Fusion Middleware Control and WebLogic Server environments for security policies.

This chapter includes the following sections:

Configuring Keystores for SSL

If you want to use any of the policies listed in "Which Policies Require You to Configure SSL?" or "Which Policies Require You to Configure Two-Way SSL?", you must configure keystores for SSL.

SSL provides secure connections by allowing two applications connecting over a network to authenticate the other's identity and by encrypting the data exchanged between the applications.

Authentication allows a server, and optionally a client, to verify the identity of the application on the other end of a network connection. Encryption makes data transmitted over the network intelligible only to the intended recipient. A client certificate (two-way SSL) can be used to authenticate the user.

This section describes how to set up a Web service client and the WebLogic Server Web service container to send requests over SSL.

To use SSL in a Web service application, you need to:

These steps are described in the sections that follow.

Which Policies Require You to Configure SSL?

The predefined policies that require you to configure SSL are as follows:

  • oracle/wss_http_token_over_ssl_service_policy

  • oracle/wss_http_token_over_ssl_client_policy

  • oracle/wss_saml_token_bearer_over_ssl_server_policy

  • oracle/wss_saml_token_bearer_over_ssl_client_policy

  • oracle/wss_saml_token_over_ssl_service_policy

  • oracle/wss_saml_token_over_ssl_client_policy

  • oracle/wss_sts_issued_saml_bearer_token_over_ssl_client_template

  • oracle/wss_sts_issued_saml_bearer_token_over_ssl_service_template

  • oracle/wss_username_token_over_ssl_service_policy

  • oracle/wss_username_token_over_ssl_client_policy

In addition, you can create a new policy that requires SSL by using the following templates:

  • oracle/wss_http_token_over_ssl_service_template

  • oracle/wss_http_token_over_ssl_client_template

  • oracle/wss_saml_token_bearer_over_ssl_service_template

  • oracle/wss_saml_token_bearer_over_ssl_client_template

  • oracle/wss_saml_token_over_ssl_service_template

  • oracle/wss_saml_token_over_ssl_client_template

  • oracle/wss_sts_issued_saml_bearer_token_over_ssl_client_template

  • oracle/wss_sts_issued_saml_bearer_token_over_ssl_service_template

  • oracle/wss_username_token_over_ssl_service_template

  • oracle/wss_username_token_over_ssl_client_template

See Appendix C, "Predefined Assertion Templates" and Appendix B, "Predefined Policies" for more information on these assertions and policies.

Which Policies Require You to Configure Two-Way SSL?

The predefined policies that require you to configure two-way SSL are as follows:

  • oracle/wss_saml_token_over_ssl_client_policy

  • oracle/wss_saml_token_over_ssl_service_policy

  • oracle/wss_username_token_over_ssl_client_policy, when mutual authentication is selected.

  • oracle/wss_username_token_over_ssl_service_policy, when mutual authentication is selected.

  • oracle/wss_http_token_over_ssl_client_policy, when mutual authentication is selected.

  • oracle/wss_http_token_over_ssl_service_policy, when mutual authentication is selected.

In addition, you can create a new policy that requires two-way SSL by using the following templates:

  • oracle/wss_saml_token_over_ssl_client_template

  • oracle/wss_saml_token_over_ssl_service_template

How to Configure a Keystore on WebLogic Server

Private keys, digital certificates, and trusted certificate authority certificates establish and verify identity and trust in the WebLogic Server environment.

This section briefly summarizes the steps that are required to configure the keystore in WebLogic Server. See the following two sources for complete information:

WebLogic Server is configured with a default identity keystore DemoIdentity.jks and a default trust keystore DemoTrust.jks. In addition, WebLogic Server trusts the certificate authorities in the cacerts file in the JDK. This default keystore configuration is appropriate for testing and development purposes. However, these keystores should not be used in a production environment.

To configure identity and trust for a server:

  1. Obtain digital certificates, private keys, and trusted CA certificates from Sun Microsystem's keytool utility, or a reputable vendor such as Entrust or Verisign, and include them in the keystore.

    To get the certificate, you must create a Certificate Request and submit it to the CA. The CA will authenticate the certificate requestor and create a digital certificate based on the request.

    The PEM (Privacy Enhanced Mail) format is the preferred format for private keys, digital certificates, and trusted certificate authorities (CAs).

    If you use the keytool utility, the default key pair generation algorithm is Digital Signature Algorithm (DSA). WebLogic Server does not support DSA. Specify another key pair generation and signature algorithm such as RSA when using WebLogic Server. For more information about Sun's keytool utility, see the keytool-Key and Certificate Management Tool description at http://download.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html.

    You can also use the digital certificates, private keys, and trusted CA certificates provided by the WebLogic Server kit. The demonstration digital certificates, private keys, and trusted CA certificates should be used only in a development environment.

  2. Create one keystore for identity and one for trust. The preferred keystore format is JKS (Java KeyStore).

  3. Load the private keys and trusted CAs into the keystores.

  4. In the left pane of the Console, expand Environment and select Servers.

  5. Click the name of the server for which you want to configure the identity and trust keystores.

  6. Select Configuration, and then Keystores.

  7. In the Keystores field, select the method for storing and managing private keys/digital certificate pairs and trusted CA certificates. These options are available:

    • Custom Identity and Custom Trust: Identity and trust keystores you create.

    • Demo Identity and Demo Trust: The demonstration identity and trust keystores, located in the ..\server\lib directory and the JDK cacerts keystore, are configured by default. Use for development only.

    • Custom Identity and Java Standard Trust: A keystore you create and the trusted CAs defined in the cacerts file in the JAVA_HOME\jre\lib\security directory.

    • Custom Identity and Command Line Trust: An identity keystore you create and command-line arguments that specify the location of the trust keystore.

  8. In the Identity section, define attributes for the identity keystore.

    • Custom Identity Keystore: The fully qualified path to the identity keystore.

    • Custom Identity Keystore Type: The type of the keystore. Generally, this attribute is Java KeyStore (JKS); if left blank, it defaults to JKS.

    • Custom Identity Keystore Passphrase: The password you will enter when reading or writing to the keystore. This attribute is optional or required depending on the type of keystore. All keystores require the passphrase to write to the keystore. However, some keystores do not require the passphrase to read from the keystore. WebLogic Server only reads from the keystore so whether or not you define this property depends on the requirements of the keystore.

      Note:

      The passphrase for the Demo Identity keystore is DemoIdentityKeyStorePassPhrase.
  9. In the Trust section, define properties for the trust keystore.

    If you chose Java Standard Trust as your keystore, specify the password defined when creating the keystore. Confirm the password.

    If you chose Custom Trust, define the following attributes:

    • Custom Trust Keystore: The fully qualified path to the trust keystore.

    • Custom Trust Keystore Type: The type of the keystore. Generally, this attribute is JKS; if left blank, it defaults to JKS.

    • Custom Trust Keystore Passphrase: The password you will enter when reading or writing to the keystore. This attribute is optional or required depending on the type of keystore. All keystores require the passphrase to write to the keystore. However, some keystores do not require the passphrase to read from the keystore. WebLogic Server only reads from the keystore, so whether or not you define this property depends on the requirements of the keystore.

  10. The changes are automatically activated.

Configuring SSL on WebLogic Server (One-Way)

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.

After you configure identity and trust keystores for a WebLogic Server instance as described in "Configuring Keystores for SSL", you configure its SSL attributes. These attributes describe the location of the identity key and certificate in the keystore specified on the Configuration: Keystores page. Use the Configuration: SSL page to specify this information.

This section summarizes the steps required to configure SSL on WebLogic Server. For complete information, see Securing Oracle WebLogic Server.

To configure SSL:

  1. In the left pane of the WebLogic Server Administration Console, expand Environment and select Servers.

  2. Click the name of the server for which you want to configure SSL.

  3. Select Configuration, and then the SSL page, and choose the location of identity (certificate and private key) and trust (trusted CAs) for WebLogic Server.

  4. Set SSL attributes for the private key alias and password.

  5. At the bottom of the page, click Advanced.

  6. Set Hostname Verification to None.

  7. Indicate the number of times WebLogic Server can use an exportable key between a domestic server and an exportable client before generating a new key. The more secure you want WebLogic Server to be, the fewer times the key should be used before generating a new key.

  8. Set the Two Way Client Cert Behavior control to Client Certs Not Requested.

  9. Specify the inbound and outbound SSL certificate validation methods. These options are available:

    • Builtin SSL Validation Only: Uses the built-in trusted CA-based validation. This is the default.

    • Built-in SSL Validation and Cert Path Validators: Uses the built-in trusted CA-based validation and uses configured CertPathValidator providers to perform extra validation.

Configuring SSL on WebLogic Server (Two-Way)

With two-way SSL, the server presents a certificate to the client and the client presents a certificate to the server. WebLogic Server can be configured to require clients to submit valid and trusted certificates before completing the SSL handshake.

After you configure identity and trust keystores for a WebLogic Server instance as described in "Configuring Keystores for SSL", you can configure its two-way SSL attributes if the policy or template you are using requires it, as described in "Which Policies Require You to Configure Two-Way SSL?".

This section summarizes the steps required to configure SSL on WebLogic Server. For complete information, see Securing Oracle WebLogic Server.

To configure two-way SSL:

  1. In the left pane of the WebLogic Server Administration Console, expand Environment and select Servers.

  2. Click the name of the server for which you want to configure SSL.

  3. Select Configuration, and then the SSL page, and choose the location of identity (certificate and private key) and trust (trusted CAs) for WebLogic Server.

  4. Set SSL attributes for the private key alias and password.

  5. At the bottom of the page, click Advanced.

  6. Set Hostname Verification to None.

  7. Indicate the number of times WebLogic Server can use an exportable key between a domestic server and an exportable client before generating a new key. The more secure you want WebLogic Server to be, the fewer times the key should be used before generating a new key.

  8. Set the Use Server Certs control if needed. Setting this control determines whether a Web service client hosted on WebLogic Server should use the server certificates/key as the client identity when initiating a connection over HTTPS.

  9. Set the Two Way Client Cert Behavior control to Client Certs Requested and Enforced.

  10. Specify the inbound and outbound SSL certificate validation methods. These options are available:

    • Builtin SSL Validation Only: Uses the built-in trusted CA-based validation. This is the default.

    • Builtin SSL Validation and Cert Path Validators: Uses the built-in trusted CA-based validation and uses configured CertPathValidator providers to perform extra validation.

Configuring SSL for a Web Service Client

The core WebLogic Server security subsystem uses private key and X.509 certificate pairs, stored in the default keystores, for SSL.

You must ensure that the Web service client trusts the X.509 certificate that WebLogic Server uses to digitally sign the request. Do one of the following:

  1. Ensure that WebLogic Server obtains a digital certificate that the client automatically trusts, because it has been issued by a trusted certificate authority.

  2. Create a certificate registry that lists all the individual certificates trusted by WebLogic Server, and then ensure that the client trusts these registered certificates.

To configure SSL for a Web service client:

  1. Create a keystore used by the client application. Oracle recommends that you create one client keystore per application user.

    You can use the keytool utility to perform this step. For development purposes, the keytool utility is the easiest way to get started.

  2. Create a private key and digital certificate pair, and load it into the client keystore.

    Make sure that the certificate's key usage allows both encryption and digital signatures. Oracle requires a key length of 1024 bits or larger.

  3. Make sure that the following properties are set in the client's JVM:

    • javax.net.ssl.trustStore -- The name of the file that contains the trust store.

    • javax.net.ssl.trustStoreType -- The type of KeyStore object that you want the default TrustManager to use.

    • javax.net.ssl.trustStorePassword -- The password for the KeyStore object that you want the default TrustManager to use.

Configuring Two-Way SSL for a Web Service Client

Note:

See "Configuring SOA Composite Applications for Two-Way SSL Communication" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite for specific configuration steps when a SOA application is the Web service client over two-way SSL.

You must ensure that WebLogic Server is able to validate the X.509 certificate that the client uses to digitally sign its request, and that WebLogic Server in turn uses to encrypt its responses to the client. Do one of the following:

  1. Ensure that the client application obtains a digital certificate that WebLogic Server automatically trusts, because it has been issued by a trusted certificate authority.

  2. Create a certificate registry that lists all the individual certificates trusted by WebLogic Server, and then ensure that the client uses one of these registered certificates.

To configure SSL for a Web service client:

  1. Create a keystore used by the client application. Oracle recommends that you create one client keystore per application user.

    You can use the keytool utility to perform this step. For development purposes, the keytool utility is the easiest way to get started.

  2. Create a private key and digital certificate pair, and load it into the client keystore.

    Make sure that the certificate's key usage allows both encryption and digital signatures. Oracle requires a key length of 1024 bits or larger.

  3. Make sure that the following properties are set in the client's JVM:

    • javax.net.ssl.trustStore -- The name of the file that contains the trust store.

    • javax.net.ssl.trustStoreType -- The type of KeyStore object that you want the default TrustManager to use.

    • javax.net.ssl.trustStorePassword -- The password for the KeyStore object that you want the default TrustManager to use.

    • javax.net.ssl.keyStore -- The name of the file that contains the KeyStore object.

    • javax.net.ssl.keyStoreType -- The type of KeyStore object.

    • javax.net.ssl.keyStorePassword -- The password for the KeyStore.

Setting up the Keystore for Message Protection

To sign and encrypt SOAP messages you must first create and configure the Web Services Manager Keystore for a WebLogic domain. This keystore is used to store public and private keys for SOAP messages within the WebLogic Domain.

Note:

The Web services manager run time does not use the WebLogic Server keystore that is used for SSL as documented elsewhere in this chapter.

The signature and encryption keys are used to sign, verify, encrypt, and decrypt the SOAP messages.

The keystore configuration is domain wide: all Web services and Web service clients in the domain use this keystore.

To set up the keystore used by Web Services Manager follow these steps:

  1. Use the keytool to create a Java keystore, as described in "How to Create and Use a Java Keystore".

  2. In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure the keystore. Select the domain.

  3. Using Fusion Middleware Control, click WebLogic Domain, then Security, and then Security Provider Configuration.

    Click the plus sign (+) to expand the Keystore control near the bottom of the page, then click Configure.

    The Web Services Manager Keystore Configuration page is displayed, as shown in Figure 10-1.

    Figure 10-1 Web Services Manager Keystore Configuration

    Description of Figure 10-1 follows
    Description of "Figure 10-1 Web Services Manager Keystore Configuration"

  4. In the Keystore Type drop-down, select Java Key Store, which is the default.

    Note:

    Hardware security modules (HSM) are also certified to operate with Oracle Advanced Security. For more information, see Using Hardware Security Modules With Oracle WSM.
  5. Enter the path and name for the keystore that you created. By default, the keystore name is default-keystore.jks, but you can change this.

  6. Enter a password for the keystore and confirm it.

  7. Enter an alias and password for the signature and encryption keys. Confirm the passwords.

    The alias and password for the signature and encryption keys define the string alias and password used to store and retrieve the keys.

  8. Click OK to submit the changes.

    Note that all fields on this page require a restart of Oracle Enterprise Manager Fusion Middleware Control to take effect.

Note:

The Oracle WSM agent caches the keystore name and object. If you make subsequent changes to the contents of the keystore or to its name, you must restart Oracle Enterprise Manager Fusion Middleware Control.

Setting Up the Web Service Client Keystore at Design Time

You need to create a Java Key Store (JKS) keystore to store the signature and encryption keys required by the X.509 token on the client. Keys are used for a variety of purposes, including authentication and data integrity. For example:

  • To sign data, you must have the signer's private key.

  • To verify a signature, you must have a trusted CA certificate and the public key that matches the private key.

  • To encrypt data, you must have the recipient's public key. The Web service's base64-encoded public certificate is published in the WSDL for use by the Web service client, as described in "Using Service Identity Certification Extension".

  • To decrypt data, you must have the private key that corresponds to the public key.

These trusted certificates and public and private keys are stored in the keystore. The following sections describe where you can obtain trusted certificates and how to create and use these keystores.

How to Obtain a Trusted Certificate

You can obtain a certificate from a Certificate Authority (CA), such as Verisign or Entrust, and include them in the keystore. To get the certificate, you must create a Certificate Request and submit it to the CA. The CA will authenticate the certificate requestor and create a digital certificate based on the request.

How to Create and Use a Java Keystore

The Java Keystore (JKS) is the proprietary keystore format defined by Sun Microsystems. To create and manage the keys and certificates in the JKS, use the keytool utility. You can use the keytool utility to perform the following tasks:

  • Create public and private key pairs, designate public keys belonging to other parties as trusted, and manage your keystore.

  • Issue certificate requests to the appropriate Certification Authority (CA), and import the certificates which they return.

  • Administer your own public and private key pairs and associated certificates. This allows you to use your own keys and certificates to authenticate yourself to other users and services. This process is known as "self-authentication." You can also use your own keys and certificates for data integrity and authentication services, using digital signatures.

  • Cache the public keys of your communicating peers. The keys are cached in the form of certificates.

How to Create Private Keys and Load Trusted Certificates

The following section provides an outline of how to create and manage the JKS with the keytool utility. It describes how to create a keystore and to load private keys and trusted CA certificates. You can find more detailed information on the commands and arguments for the keytool utility at this Web address.

http://download.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html

  1. Create a new private key and self-signed certificate.

    Use the genKey command to create a private key. It will create a new private key if one does not exist. The following command generates an RSA key, with RSA-SHA1 as the signature algorithm, with the alias test in the test.jks keystore.

    keytool -genkey -alias test -keyalg "RSA" -sigalg "SHA1withRSA" -dname "CN=test, C=US" -keystore test.jks

    The keytool utility prompts for the needed key and keystore passwords. DSA key is not supported. Make sure you pass the parameter " -keyalg RSA " in the command.

  2. Display the keystore.

    The following command displays the contents of the keystore. It will prompt you for the keystore password.

    keytool -list -v -keystore test.jks

  3. Import a trusted CA certificate in the keystore.

    Use the -import command to import the certificate. The following command imports a trusted CA certificate into the test.jks keystore. It will create a new keystore if one does not exist. The keytool utility prompts for the needed password.

    keytool -import -alias aliasfortrustedcacert -trustcacerts -file trustedcafilename -keystore test.jks

  4. Generate a certificate request.

    Use the -certreq command to generate the request. The following command generates a certificate request for the test alias. The CA will return a certificate or a certificate chain.

    keytool -certreq -alias test -sigalg "RSAwithSHA1" -file certreq_file -storetype jks -keystore test.jks

  5. Replace the self-signed certificate with the trusted CA certificate.

    You must replace the existing self-signed certificate with the certificate from the CA. To do this, use the -import command. The following command replaces the trusted CA certificate in the test.jks keystore. The keytool utility prompts for the needed password.

    keytool -import -alias test -file trustedcafilename -keystore test.jks

Configuring SSL on Oracle HTTP Server

The HTTPS protocol uses an industry standard protocol called Secure Sockets Layer (SSL) to establish secure connections between clients and servers. You can use the HTTPS/SSL support offered by the Oracle HTTP Server as one of the communication protocols to communicate between the client and the Web service. This section describes how to set up a Web service client and a Web service using Oracle WSM policies to send requests over SSL. Oracle HTTP Server is configured as a Web proxy that intermediates between the client and Oracle WebLogic Server. SSL is enabled at Oracle HTTP Server and SSL transport is turned on between the client and Oracle HTTP Server. Communication remains non-SSL between Oracle HTTP Server and WebLogic Server. This section describes how to configure the policies that require one-way SSL and two-way SSL.

For more information, see:

One-Way SSL

For more information on the Oracle WSM policies that require one-way SSL configuration, see "Which Policies Require You to Configure SSL?".

To use one-way SSL, you need to:

  1. Configure the Oracle HTTP Server as follows:

    1. In the file ORACLE_INSTANCE/config/OHS/<ohs_name>/ssl.conf, configure Oracle HTTP Server as a Web proxy and specify the list of URLs you want to access as shown in Example 10-1.

      Example 10-1 Specifying URLs in ssl.conf

      # added properties for configuring OHS as webproxy
      <IfModule weblogic_module>
      WebLogicHost <host>
      WebLogicPort <port>
      SecureProxy Off
      WlProxySSL On
      Debug ALL
      WlLogFile /tmp/weblogic.log
      #the location attributes list the urls you want to access via OHS
      <Location
       /myWlsService>
              SetHandler weblogic-handler
              WebLogicHost <host>
              WeblogicPort <port>
      </Location>
       
      
    2. In the same file, set the following properties under virtual host configuration to ensure the client certificate information is sent to WebLogic Server:

      SSLVerifyClient optional

    3. By default, SSL in enabled on Oracle HTTP Server. The default https port is 4443. For more information on configuring this port, see "SSL Configuration in Oracle Fusion Middleware" in Oracle Fusion Middleware Administrator's Guide.

    4. Restart Oracle HTTP Server.

      For more information, see "SSL Configuration in Oracle Fusion Middleware" in Oracle Fusion Middleware Administrator's Guide.

  2. Create a wallet as described at "Managing Keystores, Wallets, and Certificates" in Oracle Fusion Middleware Administrator's Guide and replace the default wallet. The default wallet is located in the ORACLE_INSTANCE/config/OHS/<ohs_name>/keystores/default directory. See Example 10-2 for sample commands for creating a wallet.

    Example 10-2 Sample Commands for One-Way SSL

    ./orapki wallet create -wallet <wallet_location> -pwd welcome1 -auto_login
    ./orapki wallet display -wallet <wallet_location> -pwd welcome1
    ./orapki cert display -cert <wallet_location>/ohs.crt
        
    ./orapki wallet add -wallet <wallet_location> -keysize 512 -dn "CN=<host_name>,OU=st,O=owsm,L=N,ST=delhi,C=IN"
    -self_signed -validity 700 -serial_num 20 -cert <wallet_location>/ohs.crt -user_cert -pwd welcome1
        
    ./orapki wallet display -wallet <wallet_location> -pwd welcome1
        
    JAVA_HOME/bin/keytool -import -trustcacerts -file ohs.crt -alias sslcert -keystore client_keystore.jks -storepass welcome1
    
  3. In the Oracle WebLogic Administration Console, perform the following:

    1. Navigate to the Servers page in the Environment tab.

    2. Click Adminserver and in Configuration, select General.

    3. In the Advanced section, check the following: WebLogic Plug-In Enabled, and Client Cert Proxy Enabled.

    4. Save the changes.

    5. Set the same parameters for the SOA server.

      For more information, see "Server: Configuration: General" in the Oracle WebLogic Server Administration Console Help.

To modify the client to use one-way (server authentication mode), create a JSE client from the Web service using JDeveloper. Modify the parameters and properties as described in Example 10-3.

Example 10-3 JSE Client Using SSL

public static void main(String [] args)
  {
    class1Service = new Class1Service();   
        SecurityPolicyFeature[] securityFeatures =
            new SecurityPolicyFeature[] { new SecurityPolicyFeature("oracle/wss_
saml_token_over_ssl_client_policy") };
    Class1 class1 = class1Service.getClass1Port(securityFeatures);       
    ((BindingProvider) class1).getRequestContext().put(BindingProvider.ENDPOINT_
ADDRESS_PROPERTY,
        "https://<host>:4443/myWlsService/Class1Port");
       
    ((BindingProvider) class1).getRequestContext().put(BindingProvider.USERNAME_
PROPERTY, "weblogic");
    System.setProperty("javax.net.ssl.trustStore","D:\\OWSM_
QA\\11g\\PS2\\OHS\\wallet\\client_keystore.jks");
    System.setProperty("javax.net.ssl.trustStorePassword","welcome1");
    System.setProperty("javax.net.ssl.trustStoreType","JKS");   
   
    System.setProperty("weblogic.security.SSL.ignoreHostnameVerification" ,
 "true");
    System.setProperty("java.protocol.handler.pkgs",
 "com.sun.net.ssl.internal.www.protocol");
    System.setProperty("javax.net.debug","all");       
   
    System.out.println("Call to the SSL service...");           
    String response1 = class1.sayHello("test");
    System.out.println("Response = " + response1);
  }

Two-Way SSL

For more information on the Oracle WSM policies that require two-way SSL configuration, see "Which Policies Require You to Configure Two-Way SSL?".

To use two-way SSL, you need to:

  1. Configure the Oracle HTTP Server as follows:

    1. In the file ORACLE_INSTANCE/config/OHS/<ohs_name>/ssl.conf, configure Oracle HTTP Server as a Web proxy and specify the list of URLs you want to access as shown in Example 10-4.

      Example 10-4 Specifying URLs in ssl.conf

      # added properties for configuring OHS as webproxy
      <IfModule weblogic_module>
      WebLogicHost <host>
      WebLogicPort <port>
      SecureProxy Off
      WlProxySSL On
      Debug ALL
      WlLogFile /tmp/weblogic.log
      #the location attributes list the urls you want to access via OHS
      <Location /myWlsService>
              SetHandler weblogic-handler
              WebLogicHost <host>
              WeblogicPort <port>
      </Location>
      
    2. In the same file, set the following properties under virtual host configuration to ensure the client certificate information is sent to the WebLogic Server:

      SSLVerifyClient optional

      SSLOptions +StdEnvVars +ExportCertData

      SSLOptions +ExportCertData is a mod_ssl directive that ensures certificate-related information is sent to WebLogic Server. SSLOptions +StdEnvVars +ExportCertData ensures that SSL-related information is sent.

    3. By default, SSL in enabled on Oracle HTTP Server. The default https port is 4443. For more information on configuring this port, see "SSL Configuration in Oracle Fusion Middleware" in Oracle Fusion Middleware Administrator's Guide.

    4. Restart Oracle HTTP Server.

      For more information, see "SSL Configuration in Oracle Fusion Middleware" in Oracle Fusion Middleware Administrator's Guide.

  2. Create a wallet as described at "Managing Keystores, Wallets, and Certificates" in Oracle Fusion Middleware Administrator's Guide and replace the default wallet. The default wallet is located in the ORACLE_INSTANCE/config/OHS/<ohs_name>/keystores/default directory. See Example 10-5 for sample commands.

    Example 10-5 Sample Commands for Two-Way SSL

    JAVA_HOME/bin/keytool -genkey -alias twowayssl -keyalg RSA
     -keystore twowaykeystore.jks -storepass welcome1 -validity 700
    ./orapki wallet add -wallet <wallet_location> -cert
     <wallet_location>/twowayssl.crt -trusted_cert -pwd welcome1
    
  3. In the Oracle WebLogic Administration Console, perform the following:

    1. Navigate to the Servers page in the Environment tab.

    2. Click Adminserver and in Configuration, select General.

    3. In the Advanced section, check the following: WebLogic Plug-In Enabled, and Client Cert Proxy Enabled.

    4. Save the changes.

    5. Set the same parameters for the SOA server.

      For more information, see "Server: Configuration: General" in the Oracle WebLogic Server Administration Console Help.

To modify the client to use two-way (mutual authentication mode) SSL, create a JSE client from the Web service using JDeveloper. Modify the parameters and properties as described in Example 10-6.

Example 10-6 JSE Client Using SSL

public static void main(String [] args)
  {
    class1Service = new Class1Service();   
        SecurityPolicyFeature[] securityFeatures =
            new SecurityPolicyFeature[] { new SecurityPolicyFeature("oracle/wss_
username_token_over_ssl_client_policy") };
    Class1 class1 = class1Service.getClass1Port(securityFeatures);       
    ((BindingProvider) class1).getRequestContext().put(BindingProvider.ENDPOINT_
ADDRESS_PROPERTY,
        "https://<host>:4443/myWlsService/Class1Port");
       
    ((BindingProvider) class1).getRequestContext().put(BindingProvider.USERNAME_
PROPERTY, "weblogic");
    ((BindingProvider) class1).getRequestContext().put(BindingProvider.PASSWORD_
PROPERTY, "welcome1");
    System.setProperty("javax.net.ssl.trustStore","D:\\OWSM_
QA\\11g\\PS2\\OHS\\wallet\\twowaykeystore.jks");  
    System.setProperty("javax.net.ssl.trustStorePassword","welcome1");
    System.setProperty("javax.net.ssl.trustStoreType","JKS");   
    System.setProperty("javax.net.ssl.keyStore","D:\\OWSM_QA\\11g\\PS2\\OHS\\wallet\\twowaykeystore.jks");
    System.setProperty("javax.net.ssl.keyStorePassword","welcome1");
    System.setProperty("javax.net.ssl.keyStoreType","JKS");   
   
    System.setProperty("weblogic.security.SSL.ignoreHostnameVerification" ,
 "true");
    System.setProperty("java.protocol.handler.pkgs",
 "com.sun.net.ssl.internal.www.protocol");
    System.setProperty("javax.net.debug","all");       
   
    System.out.println("Call to the SSL service...");           
    String response1 = class1.sayHello("test");
    System.out.println("Response = " + response1);
  }

Using Hardware Security Modules With Oracle WSM

Hardware security modules (HSM) are certified to operate with Oracle Advanced Security. These modules provide a secure way to store keys and off-load cryptographic processing.

Using SafeNet Luna SA With Oracle WSM for Key Storage

SafeNet Luna SA is a network-attached, (HSM featuring cryptographic processing and hardware key management for applications. Luna SA is designed to protect critical cryptographic keys across a wide range of security applications.

Some key advantages of using Luna SA with Oracle WSM are:

  • Network shareability

  • Most secure with keys always in hardware

  • FIPS validated

Note:

You must contact your SafeNet representative to obtain certified hardware and software to use with Oracle Advanced Security.

By default, Oracle Web Services Manager (Oracle WSM) uses Java Key Store (JKS) for key storage. Keys and certificates required by Oracle WSM for cryptographic operations are fetched from a keystore file. When Luna SA is available in-network, it can be leveraged by Oracle WSM for key storage purposes and cryptographic operations.

This section includes the following topics:

About Installing and Configuring the Luna SA HSM Client

The Luna SA HSM client needs to be installed on the host that has a running instance of Oracle WSM. Then the Luna SA HSM client will communicate with an available Luna SA HSM network. However, this section does not cover Luna SA client installation, nor does it cover the Luna SA network installation and setup, which are out of scope for this document. Instead, you should refer to the Luna SA documentation for those instructions, at http://www.safenet-inc.com/Products/Detail.aspx?id=2147483853&terms=search.

Before you installing the Luna SA HSM client, verify the following checklist:

  • You already have Luna SA installed and available in you network.

  • You are logged in as root or as a user that has installation permission.

  • You have a Luna SA client installation CD or software image.

  • You have all required passwords for Luna SA, including an administrator password and a partition password.

Note:

You must contact your SafeNet representative to have the hardware security module, and to acquire the necessary library.

These tasks must be performed before you can use an Luna SA hardware security module with Oracle WSM

Configuring the JRE Used By Oracle WSM

After installing the Luna SA client, you need to configure the JRE that will be used by the Oracle WSM setup.

  1. Copy the following JAR files from the /usr/lunasa/jsp/lib directory to the $JAVA_HOME/jre/lib/ext directory:

    • LunaJCASP.jar

    • LunaJCESP.jar

  2. Copy the libLunaAPI.so file to the java.library.path.

  3. Edit the $JAVA_HOME/jre/lib/security/java.security file to include two Luna providers.

    At the end of the security.providers list add these two Luna providers:

    security.provider.n=com.chrysalisits.crypto.LunaJCAProvider
    security.provider.n+1=com.chrysalisits.cryptox.LunaJCEProvider
    

    where

    n specifies the preference order that determines the order in which providers are searched for requested algorithms when no specific provider is requested. The order is 1-based; 1 is the most preferred, followed by 2, and so on.

Logging On to Luna SA

Before you can use Luna SA with Oracle WSM, you must log on to the Luna SA server. This is one-time process that creates a Luna log-in session on the client machine. This session remains active until the client or server machine is rebooted, or when someone explicitly logs out of the Luna session.

You must use the salogin utility to log in. The salogin utility establishes a connection between the client and the HSM partition for a particular application. It takes an application ID as an argument. This application id consists of two parts: a high and a low ID.

Before invoking the salogin utility, you need to add an entry to the Chrystoki.conf file, which registers the application ID. The Chrystoki.conf file is usually found in the /etc/ directory. This is also a one-time process.

  1. Edit the /etc/Chrystoki.conf file by adding the application ID to the end of file. For example:

    Misc = { AppIdMajor=<major id>; AppIdMinor=<minor id>;  }
    
  2. Log into the Luna SA server, by entering:

    /salogin -o -s <partition number> -i <AppIdMajor>:<AppIdMinor> -v -p <partition_password>
    

    This opens a session for the application ID you provided. The salogin is in the /usr/lunasa/bin directory.

  3. To log out of the Luna SA server, enter:

    salogin -c -s <slot number> -i <AppIdMajor>:<AppIdMinor>
    

Copying Keys and Certificates from JKS to Luna SA

If keys and certificates are currently in the JKS, then you need to move all keys and certificates to LunaSA. You can use the cmu script provided by LunaSA for importing keys and certificates.

  • The cmu importKey command imports an RSA|DSA private key from a file onto an HSM. (Supports PKCS12(RSA), PKCS8(RSA/DSA), or PKCS1(RSA)).

  • The cmu import command imports an X.509 certificate from a file onto an HSM.

Configuring Oracle WSM to Use Luna SA

As part of configuring Oracle WSM to use Luna SA, the keystore type has to be changed to Luna from the default Java Key Store (JKS) value.

Follow these steps to configure the keystore type:

  1. In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure the keystore. Select the domain.

  2. Using Fusion Middleware Control, click WebLogic Domain, then Security, and then Security Provider Configuration.

  3. Click the plus sign (+) to expand the Keystore control near the bottom of the page, and then click Configure.

    The Web Services Manager Keystore Configuration page is displayed, as shown in Figure 10-2.

    Figure 10-2 Web Services Manager Keystore Configuration Page

    Description of Figure 10-2 follows
    Description of "Figure 10-2 Web Services Manager Keystore Configuration Page"

  4. In the Keystore Type drop-down, select Hardware Security Module (HSM).

  5. After the Keystore Configuration page refreshes, enter Luna in the HSM Provider Type field, as shown is Figure 10-3.

    Figure 10-3 Web Services Manager Keystore Configuration Page (Refreshed)

    Description of Figure 10-3 follows
    Description of "Figure 10-3 Web Services Manager Keystore Configuration Page (Refreshed)"

  6. In the Key Alias and Crypt 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.)

    For HSMs, only a 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 OK to submit the changes.

  8. Restart Fusion Middleware Control.

Using Service Identity Certification Extension

In prior releases of Oracle WSM, for Web services that implemented a message-protection policy the Web service client needed to store the Web service's public certificate in its domain-level keystore. The client then used the keystore.recipient.alias property to identify the certificate in the keystore. To do this, you either identified the keystore.recipient.alias property on the Configurations page or overrode it on a per-client basis using the Security Configuration Details control when attaching the policy (or programmatically).

In this release of Oracle WSM, for Web services that implement a message-protection policy the Web service's base64-encoded public certificate is published in the WSDL. The certificate is included for message protection policies whether or not the policy encrypts or decrypts data.

The certificate in the WSDL is the service's public key by default, as determined by the Encryption Key you specified when "Setting up the Keystore for Message Protection".

If this certificate is not found, the keystore.recipient.alias property is used instead and the certificate must be in the client's domain-level keystore as before.

Note:

Self-signed certificates must be available in the client side keystore to be trusted.

Hostname Verification Included in WSDL

This release includes a hostname verification feature that ensures that a certificate retrieved from a WSDL was not the subject of a substitution attack or "man in the middle" attack and is indeed the expected certificate.

To to this, Oracle WSM validates that the common name (CN) or the subject Group Base Distinguished Name (DN) in the certificate matches the hostname of the service.

This feature depends upon the subject DN of the certificate.

By default, hostname verification is disabled.

Enabling or Disabling Service Identity Certificate Extension and Hostname Verification

You use Fusion Middleware Control to enable or disable service identity certificate extension and hostname verification.

The properties on the Identity Extension tab enable you to specify whether to enforce Web service policies by publishing the X509 certificate in the WSDL. In addition, if the X509 is published, you can also specify whether to ignore hostname verification.

Service identity certificate extension is enabled by default; hostname verification is disabled by default.

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 "Setting up the Keystore 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 "Setting up the Keystore 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. From the navigation pane, expand WebLogic Domain.

  3. Select the domain in which you want to enable or disable service identity certificate extension and hostname verification.

  4. Using Fusion Middleware Control, click WebLogic Domain.

  5. Select Web Services, and then select Platform Policy Configuration.

  6. Select the Identity Extension tab.

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

    • wsm.ignore.identity.wsdl – 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 run time for encryption. You can disable the consumption of the X509 Certificate by changing the default setting to true.

    • wsm.ignore.hostname.verification – Specifies 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.

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

  9. Click Apply to apply the property updates.

Ignoring the Service Identity Certificate Extension From the Client

Note:

If the client overrides the keystore.recipient.alias property (oracle.wsm.security.util.SecurityConstants.ClientConstants.WSS_RECIPIENT_KEY_ALIAS in a client programmatic override), the override is always used, and not the certificate published in the WSDL.

For a Java EE client, the value of the wsm.ignore.identity.wsdl property is read automatically and no additional configuration is required. Set this property in Fusion Middleware Control to turn identity verification on and off, as described in "Enabling or Disabling Service Identity Certificate Extension and Hostname Verification".

For a JSE client, the Web service client must take explicit action to ignore the certificate in the WSDL and rely solely on the keystore.recipient.alias property it sets.

To do this, set the value of wsm.ignore.identity.wsdl to true:

BindingProvider.getRequestContext().put(SecurityConstants.ClientConstants.WSM_IGNORE_IDENTITY_WSDL, "true");

Ignoring Hostname Verification from the Client

For a Java EE client, the value of the wsm.ignore.hostname.verification property is read automatically and no additional configuration is required. Set this property in Fusion Middleware Control to turn hostname verification on and off, as described in "Enabling or Disabling Service Identity Certificate Extension and Hostname Verification".

For a JSE client, the Web service client must take explicit action to ignore hostname verification.

To do this, set the value of wsm.ignore.hostname.verification to true:

BindingProvider.getRequestContext().put(SecurityConstants.ClientConstants.WSM_IGNORE_HOSTNAME_VERIFICATION,"false");

Configuring the Credential Store Provider

The credential store provider provides a way to store, retrieve, and delete credentials for a Web service and other applications.

For example, the oracle/wss_http_token_client_policy policy includes the csf-key property, with a default value of basic.credentials. The basic.credentials credential is stored in the credential store provider. You need to change the value of basic.credentials credential to a valid username and password in the Oracle Platform Security Services identity store.

Follow these steps to configure the credential store provider:

  1. In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure the keystore. Select the domain.

  2. Using Fusion Middleware Control, click WebLogic Domain, then Security, and then Credentials.

    The Credential Store Provider Configuration page is displayed, as shown in Figure 10-4. (In this figure, the Credential Store Provider control has already been expanded.)

    Figure 10-4 Credential Store Provider Configuration Page

    Description of Figure 10-4 follows
    Description of "Figure 10-4 Credential Store Provider Configuration Page"

  3. Click Create Map and enter the map name oracle.wsm.security, as shown in Figure 10-5.

    Figure 10-5 Set Security Provider Screen

    Description of Figure 10-5 follows
    Description of "Figure 10-5 Set Security Provider Screen"

  4. Click Create Key. The Create Key dialog box appears, as shown in Figure 10-6.

    Figure 10-6 Create Key Dialog Box

    Description of Figure 10-6 follows
    Description of "Figure 10-6 Create Key Dialog Box"

  5. Select the map name oracle.wsm.security if it is not already selected.

  6. Enter the key name.

  7. Select the key type, either Password or Generic. A password credential can store a username and password. A generic credential can store any credential object.

  8. For a password credential, enter the username and password.

  9. Click OK.

  10. Restart Fusion Middleware Control.

Configuring an Authentication Provider in WebLogic Server

This section introduces WebLogic Server security features that are described in detail in Securing Oracle WebLogic Server and in the Oracle WebLogic Server Administration Console Help. This section provides only a brief introduction to the security features, and concentrates on how they relate to configuring policies.

The security policies that you use determine what types of security providers you must configure in WebLogic Server. You can categorize the policies based on their token type:

What Type of WebLogic Security Authentication Providers Must You Create?

You can use any WebLogic Authentication provider that can validate the credentials in the NameCallback and PasswordCallback callbacks, or the NameCallback alone, as appropriate. This means that you can use the WebLogic Default Authentication provider and authenticate the user against the embedded LDAP data store if you so choose, or the Default Identity Asserter, and so forth. See "Configure Authentication and Identity Assertion Providers" in the Oracle WebLogic Server Administration Console Help for information on how to do this.

Configuring the SAML and Kerberos Login Modules

The SAML and Kerberos 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 policy and make any needed changes.

You can configure the following SAML and Kerberos login modules:

(Login modules associated with other policy types do not have settings specific to the Web service policies.)

To configure a login module:

  1. In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure the login module. Select the domain.

  2. Using Fusion Middleware Control, click WebLogic Domain, then Security, and then Security Provider Configuration.

  3. From the list of login modules, select a login module and click Edit.

    For example, if you select the saml.loginmodule from the list of login modules and click Edit, the Edit Login Module page shown in Figure 10-7is displayed.

    Figure 10-7 Edit Login Module Page for SAML Login Module

    Description of Figure 10-7 follows
    Description of "Figure 10-7 Edit Login Module Page for SAML Login Module"

    Note:

    Do not edit the default values in the General Properties section or unexpected results may occur. The default values for these properties are as follows:
    • Control Flag —Required

    • Debug — true

    • Add All Roles — true

    • Log Level — Fine

  4. Optionally, in the SAML Specific Attributes section, configure an alternate Issuer attribute if required for your configuration. For SAML policies, the Issuers attribute is required. This attribute specifies the name of the issuer of the SAML or SAML2 token. For predefined Oracle SAML policies and assertions, the default value is www.oracle.com. If you are using the predefined SAML policies (or assertions) for both the Web service client and Web service sides, you can generally use the defaults and not configure any issuer. For more information, see "Adding an Additional SAML Assertion Issuer Name".

  5. In the Custom Properties section of the page, configure any custom properties for the login module.

    To add a property, click Add and enter a property name and value in the Add New Property window. Click OK to add the property to the Custom Properties list.

    To change the value of an existing property, you need to delete the property from the Custom Properties list and add a new property with the revised value.

Table 10-1 lists the SAML and Kerberos login modules and describes properties that you can configure.

Table 10-1 SAML and Kerberos Login Modules Attributes and Properties

Login Module Service Name Property Description

saml.loginmodule

saml2.loginmodule

oracle.security.jps.assert.saml.identity

A domain-wide property used to determine the mapping between the SAML subject and the user. Valid values include:

  • false—When this flag 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. This is the default.

  • true—When this flag is set to true, the SAML subject is treated as a logical/virtual user. 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 Identity Assertion Provider is not invoked for all SAML policies in the domain using this login module.

 

oracle.security.jps.add.assertion.to.subject

Boolean flag used to indicate whether the SAML assertion should be added to the authenticated subject as a private credential. The default is true.

krb5.loginmodule

principal

The name of the principal that should be used. It can be a simple username, such as "testuser", or a service name such as "host/testhost.eng.sun.com". 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.

 

useKeyTab

True or false. Set this to true if you want the module to get the principal's key from the keytab (default value is False). If 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.

 

storeKey

Set this to True to if you want the principal's key to be stored in the Subject's private credentials.

 

keyTab

Set this to the file name of the keytab to get principal's secret key.

 

doNotPrompt

Set this to true if you do not want to be prompted for the password if credentials cannot be obtained from the cache or keytab (default is false). If set to true, authentication will fail if credentials cannot be obtained from the cache or keytab.


Configuring SAML

The SAML standard defines a common XML framework for creating, requesting, and exchanging security assertions between software entities on the Web. The SAML Token profile is part of the core set of WS-Security standards, and specifies how SAML assertions can be used for Web services security. SAML also provides a standard way to represent a security token that can be passed across the multiple steps of a business process or transaction, from browser to portal to networks of web services.

If you use any of the following predefined policies, you must configure SAML:

The following sections provide more information about SAML configuration:

How the SAML Token is Validated

The SAML login module verifies the SAML tokens on behalf of the Web service. The SAML login module then extracts the username from the verified token and (indirectly) passes it to Oracle Platform Security Services (OPSS) to complete the perimeter authentication.

Which Authentication Provider is Used?

Any configured Identity Assertion provider (that handles the NameCallback, as described in "Configuring an Authentication Provider in WebLogic Server" can then be invoked.

The provider then simply checks whether the user exists (identity assertion mode) and, if it does, the user is asserted and a subject is established.

How to Configure SAML Web Service Client at Design Time

Follow the steps described in this section to configure the SAML Web service client at design time. (If you attach the SAML policies to the Web service client at deploy time, you do not need to configure these properties and they are not exposed in Fusion Middleware Control.)

You can also include user roles in the assertion and change the SAML assertion issuer name, as described in subsequent sections.

Configure the Username for the SAML Assertion

For a JSE client application, configure the username as a BindingProvider property:

Map<String,Object>  reqContext = ((BindingProvider) proxy).getRequestContext()   reqContext.put( BindingProvider.USERNAME_PROPERTY, "jdoe")

where proxy refers to the Web service proxy used for invoking the actual Web service.

For a Java EE client, if the user is already authenticated and a subject is established in the container, then the username is obtained from the subject automatically and no additional configuration is required.

For example, if user jdoe is already authenticated to the Java EE application and you are making a Web service call from that Java EE application, the username jdoe will be automatically propagated.

However, if the user is not authenticated, then you need to configure the username in the BindingProvider as in the JSE case.

Including User Attributes in the Assertion

SAML client policies include the user.attributes property that you can use to add user attributes to the SAML assertion.

To do this, you specify the attributes to be included as a comma-separated list. For example, attrib1,attrib2. The attribute names you specify must exactly match valid attributes in the configured identity store.

user.attributes requires that the Subject is available and subject.precedence is set to true.

The Oracle WSM runtime reads the values for these attributes from the configured identity store, and then includes the attributes and their values in the SAML assertion.

The user.attributes property is supported for a single identity store, and by default only the first identity store in the list is used. The user must therefore exist and be valid in the identity store used by the configured WebLogic Server Authentication provider. Authentication providers are described in "Configuring an Authentication Provider in WebLogic Server".

If you have more than one identity store configured, and you want to search for the user in all identity stores, follow these steps to enable searching in all configured identity stores.

  1. In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure the identity store provider. Select the domain.

  2. Using Fusion Middleware Control, click WebLogic Domain, then Security, and then Security Provider Configuration.

  3. In the Identity Store Provider section of the page, click Configure to configure parameters that interact with the identity store.

    The Identity Store Configuration page is displayed, as shown in Figure 10-8.

    Figure 10-8 Identity Store Configuration Page

    Description of Figure 10-8 follows
    Description of "Figure 10-8 Identity Store Configuration Page"

  4. Click Add to add a custom property.

  5. Add the property "virtualize" with a value of "true", as shown in Figure 10-9.

    Figure 10-9 Adding the virtualize property

    Description of Figure 10-9 follows
    Description of "Figure 10-9 Adding the virtualize property"

  6. Click OK to submit the changes.

  7. Restart Fusion Middleware Control.

Including User Roles in the Assertion

You can pass the user's role as an attribute statement in the SAML assertion. To do this at post-deploy time, configure the user.role.include property to "true." The default value in the policy is "false."

To configure the user's role at design time, set the user.role.include property to "true" in the BindingProvider.

How to Configure Oracle Platform Security Services (OPSS) for SAML Policies

Follow these steps to configure OPSS for the predefined SAML policies:

  1. Configure the SAML login module, as described in "Configuring the SAML and Kerberos Login Modules".

    By default, the SAML assertion issuer name is www.oracle.com. The saml.issuer.name client property must be www.oracle.com if you are using the predefined SAML policies (or assertions) on both the Web service client and Web service sides. Therefore, you can generally use the defaults and not configure any issuer.

    See "Adding an Additional SAML Assertion Issuer Name" for information on adding an additional issuer.

  2. Configure the identity assertion provider in the WebLogic Server Administration Console.

  3. If you will be using policies that involve signatures related to SAML assertions (for example, SAML holder-of-key policies) where a key referenced by the assertion is used to sign the message, or sender-vouches policies where the sender's key is used to sign the message, you need to configure keys and certificates for signing and verification, as described in "Setting up the Keystore for Message Protection".

  4. If you will be using policies that require SSL, you need to configure SSL, as described in "Configuring Keystores for SSL".

Adding an Additional SAML Assertion Issuer Name

The SAML issuer name is generally www.oracle.com if you are using the predefined SAML policies (or assertions) on both the Web service client and Web service sides. Therefore, you can generally use the defaults and not configure any issuer.

There are two circumstances in which you need to add additional issuers:

  • For a SAML predefined Web service policy or assertion, you set a value for the saml.trusted.issuer property. If you set a value for this property, you must add that trusted issuer to the Issuers list.

  • For SAML client side policy or assertion, you set a value for the saml.issuer.name property. If you set a value for this property, you must add that trusted issuer to the Issuers list with the same value.

  • If a different client, for instance .NET/STS, is talking to a Web service protected by a predefined SAML policy, then you need to add that issuer to the Issuers list.

To add an additional SAML assertion issuer to the Issuers list:

  1. In the navigator pane, expand WebLogic Domain to show the domain for which you need to add the issuer. Select the domain.

  2. Using Fusion Middleware Control, click WebLogic Domain, then Security, and then Security Provider Configuration.

  3. Select the SAML or SAML2 login module as appropriate and click Edit.

  4. From the SAML Specific Attributes section of the page, click Add to add an additional issuer name, as shown in Figure 10-10.

    Figure 10-10 Adding a SAML Issuer to the Login Module

    Description of Figure 10-10 follows
    Description of "Figure 10-10 Adding a SAML Issuer to the Login Module"

  5. For a client policy, at deploy time, specify a value for saml.issuer.name on the Configurations page for the SAML client policy, or override it on a per-client basis using the Security Configuration Details control when you attach the policy. The default value in the policy is www.oracle.com.

    To configure the issuer at design time, set the saml.issuer.name property in the BindingProvider.

Configuring SAML Web Service Clients for Identity Switching

Oracle WSM includes the wss11_saml_token_identity_switch_with_message_protection_client_policy policy that enables identity switching. Identity switching means that the policy propagates a different identity than the one based on the authenticated Subject.

You might have a scenario in which your SOA application needs to specify which user identity to use in client-side Web service policies, and then dynamically switch the user associated with the SAML token in the outbound Web service request. Instead of using the username from the Subject, this policy allows you to set a new user name when sending the SAML Web service request.

The wss11_saml_token_identity_switch_with_message_protection_client_policy policy creates the SAML token based on the user ID set via the property javax.xml.ws.security.auth.username.

Consider the following use case in which a Web service client calls a SOA application, which in turn becomes the client for a Web service.

client -> SOA -> web service

In this use case:

  • The client is secured with the wss11_username_with_message_protection_client_policy policy. It communicates with the SOA entry point as user end_user1.

  • The SOA entry point is protected by wss11_username_with_message_protection_service_policy. The SOA application authenticates the end user and establishes the Subject based on end_user1. However, it wants to propagate a different identity to the external Web service.

    Therefore, to do identity switching, attach the wss11_saml_identity_switch_message_protection_client_policy policy to the SOA reference binding component.

  • The username that is propagated is determined dynamically by the BPEL process, which is a component in the SOA application. The username is set as BPEL property javax.xml.ws.security.auth.username with the dynamically determined username value. The external Web service can be protected by wss11_saml_with_message_protection_service_policy. It receives the switched user and not end_user1.

  • A similar scenario can be used by a J2EE application (replacing SOA in this scenario with the J2EE application) that establishes the Subject based on an end user but then needs to propagate a different identity. In case of J2EE, you can set the user name programmatically as follows:

    ((BindingProvider) port).getRequestContext().put(BindingProvider.USERNAME_PROPERTY, config.get(USERNAME));
    
  • Use Fusion Middleware Control to add the WSIdentityPermission permission to the SOA reference binding component.

    The wss11_saml_token_identity_switch_with_message_protection_client_policy policy requires that an application to which the policy is attached must have the WSIdentityPermission permission. That is, applications from which Oracle WSM accepts the externally-supplied identity must have the WSIdentityPermission permission.

    This is to avoid potentially rogue applications from providing an identity to Oracle WSM.

Note:

The wss11_saml_token_identity_switch_with_message_protection_client_policy policy disables local optimization (see "Configuring Local Optimization for a Policy" for SOA to SOA interactions on the same server.

This policy is compatible with the wss11_saml_token_with_message_protection_service_policy policy on the Web service.

Set the javax.xml.ws.security.auth.username Property

For SOA:

The SOA composite has a BPEL process as one SOA service component. A BPEL process provides process orchestration and storage of synchronous and asynchronous processes.

You can define a BPEL property with the exact name javax.xml.ws.security.auth.username. The value for this property can be the identity that the SOA application wants to propagate, which could potentially be determined dynamically by the BPEL process.

For J2EE:

Set the BindingProvider.USERNAME_PROPERTY property.

Set the WSIdentityPermission Permission

The Web service client (for example, the SOA reference binding component) to which you attached the wss11_saml_token_identity_switch_with_message_protection_client_policy policy must have the oracle.wsm.security.WSIdentityPermission permission.

To use Fusion Middleware Control to add the oracle.wsm.security.WSIdentityPermission permission to the SOA reference binding component as a System Grant, perform the following steps:

  1. In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure the application. Select the domain.

  2. Using Fusion Middleware Control, click WebLogic Domain, then Security, and then System Policies. System policies are the system-wide policies applied to all applications deployed to the current WebLogic Domain.

  3. From the System Policies page, select the arrow icon in the Permission field to search the system security grants.

  4. Select one of the codebase permissions to use as a starting point and click Create Like.

  5. In the Grant Details section of the page, enter file:${common.components.home}/modules/oracle.wsm.agent.common_11.1.1/wsm-agent-core.jar in the Codebase field.

  6. In the Permissions section of the page, select the starting point permission class and click Edit.

  7. Enter oracle.wsm.security.WSIdentityPermission in the Permission Class field. The resource name is the composite name for SOA, and the application name for a J2EE client. The action is always assert, as shown in Figure 10-11.

    Figure 10-11 Editing the WSIdentityPermission

    Description of Figure 10-11 follows
    Description of "Figure 10-11 Editing the WSIdentityPermission"

To use WLST to add the oracle.wsm.security.WSIdentityPermission permission, execute the following command:

grantPermission(codeBaseURL="file:${common.components.home}/modules/
oracle.wsm.agent.common_11.1.1/wsm-agent-core.jar",
     permClass="oracle.wsm.security.WSIdentityPermission",
     permTarget="resource=yourAppName",
     permActions="assert")

In this command:

  • codeBaseURL must point to wsm-agent-core.jar.

  • permTarget syntax is "resource=yourAppName/compositeName". The resource name is the composite name for SOA, and the application name for a J2EE client.

  • permActions is always "assert".

Defining a Trusted Distinguished Names List for SAML Signing Certificates

For additional security, you can define a list of trusted distinguish names (DNs) for SAML signing certificates.

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

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

For more information about defining a trusted DNs list for SAML signing certificates, see "Defining a Trusted Distinguished Name List for SAML Signing Certificates".

Note:

In this release, the trusted DNs list is valid for SAML sender vouches and holder-of-key policies only; it is not valid for SAML bearer policies.

Using Kerberos Tokens

Oracle Fusion Middleware 11g Release 1 (11.1.1) provides support for Kerberos tokens with the following predefined policies:

You may also create a policy using the following assertion templates:

See Appendix C, "Predefined Assertion Templates" and Appendix B, "Predefined Policies" for more information on these assertions and policies.

Configuring the KDC

Follow the steps described in this section to configure the Key Distribution Center (KDC) for use by the Web service client and Web service.

You can also use Microsoft Active Directory with KDC. See "Using Active Directory with Kerberos and Message Protection".

Initializing and Starting the MIT Kerberos KDC

Initialize KDC database. For example, on UNIX you might run the following command as root, where oracle.com is your default realm:

root# /usr/kerberos/sbin/krb5_util -r oracle.com -s

Start the kerberos service processes. For example, on UNIX you might run the following commands as root.:

root# /usr/kerberos/sbin/krb5kdc &
root# /usr/kerberos/sbin/kadmind &

Creating Principals

Create two accounts in the KDC user registry. The first account is for the end user; that is, the Web service client principal. The second account is for the Web service principal.

One way to create these accounts is with the kadmin.local tool, which is typically provided with MIT KDC distributions. For example:

>sudo su - # become root
>cd /usr/kerberos/sbin/kadmin.local
>kadmin.local>addprinc fmwadmin -pw welcome1
>kadmin.local> addprinc SOAP/myhost.oracle.com -randkey
>kadmin.local>listprincs # to see the added principals

The Web service principal name (SOAP/myhost.oracle.com) is shown in the example as being created with a random password. The Web service principals use keytables (a file that stores the service principal name and key) to log into Keberos System. Using a random password increases security.

Configuring the Web Service Client to Use the Correct KDC

The Web service client needs to be configured to authenticate against the right KDC.

The configuration for the KDC resides at /etc/krb5.conf for UNIX hosts, and at C:\windows\krb5.ini for Windows hosts.

A sample krb5.conf is shown in Example 10-7. Note the following:

  • The file tells the kerberos run time the realm of operation and the KDC endpoint to contact.

  • For Kerberos token policies to work, three additional properties need to be specified in the libdefaults section of this file:

    • default_tkt_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc

    • default_tgs_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc

    • permitted_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc

  • The order of cipher suites is significant. For Keberos message protection to work, the first in the list needs to "des3-cbc-sha1". This is because Oracle WSM supports the encryption algorithm TripleDES, but not plain DES.

Example 10-7 Sample krb5.conf File

[logging]
default = FILE:/var/log/krb5libs.log
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmind.log
 
[libdefaults]
default_realm = oracle.com
dns_lookup_realm = false
dns_lookup_kdc = false
default_tkt_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tgs_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc
permitted_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc
 
[realms]
oracle.com =
{kdc = someadminserver.com:88  admin_server = someadminserver.com:749   
 
 
default_domain = us.oracle.com  }
[domain_realm]
us.oracle.com = oracle.com
 
[kdc]
profile = /var/kerberos/krb5kdc/kdc.conf
 
[appdefaults]
pam =
{   debug = false    ticket_lifetime = 36000   renew_lifetime = 36000    
 
 
forwardable = true    krb4_convert = false  }

Setting the Service Principal Name In the Web Service Client

The Web service client that is enforcing Kerberos client side policies needs to know the service principal name of the service it is trying to access. You set the service principal name in "Creating Principals".

You can specify a value for service.principal.name on the Configurations page, or override it on a per-client basis using the Security Configuration Details control when you attach the policy. The default (place holder) value is HOST/localhost@oracle.com.

Setting the Service Principal Name In the Web Service Client at Design Time

The Web service client that is enforcing Kerberos client side policies needs to know the service principal name of the service it is trying to access. You set the service principal name in "Creating Principals".

Use a configuration override to specify the service principal name at design time, as follows:

JAX-WS Clients: 
((BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSSEC_KERBEROS_SERVICE_PRINCIPAL, 
SOAP/myhost.oracle.com@oracle.com);

Configuring the Web Service to Use the Right KDC

Configure the Web service to authenticate against the right KDC. The configuration for the KDC resides at /etc/krb5.conf for UNIX hosts, and at C:\windows\krb5.ini for Windows hosts.

A sample KDC configuration for a Web service client is shown in Example 10-7. This example also applies to the Web service KDC configuration.

Using the Correct Keytab File in Enterprise Manager

To use the correct keytab file, you

  • Extract and install the keytab File

  • Modify the krb5 login module

These tasks are described in the sections that follow.

Extract and Export the Keytab File

Extract the key table file, which is often referred to as the keytab, for the service principal account from the KDC and install on the machine where the Web service implementation is hosted.

For example. you can use a tool such as kadmin.local to extract the keytab for the service principal name, as follows:

>kadmin.local>ktadd -k /tmp/krb5.keytab SOAP/myhost.oracle.com

Export the keytab file to the machine where the Web service is hosted. The keytab is a binary file; if you ftp it, use binary mode.

Modify the krb5 Login Module to use the Keytab File

Modify the krb5 login module as described in "Configuring the SAML and Kerberos Login Modules" to identify the location of the Web service KDC file.

For example, assume that the keytab file is installed at /scratch/myhome/krb5.keytab. Note the changes for the keytab and principal properties:

  • principal value=SOAP/myhost.oracle.com@oracle.com

  • useKeyTab value=true

  • storeKey value=true

  • keyTab value=/scratch/myhome/krb5.keytab

  • doNotPrompt value=true

Authenticating the User Corresponding to the Service Principal

The Web services run time must be able to verify the validity of the kerberos token.

If the token is valid, Oracle Platform Security Services (OPSS) must then be able to authenticate the user corresponding to the service principal against one of the configured WebLogic Server Authentication providers. (Authentication providers are described in "Configuring an Authentication Provider in WebLogic Server".)

The user must therefore exist and be valid in the identity store used by the Authentication provider.

For example, consider a service principal such as SOAP/myhost.oracle.com@oracle.com. In this example, a user with the name SOAP/myhost.oracle.com must exist in the identity store. Note that @domain should not be part of your user entry.

Creating a Ticket Cache for the Web Service Client

Perform the following steps to create a ticket cache for the Web service client:

  1. Log in to the Kerberos system using the user principal you created for the client.

    >kinit fmwadmin welcome1
    
  2. This creates a ticket cache on the file system with ticket granting ticket. To see this:

    >klist -e
    

    Information similar to the following is displayed:

    Credentials cache: /tmp/krb5cc_36687
    Default principal: fmwadmin@oracle.com, 1 entry found.
    [1]  Service Principal:  krbtgt/oracle.com@oracle.com
         Valid starting:  Sep 28, 2007 17:20
         Expires:         Sep 29, 2007 17:20
             Encryption type: DES3 CBC mode with SHA1-KD
    

    Make sure the encryption type reflects what is shown above.

  3. Run the Web service client.

Alternatively, you can run the Web service client without first logging into the Kerberos . You are prompted for the Kerberos user name and password. Note that in this case a ticket cache is not created on the file system; it is maintained in memory.

Using Active Directory with Kerberos and Message Protection

You can use Microsoft Active Directory with the Key Distribution Center (KDC) as your KDC. This section describes how to configure the KDC through Active Directory for use with Kerberos and message protection.

This section assumes that you are already familiar with Active Directory. See your Active Directory documentation for additional details.

Setting Up the Web Service Client

This section describes the following tasks:

Create a User Account

Use Active Directory to create a new user account. Do not use DES encryption. By default, the user account is created with RC4-HMAC.

For example, you might create a user testpol with the user logon name test/testpol.

The user logon name should be of the form container/name. You can create the account in any container.

Create a Keytab File

Use ktpass to create a keytab file:

ktpass -princ test/testpol@{domain} -pass {...}  -mapuser testpol -out
 testpol.keytab -ptype KRB5_NT_PRINCIPAL  -target {domain}

where test/testpol is the Service Principal Name and it is mapped to the user testpol. Do not set /desonly or cyrpto as des-cbc-crc.

Set the Service Principal Name

Use setSpn to map the Service Principal Name to the user:

setSpn -A test/testpol testpol
setSpn -L testpol (this should display the availabel mapping)

There should be only one Service Principal Name mapped to the user. If there are multiple Service Principal Names mapped to the user, remove them using setSpn -D <spname> <username>.

Set Up the Web Service

Perform the following steps to set up the Web service:

  1. Attach the Kerberos policy to your Web service.

  2. Configure the Web service client to authenticate against the right KDC.

    The configuration for the KDC resides at /etc/krb5.conf for UNIX hosts, and at C:\windows\krb5.ini for Windows hosts.

    Configure the default domain and realm in the krb5.conf or krb5.ini file. Enable the RC4-HMAC encryption type (available in JDK6).

    [libdefaults]
     
    default_tkt_enctypes = rc4-hmac
    default_tgs_enctypes = rc4-hmac
    permitted_enctypes = rc4-hmac
    
  3. Export the keytab file you created in "Create a Keytab File" to the system where the Web service is hosted. The keytab is a binary file; if you ftp it, use binary mode.

  4. Verify the keytab file using kinit:

    kinit -k -t <absolute path the the keytab file> <Service Principal Name> 
    
  5. Modify the krb5 login module as described in "Configuring the SAML and Kerberos Login Modules" to specify the keytab location and the Service Principal Name.

    Use the absolute path to the keytab file. Also, be sure to add @realmname to the Service Principal Name. For example:

    principal value=test/testpol@oracle.com
    

SAML Message Protection Use Case

Assume that you have a Web service client that you want to protect with the wss11_saml_token_with_message_protection_client_policy policy, and a corresponding Web service that you want to protect with the wss11_saml_token_with_message_protection_service_policy policy.

This section steps through the procedure for using these two policies.

The following topics are described:

What You Need to Know

This section describes what you need to know to configure this SAML message protection use case. The following topics are described:

Requirements of the wss11_saml_token_with_message_protection_service_policy Policy

wss11_saml_token_with_message_protection_service_policy enforces message-level protection (that is, message integrity and message confidentiality), and SAML-based authentication for inbound SOAP requests in accordance with the WS-Security 1.1 standard.

Messages are protected using WS-Security's Basic 128 suite of symmetric key technologies, specifically RSA key mechanisms for message confidentiality, SHA-1 hashing algorithm for message integrity, and AES-128 bit encryption. For more information about the available algorithms for message protection, see "Supported Algorithm Suites".

Therefore, when you use the keytool (or other tool) to create the signature and encryption keys needed by this policy, you need to make sure you use the RSA key mechanism, the SHA-1 algorithm, and AES-128 bit encryption to satisfy the policy requirements for the key.

How Are Messages Protected Via Symmetric Keys?

This policy uses symmetric key technology. Symmetric key cryptography relies on a single, shared secret key, as follows:

  1. The client creates the symmetric key, uses it to sign and encrypt the message, and shares it with the Web service in the request message.

    To protect the symmetric key, the symmetric key sent in the request message is encrypted using the service's certificate.

  2. The Web service uses the symmetric key in the request message to verify the signature of the request message and decrypt it, and to then sign and encrypt the response message.

Consider the following process flow.

To create the request, the Oracle WSM agent does the following:

  1. Generates the shared symmetric key and uses it to both sign and encrypt the request message.

  2. Uses its own private key to "endorse" the signature of the request message.

  3. Uses the Web service's public key to encrypt the symmetric key.

  4. Sends the symmetric key along with the request to the Web service. The client sends its public key in the request so that the Web service can verify the endorsement.

When the Web service gets the request, it does the following:

  1. Uses its private key to decrypt the symmetric key.

  2. Uses the symmetric key to decrypt the request message and to verify its signature.

  3. Uses the client's public key in the request message to verify the endorsement signature.

To send the response back to the client, the Web service does the following:

  1. Uses the same client-generated symmetric key sent along with the request to sign the response message.

  2. Uses the same client-generated symmetric key to encrypt the response message.

When the Oracle WSM agent receives the response message, it does the following:

  1. Uses the symmetric key it generated initially to decrypt the response message.

  2. Uses the symmetric key it generated initially to verify signature of the response message.

What Keys Must Be in the Keystore?

If the client and Web service are in the same domain with access to the same keystore, they can share the same private/public key pair.

That is, the client can use the private key “orakey” to endorse the signature of the request message and the public key “orakey” to encrypt the symmetric key. The Web service in turn uses the public key “orakey” to verify the endorsement, and the private key “orakey” to decrypt the symmetric key.

For demonstration purposes, this use case creates one key pair.

Multi-Domain Use Case (Keystore Hardening)

If the client and Web service are not in the same domain and do not have access to the same keystore, the client and Web service must each have a private/public key pair.

Consider the following requirements in a multiple-domain use case, as shown in Table 10-2.

Table 10-2 Multiple-Domain Use Case Requirements

Web Service Client Web Service

Needs its own private/public key pair in the client keystore.

Needs its own private/public key pair in the service keystore.

Needs the Web service public key.

Needs the intermediary and root certificate corresponding to the client's public key in the keystore.

These certificates will be used to verify the signature by generating a trusted certificate chain.

Generates symmetric key at run time

Needs the symmetric key, but this is sent in the request message.


For the public key the client uses to encrypt the symmetric key -- that is, the public key of the Web service -- you have two approaches:

  • The Web service's base64-encoded public certificate is published in the WSDL for use by the Web service client, as described in "Using Service Identity Certification Extension". Therefore, in this use the Web service's public key does not have to be in the client's keystore.

  • As an alternative, you can specify a value for keystore.recipient.alias on the Configurations page, or override it on a per-client basis using the Security Configuration Details control when you attach the policy. The keystore recipient alias specifies the alias used to look up the public key in the keystore when retrieving a key for encryption of outbound SOAP messages. In this use the Web service's public key must be in the client's keystore.

When to Override the SAML Issuer

The saml.issuer.name property of the client policy identifies the issuer of the SAML token, and defaults to a value of www.oracle.com. This use case uses the www.oracle.com default.

You can optionally specify a value for saml.issuer.name on the Configurations page, or override it on a per-client basis using the Security Configuration Details control when you attach the policy.

If you do use a different SAML authority (issuer) in the policy, that issuer name must be configured in the client and included in the list of possible issuers in the SAML login module. See "Adding an Additional SAML Assertion Issuer Name" for information on how to do this.

Main Steps

This section describes the steps you follow to configure the SAML message protection use case. The following topics are described:

Create a WebLogic Server User

The user in the SAML token must already exist in the WebLogic Server identity store.

The Web service run time extracts the SAML token from the WS-Security header and uses the name in the SAML token to validate the user against the WebLogic Server identity store.

Specifically, the SAML login module (see "Configuring the SAML and Kerberos Login Modules" verifies the SAML tokens on behalf of the Web service. The SAML login module then extracts the username from the verified token and (indirectly) passes it to Oracle Platform Security Services (OPSS) via the NameCallback to complete the perimeter authentication.

Any configured WebLogic Server authentication provider (identity asserter) that handles the JAAS NameCallback can then be invoked, including the default Authentication provider.

The WebLogic Authentication provider then simply checks whether the user exists (identity assertion mode) and, if it does, the user is asserted and a subject is established.

Create the User

You use the WebLogic Server Administration Console to add the user to the identity store, as described in the Oracle WebLogic Server Administration Console Help.

The steps are repeated here for ease of use.

To create a user in the WebLogic Server Administration Console:

  1. In the left pane select Security Realms.

  2. On the Summary of Security Realms page select the name of the realm (for example, myrealm).

  3. On the Settings for Realm Name page select Users and Groups and then Users.

    The User table displays the names of all users defined in the Authentication provider.

  4. Click New.

  5. In the Name field of the Create New User page enter the name of the user.

    User names are case sensitive and must be unique. Do not use commas, tabs or any other characters in the following comma-separated list: <>, #, |, &, ?, ( ), { }

  6. (Optional) In the Description field, enter a description. The description might be the user's full name.

  7. In the Provider drop-down list, select the Authentication provider for the user.

    If multiple WebLogic Authentication providers are configured in the security realm, they will appear in the list. Select which WebLogic Authentication provider's database should store information for the new user.

  8. In the Password field, enter a password for the user.

    The minimum password length for a user defined in the WebLogic Authentication provider is 8 characters.

  9. Re-enter the password for the user in the Confirm Password field.

  10. Click OK to save your changes.

    The user name appears in the User table.

Create a Java Keystore

This section provides an outline of how to create and manage the Java keystore with the keytool utility. It describes how to create a keystore and load the private key and trusted CA certificates.

You can find more detailed information on the commands and arguments for the keytool utility at the following Web address: http://download.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html.

Note:

You specify an alias when you add an entity to the keystore using the -genkey command to generate a key pair (public and private key), or when you use the -import command to add a certificate or certificate chain to the list of trusted certificates.

Subsequent keytool commands must use this same alias to refer to the entity.

  1. Create a new key pair and self-signed certificate.

    Use the genKey command to create the key pair (public and private key). genKey creates a new private key if one does not exist.

    The following command generates an RSA key, with RSA-SHA1 as the signature algorithm, with the alias "orakey" in the default-keystore.jks keystore. You can choose any alias name; you do not need to name your alias "orakey".

    keytool -genkey -alias orakey -keyalg "RSA" -sigalg "SHA1withRSA" -dname "CN=test, C=US" -keystore default-keystore.jks
    

    The keytool utility prompts for the needed key and keystore passwords. You need these passwords later.

  2. Generate a certificate request to the certificate authority.

    Use the -certreq command to generate the request. The following commands generates a certificate request for the orakey alias.

    The CA will return a certificate or a certificate chain.

    keytool -certreq -alias orakey -sigalg "SHA1withRSA" -file certreq_file -storetype jks -keystore default-keystore.jks
    
  3. Replace (import) the self-signed certificate with the trusted CA certificate.

    You must replace the existing self-signed certificate with the certificate returned from the CA. To do this, use the -import command. The following command replaces the trusted CA certificate in the default-keystore.jks keystore. The keytool utility prompts for the needed password.

    keytool -import -alias orakey -file trustedcafilename -keystore default-keystore.jks
    

Configure the Web Services Manager Keystore

Perform the following steps to configure the Oracle Web Services Manager keystore:

  1. In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure the keystore. Select the domain.

  2. Using Fusion Middleware Control, click WebLogic Domain, then Security, and then Security Provider Configuration.

    Click the plus sign (+) to expand the Keystore control near the bottom of the page, then click Configure.

    The Web Services Manager Keystore Configuration page is displayed, as shown in Figure 10-1.

  3. If it is not already enabled, click the Configure Keystore Management check box.

  4. Enter the path and name for the keystore that you created. By default, the keystore name is default-keystore.jks, as used in this use case. The keystore type must be JKS.

  5. Enter the password for the keystore and confirm it.

  6. Enter the alias and password for the signature and encryption keys.

    In this use case, orakey is the alias for both the signature and encryption keys.

    Confirm the passwords.

  7. Click OK to submit the changes.

    Note that all fields on this page require a restart of Fusion Middleware Control to take effect.

Store the Password for the Decryption Key in the Credential Store

You must store the password for the decryption key in the credential store, as described in "Configuring the Credential Store Provider". Use keystore.enc.csf.key as the key name.

Attach the Policy to Your Web Service

Attach wss11_saml_token_with_message_protection_service_policy to your Web service as described in "Attaching a Policy to a Single Subject".

Configure the policy assertion for message signing and message encryption.

The default is to sign and encrypt the entire body for the request the response. You have the option to not do this and to instead specify the specific body elements that you want to sign and encrypt. You can also additionally specify header elements that you want to sign and encrypt. Whatever you set here mush match the client policy settings.

Note:

You can override keystore.sig.csf.key and keystore.enc.csf.key, as described in "Attaching Web Service Policies Permitting Overrides".

If you do override these values, the keys for the new values must be in the keystore. That is, overriding the values does not free you from the requirement of configuring these keys in the keystores.

Attach the Policy to Your Web Service Client

Attach wss11_saml_token_with_message_protection_client_policy to your Web service client, as described in {"Attaching Policies to Web Service Clients".

Configure the policy assertion for message signing, message encryption, or both.

The default is to sign and encrypt the entire body. You have the option to not do this and to instead specify the specific body elements that you want to sign and encrypt. You can also additionally specify header elements that you want to sign and encrypt. Whatever you set here must match the Web service policy settings.

The Web service's base64-encoded public certificate is published in the WSDL for use by the Web service client, as described in "Using Service Identity Certification Extension". The certificate in the WSDL is the service's public key by default, as determined by the encryption key you specified (“orakey”) when you configured the Web Services Manager keystore.

Therefore, you do not need to set or change keystore.recipient.alias.

You can optionally specify a value for saml.issuer.name on the Configurations page, or override it on a per-client basis using the Security Configuration Details control when you attach the policy. The saml.issuer.name property defaults to a value of www.oracle.com. See "When to Override the SAML Issuer".

You can specify a value for user.roles.include on the Configurations page, or override it on a per-client basis using the Security Configuration Details control when you attach the policy.

WS-Trust Policies and Configuration Steps

This section describes the predefined WS-Trust policies and how to configure and use them. The following topics are described:

Overview of Web Services WS-Trust

The WS-Trust 1.3 specification defines extensions to WS-Security that provide a framework for requesting and issuing security tokens, and to broker trust relationships. WS-Trust extensions provide methods for issuing, renewing, and validating security tokens.

To secure communication between a Web service client and a Web service, the two parties must exchange security credentials. As defined in the WS-Trust specification, these credentials can be obtained from a trusted SecurityTokenService (STS), which acts as trust broker. That is, the STS must be trusted by both the Web service client and the Web service to provide interoperable security tokens.

This section describes the following topics:

How the STS Configuration is Obtained

Typically, your environment will have only one STS. If you have a hundred different Web services, all of which have attached this STS config policy, you can easily change all of your Web services to point to a different STS by changing the policy.

The STS is also a Web service. To communicate with the STS, the client application needs to know the STS details, such as the port-uri, port-endpoint, wsdl-uri, and the security tokens it can accept from clients trying to authenticate to it.

There are two mechanisms by which STS information becomes available to the client.

  • Automatic (Client STS) Policy Configuration (see "Setting Up Automatic Policy Configuration for STS") is involved. Automatic Policy Configuration dynamically generates the information about the STS by parsing the STS WSDL document.

    Automatic Policy Configuration is triggered when the STS config policy is attached to the Web service and not the client. Additionally, the only information provided in the STS config policy is the port-uri of the target STS.

    When this policy is attached to the Web service along with the issued token service policy, the port-uri of the STS appears as the Issuer-Address in the IssuedToken assertion of the Web service WSDL. As a result, all the other STS information (target namespace, service name, endpoint, and so forth) is obtained by accessing the STS WSDL and is saved in memory as the STS config. This information is stored only in memory and is not persisted in MDS.

    If you specify the STS URI in the Web service STS config policy and attach it to the Web service, the client is forced to use that STS; it cannot override it.

  • You do not use Automatic Policy Configuration and instead attach the STS config policy to the client and specify all the STS-related information (port-endpoint, port-uri, public key alias, a reference to an Oracle WSM client policy to be used for authenticating to the STS) before invoking the Web service. In this case, all the information is already available to the run time from the STS config policy.

Typical Token Request and Response

The general token request/response process works as follows. These steps are explained further in the use case described in "Example WS-Trust Use Case".

  1. The Web service client wants to invoke a Web service. The Oracle WSM agent attempts to fetch the WSDL of the Web service and extract the issued token service policy. The Oracle WSM agent uses the local client policy (as optionally overridden) to talk to the STS identified in the WSDL.

    The Web service policy can require the issued token to be from a specific STS.

  2. The Web service client requests that the STS issue a token. The Web service client can request the token from a specific STS.

    The Request Security Token (RST) is a request for a security token. The RequestSecurityTokenResponse (RSTR) is a response generated by the STS in response to the RST with claims for the requested user.

  3. The Web service client processes the RSTR sent by the STS and propagates the issued token to the Web service.

  4. The Web service processes and verifies the issued token and generates a response back.

Example WS-Trust Use Case

This section describes a sample use case for WS-Trust.

  1. The Web service client invokes a Web service. The WSDL for the Web service indicates that the Web service requires a security token from a specific STS.

  2. The Web service client (the requestor) sends an authentication request, with accompanying credentials, to the STS.

  3. The STS verifies the credentials presented by the client, and then in response issues a security token that provides proof that the client has authenticated with the STS. The response message RSTR has the token and (optionally) claims for the authenticated user.

  4. The requestor verifies the RSTR, extracts the token, and passes it to the Web service.

  5. The Web service receives the issued token and verifies that the token was issued by a trusted STS. This proves that the client has successfully authenticated with the STS.

    Once the token is validated, the Web service processes the request and responds back.

Figure 10-12 illustrates the message flows between the requestor, STS, and the Web service.

Figure 10-12 STS Use Case Message Flow

Description of Figure 10-12 follows
Description of "Figure 10-12 STS Use Case Message Flow"

On Behalf Of Use Cases

"On Behalf Of" is an identity propagation use case, in which the Web service client requests the STS token on behalf of another entity.

Consider the following scenario:

  1. The Web service client invokes the STS to get a token for another entity. This entity can be the end user or any other external entity. The entity's credentials are included in the RST in the onBehalfOf element.

  2. The STS verifies the credentials presented by the Web service client and issues a security token for the entity identified in the onBehalfOf element.

  3. The Web service client verifies the RSTR, extracts the token, and passes it to the Web service.

  4. The Web service receives the SAML assertion for the end user and verifies that the token was issued by a trusted STS.

The "On Behalf Of" use case relies on the sts.auth.on.behalf.of.csf.key and on.behalf.of properties described in Table 8-1. If the "On Behalf Of" username is obtained from the Subject, it is a username without a password.

If sts.auth.on.behalf.of.csf.key identifies a CSF key for the "On Behalf Of" user entity, the identity established using that CSF key is sent on behalf of the other entity. It can be a username with or without a password.

Token Lifetime

The RSTR response message from an STS may contain a lifetime element (<trust:Lifetime>) indicating the validity of the returned token. If the lifetime element is present, Oracle WSM validates the timestamp and rejects the message if the response has expired.

What Token Types Are Exchanged?

Although an STS can theoretically receive any token from the client and exchange it for any other token, in practice the STS generally accepts one of the following tokens and returns a SAML assertion:

  • Username token. For this token type:

    1. The Web service client sends a user name and password to the STS.

    2. The STS verifies the password and returns a SAML assertion.

    3. The client sends the SAML assertion to the Web service.

    This scenario is useful when the Web service does not have the ability to verify passwords, so it relies on the STS to verify them.

  • Kerberos token. For this token type:

    1. The client sends a user name and password to a KDC and gets a Kerberos token.

    2. The client sends the Kerberos token to the STS and gets a SAML assertion.

    3. The client sends the SAML assertion to the Web service.

    This scenario is useful in Windows environments. Clients running on the Windows machine have the logged-on user context, and they can use this context to get a SAML assertion from the STS for that user.

    In this scenario, the clients do not have the password so they cannot use a username token, they can use only Kerberos.

  • X509 token -- For this token type the client uses a private key to authenticate itself to the STS.

In response, the STS generally returns one of the following tokens:

  • SAML Holder of Key Symmetric. The SAML assertion that is returned by the STS is meant only for the particular client that sent its client token (username token, Kerberos, X509, etc) to the STS.

    A rogue client should not be allowed to steal this SAML assertion and use it. This is accomplished by a “proof key,” which can be either symmetric or asymmetric.

    A symmetric proof key is generated on the STS side, or on the client side, or by taking inputs from both sides, as described in "How the Proof Key is Determined (SAML HOK Only)".

    The STS puts this symmetric proof key in the SAML HOK assertion in an encrypted form that only the Web service can decrypt. Then, it signs the entire SAML assertion (including the encrypted proof key) and sends it to the client.

    When the client sends this SAML assertion to the server, it also needs to sign something with this proof key. The Web service will at first verify the STS signature of the SAML assertion, extract the proof key from the SAML assertion, and then decrypt it and verify the client's signature. This client's signature “proves” to the server that the client has the proof key.

    Because this proof key is never sent in clear text, a rogue client cannot get it by network sniffing. Even if a rogue client gets the SAML assertion by network sniffing, it cannot make use of it, because it does not have the proof key and cannot sign with it. Therefore, the rogue client cannot prove to the server that it is allowed to use the SAML assertion.

  • SAML Holder of Key Asymmetric. The asymmetric proof key works as follows.

    1. The client generates a public/private key pair.

    2. It keeps the private key and securely sends the public key to the STS along with its token (username token, Kerberos, X509, and so forth.)

    3. The STS verifies the client's token, and returns a SAML assertion containing the public key. The entire SAML assertion (including the public key) is signed by the STS and returned to the client.

    4. The client then sends a SAML HOK asymmetric assertion to a Web service, and it signs something with the private key of that public-private key pair.

    5. The Web service verifies the STS's signature of the SAML assertion, then extracts the public key from the SAML assertion and uses it to verify the client's signature.

      This client's signature proves to the Web service that the SAML assertion is being used correctly, and was not stolen and replayed.

    Note:

    Unlike in the case of SAML HOK symmetric key, this public key in SAML HOK is not encrypted. This reduces the amount of configuration required on the STS side.

    For SAML HOK symmetric, the STS must be configured with each Web service's certificate so that it can encrypt the symmetric key for that Web service. This is not required for SAML HOK asymmetric.

    Also, the same SAML HOK asymmetric token can be sent to any Web service because it is not encrypted with a particular Web service's key.

    Note:

    Even though there is a public/private key pair, there is no certificate involved. That is, the public key is not sent to a Certificate Authority to request a certificate.

    Instead, the STS acts similar to a CA. A CA takes in a public key and returns a certificate. In this case, the STS takes in a public key and returns a SAML assertion.

    However, unlike a certificate whose lifetime is usually in many years, the SAML assertion issued by the STS usually has a lifetime of a few hours, after which the client would have to generate a new key pair and request a new SAML assertion.

    Because of this short life, there is no need for the revocation checking that is required for certificates. This makes it attractive on the client side, because there are no client keys to manage.

  • SAML Bearer -- The SAML bearer key has no proof key associated with it. Therefore, it must be used over SSL to prevent any rogue client from stealing and replaying it.

How the Proof Key is Determined (SAML HOK Only)

For SAML Holder of Key (HOK), a proof key is required to protect communications between the client and the Web service. The proof key indicates proof of possession of the token associated with the requested security token.

You specify the requirements for the proof key type in the oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy policy in the <key-type> entry in the <sp:IssuedToken> policy assertion. For example,

<orasp:request-security-token-templateorasp:key-type = "Symmetric"

or

orasp:key-type = "Public"

Symmetric, asymmetric, and no proof key (not defined) are supported.

These possible values of <key-type> are contained in the WS-Trust 1.3 specifications:

  • http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey

  • http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey

Calculating a Symmetric Proof Key

If a symmetric proof key is required by the Web service's security policy, the requestor can pass some key material (entropy) that can be included in the calculation of the proof key. The Web service policy can indicate whether client entropy, STS entropy, or both are required.

However, the STS determines what to use for the proof key. When processing the token request, the STS can:

  • Accept the client entropy as the sole key material for the proof key. In this case, there is no <wst:RequestedProofToken> element present in RSTR; the proof key is implied.

    The Oracle WSM agent uses the client entropy as the key material for signing and encryption.

  • Accept the client entropy as partial key material and contribute additional STS server-side entropy as partial key material to compute the proof key as a function of both partial key materials.

    There is a <wst:Entropy> element containing the STS-supplied entropy in the RSTR. The <wst:RequestedProofToken> element is also present in RSTR and it contains the computed key mechanism. The default value for the algorithm is http://docs.oasis-open.org/ws-sx/ws-trust/200512/CK/PSHA1.

    The Oracle WSM agent and the STS compute the proof key by combining both entropies using the specified computed key mechanism.

  • Reject the client-side entropy and use the STS server-side entropy as the sole key material for the proof key.

    There is a <wst:RequestedProofToken> element present in RSTR that contains the proof key. The Oracle WSM agent uses the STS entropy as the key material for signing and encryption.

Requesting an Asymmetric Proof Key

An asymmetric proof key uses private/public key pairs, and is termed "asymmetric" because the public and private keys are different.

When requesting an asymmetric key token, the RST includes the wst:KeyType element with the following URI: http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey.

Overview of Sender Vouches in WS-Trust

An STS typically returns a SAML HOK or SAML Bearer token. However, an STS can also return SAML sender vouches tokens.

SAML sender vouches has a completely different trust model. In HOK and Bearer the the SAML assertion is issued by an STS and is signed by the STS. In this case, the Web service does not trust the client directly, but it trusts the STS. When the Web service receives an HOK or Bearer token, it verifies the signature against the trusted STS.

This indirect trust model greatly simplifies the trust store management. That is, if there are five clients talking to five Web services using message protection, then each of the Web services must know the five client public keys. Therefore, if there an STS in between, the Web services need to know only the public key of the STS.

For SAML sender vouches, the Web service trusts the client directly. A SAML sender vouches token is typically directly generated by a client and signed by the client private key. However a client may choose to ask the STS to generate the token. The STS does not sign the SAML assertion in this case, and simply returns it to the client. The client signs the SAML sender vouches token as before and sends it to the Web service. The Web service is not aware that the client obtained the SAML sender vouches token from an STS and it checks the client signature.

Setting Up Automatic Policy Configuration for STS

Automatic Policy Configuration dynamically generates the information about the STS by parsing the STS WSDL document.

When the STS config policy is attached to the Web service (and not to the client) Automatic Policy Configuration happens at run time on the first connect from client to server.

The only information you provide in the STS config policy (oracle/sts_trust_config_service_policy) is the port-uri of the target STS. When this policy is attached to the Web service (along with the issued token service policy) the port-uri of the STS appears as the Issuer-Address in the IssuedToken assertion of the Web service WSDL.

As a result, Oracle WSM obtains the other STS information (target namespace, service name, endpoint, and so forth) by accessing the STS WSDL and is saved in memory as the STS config. This information is saved in memory but is not persisted in MDS.

This section describes the following topics:

Requirements for Automatic Policy Configuration

There are several requirements for successfully communicating with the STS using Automatic Policy Configuration:

  • The oracle/sts_trust_config_service_policy policy must be attached to the Web service. If it is not, you cannot use Automatic Policy Configuration and must instead manually configure the oracle/sts_trust_config_client_policy policy for the client, as described in "Manually Configuring the STS Config Policy From the Web Service Client: Main Steps".

  • Automatic Policy Configuration cannot be used for SAML sender vouches confirmation because the trust is between the Web service and the client. The Web service WSDL will not have any information about the STS.

  • The certificate and public key alias of the STS must be in the keystore. The default alias name is sts-csf-key. See "Setting up the Keystore for Message Protection" for information on how to do this.

  • The client's public key must be available in the STS keystore.

Setting Up Automatic Policy Configuration: Main Steps

Perform the following steps to use Automatic Policy Configuration.

  1. "Configure a Policy for Automatic Policy Configuration"

  2. "Configure a Web Service Client for Automatic Policy Configuration"

  3. "Configure a Web Service for Automatic Policy Configuration"

Configure a Policy for Automatic Policy Configuration

Perform the following steps to configure a policy for automatic policy configuration:

  1. Decide which STS your Web service trusts and import that STS's public certificate into the Oracle WSM keystore.

  2. Optionally, add the Distinguished Name of the STS to the Trusted STS list, as described in "Defining a Trusted Distinguished Name List for SAML Signing Certificates".

  3. If you want to use SAML HOK symmetric, you need to add an entry in the Oracle OpenSSO STS configuration for your Web service and the certificate of your Web service. The STS encrypts symmetric keys using this certificate.

  4. Make a copy of the sts_trust_config_service_policy policy.

  5. Edit the orasp:port-uri field to add the port-uri of the STS.

    An STS usually exposes multiple URI points for different input and output token types; use the URI corresponding to the token that you want. For Oracle OpenSSO STS, the possible values for orasp:port-uri are as follows:

    • http://<host:port>/openssosts/sts/wss10x509

    • http://<host:port>/openssosts/sts/wss10un

    • http://<host:port>/openssosts/sts/wss11kerberos

    • https://<host:ssl_port>/openssosts/sts/tlswss10un

Configure a Web Service Client for Automatic Policy Configuration

Perform the following steps to configure a Web service client for automatic policy configuration:

  1. Attach the issue token policy to your Web service client, depending on what type of token the Web service requires.

    The following predefined issue token policies are provided:

    • oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy for SAML HOK.

    • oracle/wss_sts_issued_saml_bearer_token_over_ssl_client_policy for SAML Bearer.

  2. Set or override the following properties of the issued token policy depending on the use case. See Table 8-1 for the property descriptions.

    • sts.auth.user.csf.key

    • sts.auth.x509.csf.key

    • sts.keystore.recipient.alias

    • sts.auth.keytab.location

    • sts.auth.caller.principal.name

    • sts.auth.service.principal.name

    • sts.auth.on.behalf.of.csf.key

    • on.behalf.of

    sts.keystore.recipient.alias is used for the client to STS communication for message protection and is sufficient if the client to STS communication is using wss11 message protection.

    However, if it is using wss10 message protection, you need to additionally set up the signing key and encryption key for the client, and then import the trust for these keys into the STS configuration.

  3. Make sure the STS public certificate and credentials are present in the keystore and the client's public key is available in the STS keystore. See "Setting up the Keystore for Message Protection" for information on how to do this.

Configure a Web Service for Automatic Policy Configuration

  1. Attach the edited sts_trust_config_service_policy to the Web service.

  2. Attach the issued-token service policy (corresponding to the one attached to the client). There are two predefined issue token policies:

    • oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy -- Use this when you want your service to accept SAML HOK asymmetric or symmetric. Do not use SSL for this policy.

      As with all other wss11 message protection policies, you must set up an encryption key.

      You can modify some options in the policy. For example, whether you want SAML 1.1 or 2.0, and whether you want asymmetric or symmetric keys.

    • oracle/wss_sts_issued_saml_bearer_token_over_ssl_service_policy -- Use this when you want SAML Bearer. However, you must set up your Web service for SSL to use this policy.

      You can specify whether you want SAML 1.1 or 2.0.

  3. Override keystore.enc.csf.key in the issued-token service policy, if required.

  4. Make sure the client's public key is available in the Web service keystore.

Manually Configuring the STS Config Policy From the Web Service Client: Main Steps

You are encouraged to configure the STS config policy from the Web service, as described in "Setting Up Automatic Policy Configuration for STS". However, if you did not configure the STS config policy from the Web service, or if you are using the SAML sender vouches confirmation method, you must then configure it from the Web service client.

Perform the following steps to configure the STS config policy from the Web service client.

  1. Optionally, use Fusion Middleware Control to create a new policy from the oracle/sts_trust_config_template (see "Creating a New Web Service Policy") or from an existing oracle/sts_trust_config_client_policy policy (see "Creating a Web Service Policy from an Existing Policy").

    You might find that having a unique policy makes configuration more obvious.

  2. Use Fusion Middleware Control to edit your chosen oracle/sts_trust_config_client_policy policy.

  3. The predefined oracle/sts_trust_config_client_policy policy is shown in Example 10-8. At a minimum, you need to provide the following information:

    • Issuer address -- Port-uri is the actual endpoint URI of the STS.

    • OWSM security policy reference -- policy-reference-uri is the client policy URI that will be used by the client to communicate with the STS. The policy you choose depends on the authentication requirements of the STS, as identified in its WSDL.

      How you set this parameter determines what you must later set or override in the issue token client policy:

      • If policy-reference-uri points to a username-based policy, then you later configure the sts.auth.user.csf.key parameter to authenticate to STS and create a username token. You also configure sts.auth.x509.csf.key to specify the signature and encryption key alias.

      • If the policy-reference-uri points to an x509-based policy, then you later configure the sts.auth.x509.csf.key parameter to specify the X509 certificate for authenticating to the STS.

    • port-endpoint -- This is the endpoint of the Web service, specified as target-namespace#wsdl.endpoint(service-name/port-name).

    • Alias of STS Certificate -- sts-keystore-recipient-alias is the alias of the STS certificate you added to the keystore. The default alias name is sts-csf-key.

    Example 10-8 oracle/sts_trust_config_client_policy

    <orasp:sts-trust-config
     xmlns:orasp="http://schemas.oracle.com/ws/2006/01/securitypolicy"
     xmlns:orawsp="http://schemas.oracle.com/ws/2006/01/policy"
     orasp:policy-reference-uri="oracle/wss10_username_token_with_message_protection_client_policy"
     orasp:port-endpoint="target-namespace#wsdl.endpoint(service-name/port-name)"
     orasp:port-uri="http://host:port/sts-service" orasp:soap-version="12"
     orasp:sts-keystore-recipient-alias="sts-csf-key"
     orasp:wsdl-uri="http://host:port/sts?wsdl" orawsp:Enforced="true"
     orawsp:Silent="true" orawsp:category="security/sts-config" orawsp:name="STS Trust Configuration">
    <orawsp:bindings>
    <orawsp:Config orawsp:configType="declarative" orawsp:name="StsTrustConfig">
    <orawsp:PropertySet orawsp:name="standard-security-properties">
    <orawsp:Property orawsp:contentType="constant" orawsp:name="role" orawsp:type="string">
    <orawsp:Value>ultimateReceiver</orawsp:Value>
    </orawsp:Property>
    </orawsp:PropertySet>
    </orawsp:Config>
    </orawsp:bindings>
    </orasp:sts-trust-config>
    
  4. Save your changes.

  5. If you have not already done so, select an issue token client policy from the client policies listed in Table 10-3. Your choices are:

    • oracle/wss_sts_issued_saml_bearer_token_over_ssl_client_policy

    • oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy

    • oracle/wss11_sts_issued_saml_with_message_protection_client_policy

  6. Attach both Web service client policies to your Web service client, as described in "Attaching Client Policies Permitting Overrides". You must attach the policies in this order:

    1. sts_trust_config_client_policy

    2. Issued token client policy

    If you attach multiple instances of oracle/sts_trust_config_client_policy, no error is generated. However, only one instance is enforced, and you cannot control which instance that is.

  7. Use Fusion Middleware Control to edit your chosen issue token client policy.

  8. Save your changes.

Using SAML Sender Vouches with WS Trust

To set up SAML sender vouches with WS-Trust, configure the Web service without an issued token policy; that is, use the oracle/wss11_saml_token_with_message_protection_service_policy policy.

Configure the client with an issue token policy. Use the oracle/wss11_sts_issued_saml_with_message_protection_client_policy, which is meant for SAML sender vouches, and also an STS config policy.

The Automatic Policy Configuration feature (see "Setting Up Automatic Policy Configuration for STS") cannot be used for SAML sender vouches because the Web service WSDL will not have information about the STS.

Available WS-Trust Policies

The available WS-Trust policies are listed in Table 10-3.

Table 10-3 Available WS-Trust Policies

Name Description

oracle/sts_trust_config_service_policy

Use this policy to specify the STS configuration information that is used to invoke the STS for token exchange. You use this policy with the Web service.

oracle/sts_trust_config_client_policy

Use this policy to specify the STS configuration information that is used to invoke the STS for token exchange. You use this policy with the Web service client only when not using Automatic Policy Configuration.

oracle/wss_sts_issued_saml_bearer_token_over_ssl_client_policy

This policy inserts SAML bearer assertion issued by a trusted STS. Messages are protected using SSL.

oracle/wss_sts_issued_saml_bearer_token_over_ssl_service_policy

This policy authenticates users using credentials provided in SAML tokens with confirmation method bearer in the WS-Security SOAP header. The credentials in the SAML token are authenticated against a SAML login module. The policy verifies that the transport protocol provides SSL message protection. This policy can be applied to any SOAP-based endpoint.

oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy

This policy inserts a SAML HOK assertion issued by a trusted STS. Messages are protected using proof key material provided by STS.

oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy

This policy authenticates a SAML HOK assertion issued by a trusted STS. Messages are protected using WS-Security's Basic 128 suite of symmetric key technologies.

oracle/wss11_sts_issued_saml_with_message_protection_client_policy

This policy inserts a SAML sender vouches assertion issued by a trusted STS. Messages are protected using the client's private key.


Programmatic Configuration Overrides for WS-Trust Client Policies

Table 11-2 shows the properties you can set via programmatic configuration overrides for a given policy.

Table 10-4 describes a series of sample use cases that show how to override STS properties programmatically.

Table 10-4 STS Programmatic Configuration Use Cases

Use Case Sample Code

Token exchange username token – SAML with symmetric proof key

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_USER_CSF_KEY, "my-user-csf-key");

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

Token exchange x509 token – SAML with symmetric proof key

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

Token exchange username token – SAML with asymmetric proof key

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_USER_CSF_KEY, "my-user-csf-key");

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

Token exchange x509 token – SAML with asymmetric proof key

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

On Behalf Of token exchange with On Behalf Of username from Subject, requestor token username – SAML with symmetric proof key

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_USER_CSF_KEY, "my-user-csf-key");

on.behalf.of must be set to true.

On Behalf Of token exchange with On Behalf Of username, requestor token username – SAML with symmetric proof key

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_ON_BEHALF_OF_CSF_KEY, "my-on-behalf-of-csf-key");

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

on.behalf.of must be set to true.

On Behalf Of token exchange with On Behalf Of username, with requestor token x509 – SAML with symmetric proof key

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_ON_BEHALF_OF_CSF_KEY, "my-on-behalf-of-csf-key");

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

on.behalf.of must be set to true.

On Behalf Of token exchange with On Behalf Of username from Subject, with requestor token username – SAML with asymmetric proof key

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_USER_CSF_KEY, "my-user-csf-key");

on.behalf.of must be set to true.

On Behalf Of token exchange with On Behalf Of username, with requestor token username – SAML with asymmetric proof key

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_ON_BEHALF_OF_CSF_KEY, "my-on-behalf-of-csf-key");

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_USER_CSF_KEY, "my-user-csf-key");

on.behalf.of must be set to true.

On Behalf Of token exchange with On Behalf Of username, with requestor token x509 - SAML with asymmetric proof key

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_ON_BEHALF_OF_CSF_KEY, "my-on-behalf-of-csf-key");

(BindingProvider) port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

on.behalf.of must be set to true.


Supported STS Servers

Oracle WSM provides a standard WS-Trust client. This client has been certified to interoperate with OpenSSO STS server. To step through example scenarios using OpenSSO STS server, see "Examples Using WS-Trust with OpenSSO STS".

Examples Using WS-Trust with OpenSSO STS

The following sections provide end-to-end examples using WS-Trust with Open SSO Security Token Service (STS) server to configure the following security scenarios:

Configuring OpenSSO STS

The following procedure describes the steps required to configure OpenSSO STS for use with each of the example scenarios described in this section.

  1. Log in to the OpenSSO STS instance.

  2. Navigate to Configuration > Global > Security Token Service.

  3. Under Security: Security Mechanism: Security Token Accepted by STS Services enable all options.

  4. Under the Credential for User Token section, add a new credential for the token with the name and password set as required. Set this to test/test.

  5. Under the On Behalf of Token section, select ldapService from the Authentication Chain for On Behalf of Token drop-down list.

  6. Under the Signing section, enable the following options:

    - Is Request Signature Verified

    - Is Response Signed Enabled (select Body and Timestamp)

  7. Under the Encryption section, enable the following options:

    - Is Request Decrypted (select Body and Header)

    - Is Response Encrypted

  8. Select AES from the Encryption Algorithm drop-down list, and select 128 from the Encryption Strength drop-down list.

  9. To support the WS-Security 1.1 Kerberos token with message protection requestor token, under the Kerberos Configuration section and configure the following values:

    Table 10-5 OpenSSO STS Kerberos Token With Message Protection Configuration

    Configure this property . . . To specify . . .

    Kerberos Domain Server

    Fully qualified hostname of the domain server.

    Kerberos Domain

    Domain name.

    Kerberos Service Principal

    Service principal name in the following format: <host>/<machine name>@<REALM NAME>

    Kerberos Key Tab File

    Location of the key tab file created for the STS.

    Is Verify Kerberos Signature

    Enable only when JDK6 is used.


  10. To support SSL, perform the following steps:

    1. In the Token Issuance Attributes section, edit the SSL Endpoint based on your OpenSSO instance.

    2. Under Signing, enable the Disable signature validation when transport is secured with SSL option.

    3. Under Encryption, enable the Disable decryption when transport is secured with SSL option.

  11. To support SSL on the server hosting the OpenSSO STS:

    • On the WebLogic Server hosting the OpenSSO STS, to configure SSL, perform the steps described in "Configuring Keystores for SSL".

    • On Glassfish server hosting the Open SSO STS, perform the following steps:

      1. Generate a new key pair for the application server by issuing the following command:

        keytool -genkey -keyalg <algorithm for generating the key pair> -keystore keystore.jks -validity <days> -alias <alias_name>

        For example:

        keytool -genkey -keyalg RSA -keystore <glassfish_install_dir>/domains/<sts_deploy_domain>/config/keystore.jks -validity 365 -alias owsm

        When prompted for first and last name, enter the hostname of the machine for which the certificate is to be generated. Also enter the appropriate details for the other prompts.

      2. Generate a Certificate Signing Request (CSR) by issuing the following command:

        keytool -certreq -alias owsm -file owsm.csr -keystore keystore.jks -storepass changeit

        The request that is generated and written to the owsm.csr file needs to be submitted to a Certificate Authority in order to get a valid certificate. For example, the Certificate Management Server maintained by the OpenSSO QA team at https://mahogany.red.iplanet.com.

      3. Access the Certificate Management Server at https://mahogany.red.iplanet.com, click SSL Server in the left pane, and paste the contents of the .csr file, starting from BEGIN CERTIFICATE REQUEST and ending at END CERTIFICATE REQUEST, into the PKCS # 10 Request field.

        Fill out the other fields, as appropriate, and submit the request. Once the request is approved, the certificate can be retrieved from the retrieval tab on the same page.

      4. Copy the certificate content (PKCS # 7 format) starting from BEGIN CERTIFICATE to END CERTIFICATE into a file with .cert extension and import the server certificate into the <glassfish_install_dir>/domains/<sts_deploy_domain>/config/keystore.jks file by using the following keytool command:

        keytool -import -v -alias owsm -file owsm.cert -keystore keystore.jks -storepass changeit

        Enter YES when prompted if you trust the certificate.

      5. Access the Certificate Authority's SSL Certificate. Go to https://mahogany.red.iplanet.com and navigate to SSL Server -> Retrieval tab -> List Certificates -> Find. Click on the first Details button on the page and copy the Base 64 encoded certificate into another .cert file. For example: mahogany.cert

      6. Import this certificate with alias as "rootca" into the <glassfish_install_dir>/domains/<sts_deploy_domain>/config/cacerts.jks file, using the following command:

        keytool -import -v -alias rootca -file mahogany.cert -keystore cacerts.jks -storepass changeit

      7. The previous step may need to be repeated for client side truststore.jks file. Delete any existing rootca aliases from that file and import the new one as shown above (changing the location of the keystore file).

      8. To configure GlassFish with the new certificate, access the Administration Console at http://hostname:admin-port/. Navigate to Configuration -> HTTP Service -> http-listener2 (default SSL enabled port) -> SSL, and change the certificate nickname from s1as (self-signed cert) to owsm.

      9. Restart Glassfish.

SAML Holder-of-Key With Message Protection Scenario

The following procedure describes how to configure SAML holder-of-key with message protection using WS-Trust with OpenSSO STS. This example uses a WebLogic Web service and SOA Composite client to demonstrate the scenario.

To configure SAML holder-of-key with message protection using WS-Trust with OpenSSO STS:

  1. Configure OpenSSO STS, as described "Configuring OpenSSO STS".

  2. Configure the STS service policy following the steps described in "Configure a Policy for Automatic Policy Configuration".

    Make a copy of oracle/sts_trust_config_service_policy and edit the policy configuration, as described below, based on the requestor token type.

    To support WS-Security 1.0 username token with message protection requestor token:

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss10un"

    • orasp:wsdl-uri="http://<host>:<port>/openssosts/sts/wss10un?wsdl" (Optional)

    To support WS-Security 1.0 username token over SSL with message protection requestor token:

    • orasp:port-uri="https://<host:ssl_port>/openssosts/sts/tlswss10un"

    • orasp:wsdl-uri="https://<host:ssl_port>/openssosts/sts/tlswss10un?wsdl" (Optional)

    To support WS-Security 1.0 X509 token with message protection requestor token:

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss10x509"

    • orasp:wsdl-uri="http://<host>:<port>/openssosts/sts/wss10x509?wsdl" (Optional)

    To support WS-Security 1.1 Kerberos token with message protection requestor token:

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss11kerberos"

    • orasp:wsdl-uri="http://<host>:<port>/openssosts/sts/wss11kerberos?wsdl" (Optional)

  3. Configure the Web service policy following the steps described in "Configure a Web Service for Automatic Policy Configuration".

    Attach the policy created in step 2 followed by the oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy to the WebLogic Web service. For more information, see "Attaching a Policy to a Single Subject".

    Note:

    By default, the oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy policy is configured with token type of SAML 1.1. If you wish to configure the token type to be SAML 2.0, you will need to make a copy of the policy and edit it, as described in Creating a Web Service Policy from an Existing Policy. (This value should match the client policy.)
  4. Configure the Web service client policy following the steps described in "Configure a Web Service Client for Automatic Policy Configuration".

    Attach the oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy policy to the SOA composite client and override the client configuration properties described in Table 8-1, as required for your requestor token.

    The sts.auth.user.csf.key should be set to the user credentials available in the default OpenSSO STS configuration. Namely, username test, with password set to test. Though, it is not required to be set for the X509 requestor token.

    Note:

    For more information about overriding client configuration properties when attaching a policy, see "Attaching Policies to Web Service Clients".

    By default, the oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy policy is configured with token type of SAML 1.1. If you wish to configure the token type to be SAML 2.0, you will need to make a copy of the policy and edit it, as described in Creating a Web Service Policy from an Existing Policy. (This value should match the service policy.)

SAML Sender Vouches with Message Protection Scenario

Note:

Before proceeding, it is recommended that you review "Using SAML Sender Vouches with WS Trust".

The following procedure describes how to configure SAML sender vouches with message protection using WS-Trust with OpenSSO STS. This example uses a WebLogic Web service and SOA Composite client to demonstrate the scenario.

To configure SAML sender vouches with message protection using WS-Trust with OpenSSO STS:

  1. Configure OpenSSO STS, as described "Configuring OpenSSO STS".

  2. Configure the client-side STS policy following the steps described in "Manually Configuring the STS Config Policy From the Web Service Client: Main Steps".

    Note:

    Automatic Policy Configuration cannot be used for SAML sender vouches confirmation because the trust is between the Web service and the client. For more information, see "Using SAML Sender Vouches with WS Trust".

    Make a copy of oracle/sts_trust_config_client_policy and edit the policy configuration based on the requestor token type.

    To support WS-Security 1.0 username token with message protection requestor token:

    • orasp:policy-reference-uri="oracle/wss10_username_token_with_message_protection_client_policy"

    • orasp:port-endpoint="http://<host>:<port>/openfm/SecurityTokenService/#wsdl.endpoint(SecurityTokenService/ISecurityTokenService_Port_UN_WSS10_SOAP12):

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss10un"

    • orasp:sts-keystore-recipient-alias="test"

    To support WS-Security 1.0 username token over SSL with message protection requestor token:

    • orasp:policy-reference-uri="oracle/wss_username_token_over_ssl_client_policy"

    • orasp:port-endpoint="http://localhost:8080/openfm/SecurityTokenService/#wsdl.endpoint(SecurityTokenService/ISecurityTokenService_Port_TLS_UN_WSS10_SOAP12)"

    • orasp:port-uri="https://<host:ssl_port>/openssosts/sts/tlswss10un"

    • orasp:sts-keystore-recipient-alias="test"

    To support WS-Security 1.0 X509 token with message protection requestor token:

    • orasp:policy-reference-uri="oracle/wss10_x509_token_with_message_protection_client_policy"

    • orasp:port-endpoint="http://localhost:8080/openfm/SecurityTokenService/#wsdl.endpoint(SecurityTokenService/ISecurityTokenService_Port_X509_WSS10_SOAP12)"

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss10x509"

    • orasp:sts-keystore-recipient-alias="test"

    To support WS-Security 1.1 Kerberos token with message protection requestor token:

    • orasp:policy-reference-uri="wss11_kerberos_token_with_message_protection_basic128_client_policy" OR "wss11_kerberos_token_with_message_protection_client_policy"

    • orasp:port-endpoint="http://localhost:8080/openfm/SecurityTokenService/#wsdl.endpoint(SecurityTokenService/ISecurityTokenService_Port_KERBEROS_WSS11_SOAP12)"

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss11kerberos"

    • orasp:sts-keystore-recipient-alias="test"

  3. Attach the oracle/wss11_saml_token_with_message_protection_service_policy policy to the WebLogic Web service (there is no corresponding issued token policy for SAML sender vouches scenarios) and override the keystore.enc.csf.key to specify the service encryption key alias and password.

    Note:

    By default, the oracle/wss11_saml_hok_with_message_protection_service_policy policy is configured with token type of SAML 1.1. If you wish to configure the token type to be SAML 2.0, you will need to make a copy of the policy and edit it, as described in Creating a Web Service Policy from an Existing Policy.
  4. Attach the policy created in step 2 followed by the oracle/ws11_sts_issued_saml_hok_with_message_protection_client_policy policy to the SOA composite client and override the client configuration properties described in Table 8-1, as required for your requestor token.

    The "On Behalf Of" use case relies on the sts.auth.on.behalf.of.csf.key and on.behalf.of properties described in Table 8-1. For more information, see "On Behalf Of Use Cases".

    The on.behalf.of property should be set to true. The sts.auth.on.behalf.of.csf.key should be set to the user credentials available in the default Open SSO STS configuration that support the "on behalf of" use case. Namely, demo, with password set to changeit.

    Note:

    For more information about overriding client configuration properties when attaching a policy, see "Attaching Policies to Web Service Clients".
  5. To grant permission to the client application to request a token from OpenSSO STS "on behalf of" a user, edit the <MW_HOME>/user_projects/domains/base_domain/config/fmwconfig/system-jazn-data.xml file to include the following code:

    <grant>
       <grantee>
          <codesource>
             <url>
    file:${common.components.home}/modules/oracle.wsm.agent.common_11.1.1/wsm-agent-core.jar
             </url>
          </codesource>
       </grantee>
       <permissions>
          <permission>
                <class>oracle.wsm.security.WSIdentityPermission</class>
                <name>resource=<Client App. Name></name>
                <actions>assert</actions>
          </permission>
        </permissions>
    </grant>
    

SAML Bearer with Message Protection Scenario

The following procedure describes how to configure SAML bearer with message protection using WS-Trust with OpenSSO STS. This example uses a WebLogic Web service and SOA Composite client to demonstrate the scenario.

To configure SAML bearer with message protection using WS-Trust with OpenSSO STS:

  1. Configure OpenSSO STS. as described "Configuring OpenSSO STS".

  2. Configure the STS policy following the steps described in "Configure a Policy for Automatic Policy Configuration".

    Make a copy of oracle/sts_trust_config_service_policy and edit the policy configuration, as described below, based on the requestor token type.

    To support WS-Security 1.0 username token with message protection requestor token:

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss10un"

    • orasp:wsdl-uri="http://<host>:<port>/openssosts/sts/wss10un?wsdl" (Optional)

    To support WS-Security 1.0 username token over SSL with message protection requestor token:

    • orasp:port-uri="https://<host:ssl_port>/openssosts/sts/tlswss10un"

    • orasp:wsdl-uri="https://<host:ssl_port>/openssosts/sts/tlswss10un?wsdl" (Optional)

    To support WS-Security 1.0 X509 token with message protection requestor token:

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss10x509"

    • orasp:wsdl-uri="http://<host>:<port>/openssosts/sts/wss10x509?wsdl" (Optional)

    To support WS-Security 1.1 Kerberos token with message protection requestor token:

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss11kerberos"

    • orasp:wsdl-uri="http://<host>:<port>/openssosts/sts/wss11kerberos?wsdl" (Optional)

  3. Configure the Web service policy following the steps described in "Configure a Web Service for Automatic Policy Configuration".

    Attach the policy created in step 2 followed by the oracle/wss11_sts_issued_saml_bearer_token_over_ssl_service_policy. For more information, see "Attaching a Policy to a Single Subject".

  4. Configure the Web service client policy following the steps described in "Configure a Web Service Client for Automatic Policy Configuration".

    Attach the oracle/ws11_sts_issued_saml_bearer_token_over_ssl_client_policy policy to the SOA composite client and override the client configuration properties described in Table 8-1, as required for your requestor token.

    The sts.auth.user.csf.key should be set to the user credentials available in the default OpenSSO STS configuration. Namely, username test, with password set to test. Though, it is not required to be set for the X509 requestor token.

    Note:

    For more information about overriding client configuration properties when attaching a policy, see "Attaching Policies to Web Service Clients".