9 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.

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

  • Configure the WebLogic Server keystore and SSL settings.

  • Configure the Web service client keystore and SSL settings.

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_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_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://java.sun.com/j2se/1.5.0/docs/tooldocs/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 in order 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 in order 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

In order 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 runtime 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 9-1.

    Figure 9-1 Web Services Manager Keystore Configuration

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

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

  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. However, you cannot change the keystore type; it must be JKS.

  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://java.sun.com/j2se/1.4.2/docs/tooldocs/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

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 in order 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. If there is no need to publish the X509 certificate (for e.g., with SSL), you can override the default setting to avoid publishing the certificate. In addition, if the X509 is published, you can also specify whether to ignore 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 runtime 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 JEE 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 JEE 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. This credential is stored in the credential store provider.

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 9-2. (In this figure, the Credential Store Provider control has already been expanded.)

    Figure 9-2 Credential Store Provider Configuration Page

    Description of Figure 9-2 follows
    Description of "Figure 9-2 Credential Store Provider Configuration Page"

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

    Figure 9-3 Set Security Provider Screen

    Description of Figure 9-3 follows
    Description of "Figure 9-3 Set Security Provider Screen"

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

    Figure 9-4 Create Key Dialog Box

    Description of Figure 9-4 follows
    Description of "Figure 9-4 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:

  • Policies that use the username token require an authentication provider that can handle the NameCallback and PasswordCallback. The WebLogic Default Authentication provider is one such provider.

    The following policies fall into this category:

    • oracle/wss_http_token_service_policy

    • oracle/wss_username_token_service_policy

    • oracle/wss_username_token_over_ssl_service_policy

    • oracle/wss11_username_token_with_message_protection_service_policy

    • oracle/wss10_username_token_with_message_protection_service_policy

    • oracle/wss10_username_token_with_message_protection_ski_basic256_service_policy

  • Policies that use the X.509 and SAML tokens require an authentication provider (or Identity Assertion provider) that can handle perimeter authentication via the NameCallback. The Web service runtime process the tokens on your behalf to determine the username, and then invokes the Oracle Platform Security Service (OPSS) layer to complete the authentication. In this way, the security providers do not handle the X.509 or SAML tokens directly, and the WebLogic providers do not have to support these token types.

    The following policies fall into this category:

    • oracle/wss10_x509_token_with_message_protection_service_policy

    • oracle/wss10_saml_token_service_policy

    • oracle/wss10_saml_token_with_message_protection_service_policy

    • oracle/wss_saml_token_over_ssl

    • oracle/wss_saml_token_bearer_over_ssl_service_policy

    • oracle/wss10_saml_hok_token_with_message_protection_service_policy

    • oracle/wss11_saml_token_with_message_protection_service_policy

    • oracle/wss10_saml_token_with_message_protection_ski_basic256_service_policy

    • oracle/wss11_x509_token_with_message_protection_service_policy

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 datastore 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 must edit the login policy and make any needed changes. The Kerberos login module has settings that you can optionally configure.

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

Table 9-1 lists the available login modules and which policies use them.

Table 9-1 SAML and Kerberos Login Modules and Related Policies

Login Module Service Name Description Settable Attributes and Values

saml.loginmodule

The SAML login module is a Java Authentication and Authorization Service (JAAS) login module that accepts SAML assertions to do a login. The SAML login module enables the Web services to be run using the login context of the principal created from the SAML assertion.

Issuers. Name of the issuer of the SAML token. www.oracle.com is the default.

krb5.loginmodule

Kerberos login module

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


Do the following to configure a login module:

  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. From the list of login modules, select a login module and click Edit.

  4. Configure any specific attributes or custom properties for the login module.

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:

  • 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/wss10_saml_token_service_policy

  • oracle/wss10_saml_token_client_policy

  • oracle/wss10_saml_token_with_message_protection_client_policy

  • oracle/wss10_saml_token_with_message_protection_service_policy

  • oracle/wss10_saml_token_with_message_protection_ski_basic256_client_policy

  • oracle/wss10_saml_token_with_message_protection_ski_basic256_service_policy

  • oracle/wss10_saml_hok_token_with_message_protection_service_policy

  • oracle/wss10_saml_hok_token_with_message_protection_client_policy

  • oracle/wss10_saml_token_with_message_integrity_service_policy

  • oracle/wss10_saml_token_with_message_integrity_client_policy

  • oracle/wss11_saml_token_with_message_protection_service_policy

  • oracle/wss11_saml_token_with_message_protection_client_policy

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) via the NameCallback to complete the perimeter authentication.

Which Authentication Provider is Used?

Any configured authentication provider (identity asserter) that handles the NameCallback can then be invoked.

The 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.

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 JEE 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 JEE application and you are making a Web service call from that JEE 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 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 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.

    To use a different issuer name, click Add to add an additional issuer name, as shown in Figure 9-5.

    Figure 9-5 Adding a SAML Issuer to the Login Module

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

  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 property 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.If a different client, for instance .NET/WLS, is talking to a Web service protected by a predefined SAML policy, or you otherwise need to use a different SAML issuer, then you need to add an additional issuer name.

To add an additional SAML assertion issuer name:

  1. Configure the SAML login module, as described in "Configuring the SAML and Kerberos Login Modules". Click Add to add an additional issuer name, as shown in Figure 9-5.

  2. 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, in order 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.

Use Fusion Middleware Control to add the oracle.wsm.security.WSIdentityPermission permission to the SOA reference binding component as a System Grant, as follows:

  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 Security 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 9-6.

    Figure 9-6 Adding the WSIdentityPermission

    Description of Figure 9-6 follows
    Description of "Figure 9-6 Adding the WSIdentityPermission"

Using Kerberos Tokens

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

  • oracle/wss11_kerberos_token_client_policy

  • oracle/wss11_kerberos_token_service_policy

  • oracle/wss11_kerberos_token_with_message_protection_client_policy

  • oracle/wss11_kerberos_token_with_message_protection_service_policy

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

  • oracle/wss11_kerberos_token_client_template

  • oracle/wss11_kerberos_token_service_template

  • oracle/wss11_kerberos_token_with_message_protection_client_template

  • oracle/wss11_kerberos_token_with_message_protection_service_template

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 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/kdb5_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 9-1. Note the following:

  • The file tells the kerberos runtime 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 9-1 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 9-1. 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 runtime 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.

    In order 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 9-2.

Table 9-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 runtime

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 runtime 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://java.sun.com/j2se/1.4.2/docs/tooldocs/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 "RSAwithSHA1" -file certreq_file -storetype jks -keystore client-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 9-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.