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:

• Understanding Keys and Certificates

• Configuring Keystores for Message Protection

• Configuring the Credential Store

• Creating an Application-level Credential Map

• Configuring the OPSS Keystore Service for Message Protection

• Configuring Keystores for SSL

• Configuring SSL on Oracle HTTP Server

• Hardware Integration

• Using Service Identity Certification Extension

• Configuring an Authentication Provider in WebLogic Server

• Configuring the SAML and Kerberos Login Modules

• Configuring SAML

• Using JSON Web Token (JWT) with Oracle WSM

• Using OAuth2 with Oracle WSM

• Configuring Web Service Clients for Identity Switching

• Propagating Identity Context with Oracle WSM

• Using Kerberos Tokens

• Using Active Directory with Kerberos and Message Protection

• SAML Message Protection Use Case

• WS-Trust Policies and Configuration Steps

• Examples Using WS-Trust with OpenSSO STS

• Understanding Fine-Grained Authorization Using Oracle Entitlements Server

Understanding Keys and Certificates

Before you can use any message protection security policies or message protection and authentication with SSL security policies, you need to set up your keystores and truststores. (Authentication-only security policies do not require keys.)

The keystore contains the entities private keys and certificates associated with those private keys. A truststore contains certificates from a Certificate Authority (CA), or other entities that this entity trusts. The keystore and the truststore can be maintained together in a common store, such as with Oracle Web Services Manager (WSM).

Before configuring your Web services, you need to determine the type of private keys and certificates required, the names for the keys and keystores, and then set up your environment accordingly.

Overview of Private Keys and Certificates

Private keys, digital certificates, and trusted certificate authorities establish and verify server identity and trust.

SSL uses public key encryption technology for authentication. With public key encryption, a public key and a private key are generated for a server. Data encrypted with the public key can only be decrypted using the corresponding private key and data verified with a public key can only have been signed with the corresponding private key. The private key is carefully protected so that only the owner can decrypt messages that were encrypted using the public key.

The public key is embedded in a digital certificate with additional information describing the owner of the public key, such as name, street address, and e-mail address. A private key and digital certificate provide identity for the server.

The data embedded in a digital certificate is verified by a certificate authority and digitally signed with the certificate authority's digital certificate. Well-known certificate authorities include Verisign and Entrust.net. The trusted certificate authority (CA) certificate establishes trust for a certificate.

An application participating in an SSL connection is authenticated when the other party evaluates and accepts the application's digital certificate. Web browsers, servers, and other SSL-enabled applications generally accept as genuine any digital certificate that is signed by a trusted certificate authority and is otherwise valid. For example, a digital certificate can be invalidated because it has expired or the digital certificate of the certificate authority used to sign it expired. A server certificate can be invalidated if the host name in the digital certificate of the server does not match the URL specified by the client.

The different types of trusted certificates, along with the benefits and disadvantages of each, that you can use in your environment are as follows:

• Self-signed certificates — A self-signed certificate is a certificate that is signed by the entity creating it.

  Benefits:

  • Easy to generate because you can do it yourself, for example using the keytool command as described in "Generating Private Keys and Creating the Java Keystore".

  • Can be used in production as long as you use only a new certificate that you have generated.

  Disadvantages:

  • Self-signed certificates can quickly become unmanageable if you have many clients and services that need to communicate with each other. For example, if you have three clients communicating with two services, you need to generate a private key and self-signed certificate for both services, and then import the two certificates into the truststore of all three clients.

• Demonstration Certificate Authority (CA) signed certificates— WebLogic Server includes a set of demonstration private keys, digital certificates, and trusted certificate authorities that are for development only.

  Benefits:

  • Easy to use because they are available and configured for use in the default WebLogic Server installation in a development environment.

  Disadvantages:

  • Should never be used in a production environment. The private key of the demo certificate CA is available to all installations of WebLogic Server, therefore each installation can generate a demo CA signed certificate using the same key. As a result, you cannot trust these certificates.

• Internal CA signed certificates — An internal CA signed certificate is a certificate that you issue yourself using an internal CA that you can setup for your intranet. This type of certificate can be used if your services are mostly internal only.

  Benefits:

  • You have complete control over the certificate issuance process because you create the certificates yourself.You can control to whom the certificates are issued, how long the certificates remain valid, and so on. For example, if you are issuing certificates to your partners, you can issue them only to partners in good standing.

  Disadvantages:

  • You need to ensure that all clients have the internal CA root certificate imported into their truststore.

• External CA signed certificates — An external CA signed certificate is a certificate that has been issued by a reputable CA such as Verisign and Entrust.net. This type of certificate should be used if your services are external facing.

  Benefits:

  • In most cases, clients are already set up to trust these external CAs. Therefore, those clients do not have to modify their truststore.

  Disadvantages:

  • You do not have any control over the certificate issuance process.

How Different Security Policies Use Private Keys and Certificates

Oracle WSM security policies that require the use of private keys address two aspects: message protection and authentication:

• Message protection encompasses two concepts, message confidentiality and message integrity. Message confidentiality involves keeping the data secret and is achieved by encrypting the content of messages. Message integrity ensures that a message remains unaltered during transit by having the sender digitally sign the message.

• Authentication involves verifying that the user is who they claim to be. A user's identity is verified based on the credentials presented by that user.

The predefined Oracle WSM policies that are included with your installation support various options for message protection and authentication. These options are described in the following sections.

Note:

The naming convention used for Oracle WSM policies identifies the type of options being used. For example, the policy oracle/wss10_username_token_with_message_protection_service_policy is a message protection service policy that uses the wss10 Web services standard and requires a username_token for authentication. For more information about policy naming conventions, see "Recommended Naming Conventions for Policies".

Message Protection Policy Types

The types of message protection policies and how they work are described in the following sections.

SSL

Policies that include the SSL option, such as oracle/wss_saml_or_username_token_over_ssl_service_policy, use one-way SSL for message protection. When using policies of this type, you need to do the following:

• On the service side, set up private keys at the SSL termination point as described in "Setting Up Private Keys and Certificates for SSL Policies".

• On the client side, set up the truststore to trust the service keys.

The private key is used to protect the messages for the SSL handshake, at which time the client and service agree on a shared session key. After the SSL handshake, the private key is not used, and all traffic between the client and the service are signed and encrypted using the shared session key.

wss11

Policies of this type use WS-Security 1.1 for message protection. When using wss11 policies, you need to do the following:

• On the service side, set up private keys and define as the Encryption Key Alias in the Oracle WSM Keystore Configuration screen. For details see "Configuring the Oracle WSM Keystore".

• On the client side, you need to configure the client-side trust by obtaining the server's certificate in one of the following ways:

  • Use the service's public certificate published in the WSDL using the Service Identity Certificate extension as described in "Using Service Identity Certification Extension". You also need to import either the server certificate itself, or the root certificate from the CA that issued the server certificate, into the client truststore. You can choose any alias name for the server certificate.

  • Import the server certificate into the client keystore using any alias you choose, and specify that alias using the keystore.recipient.alias property using a configuration override when you attach the policy. For this method you need to import the actual server certificate, you cannot import the CA root certificate.

For each request, the following occurs:

1. The client creates a symmetric key, encrypts this symmetric key with the service's public key as configured with Encryption Key Alias, and then encrypts and signs the whole message with the symmetric key.

2. When the service receives the message, it decrypts the encrypted key first, and then decrypts and verifies the whole message.

3. The Web service then uses the same symmetric key to encrypt and sign the response that it sends back to the client.

wss10

Policies of this type use WS-Security 1.0 for message protection. When using wss10 policies, you need to do the following:

• Set up private keys on both the client and service side. On the client side, you need to set a signature key alias, and on the service side you need both an encryption key alias and signature key alias. Note that you can normally use the same key for both.

• On the client side, you need to configure the client-side trust by obtaining the server's certificate in one of the following ways:

  • Use the service's public certificate published in the WSDL using the Service Identity Certificate extension as described in "Using Service Identity Certification Extension". You also need to import either the server certificate itself, or the root certificate from the CA that issued the server certificate, into the client truststore. You can choose any alias name for the server certificate.

  • Import the server certificate into the client keystore using any alias you choose, and specify that alias using the keystore.recipient.alias property using a configuration override when you attach the policy. For this method you need to import the actual server certificate, you cannot import the CA root certificate.

• On the service side, you need to configure the service to trust the client, either by importing these certificates directly, or importing the CA that issued these certificates.

Similar to the wss11 option, the client creates a symmetric key, and then encrypts the symmetric key with the service's public key. The difference, however, is that it only uses this symmetric key for encrypting the message; it doesn't use it for signing the message. Instead, the client signs the request message with its own private signature key as defined by the Signature Key alias, and the service signs the response with its private signature key.

Authentication Token Policy Types

The tokens that are supported for authentication, and the private keys and certificates that are used with these policy types are described in the following sections.

Note that in the following sections, "signature key alias" is used to mean different things in different contexts.

• In SAML sender vouches policies, it is the key used to sign the SAML assertion. This proves the authenticity of the SAML assertion, and SAML Login module will then assert the user specified in the SAML assertion.

• In wss10 policies, it is used to sign the request and response message to prevent them from being tampered over the wire.

• In X.509 authentication policies, it is used to authenticate a particular end user.

JWT Token

JSON Web Token (JWT) is a compact URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is digitally signed using a JSON Web Signature (JWS) and optionally encrypted using JSON Web Encryption (JWE). The token is generated and signed by the client using its private signature key.

Kerberos Token

A Kerberos token is comprised of a binary authentication and session token. When a Kerberos token is used with an authentication-only policy, no private keys are used. When used in a policy that includes authentication and message protection, the keys required for message protection are required.

SAML Bearer and SAML HOK Tokens from an STS

For these options, the client does not construct the SAML token. Instead it is STS that constructs and signs the SAML token.

When using tokens from an STS, you must add the STS's certificate or its issuer to the service's truststore. Optionally, you can configure the STS in the Trusted DN list.

SAML Sender Vouches Token

In sender vouches, the client signs the SAML token with its own private signature key.

Use the SAML sender vouches token with each of the message protection options as follows:

• With SSL: SAML sender vouches requires two-way SSL. Therefore, you need to set up an SSL client-side private key, and corresponding trust certificate on the service side. If your SSL terminates before WebLogic Server, such as in the Oracle HTTP Server or in the Load balancer, you must configure these layers to propagate the client certificate all the way to WebLogic Server.

• With wss11: Normally wss11 does not need a client-side signature key. However, when you use wss11 with SAML, you need to set up a signature key on the client side, and configure it using the signature key alias. You also need to add this client certificate or its issuer to the service's truststore.

• With wss10: There is no additional setup to use SAML. The regular client signature key that is used for signing the request is also used for signing the SAML token.

  Note:

  Be very cautious when using the SAML signature key. It is a very powerful key as it enables the client side to impersonate any user. Consider configuring the server side to limit the number of SAML signers that is accepts, by setting up a Trusted DN list. For information about setting up a trusted DN, see "Defining Trusted Issuers and a Trusted DN List for Signing Certificates".

Username Token

A username token carries basic authentication information such as a username and password. When a username token is used with an authentication-only policy, no private keys are used. When used in a policy that includes authentication and message protection, the keys required for message protection are required.

X.509 Certificate Token

Request messages are signed with the end user's signature key. On the client side you need to configure a signature key alias with the end user's signature key.

Setting Up Private Keys and Certificates for SSL Policies

The following list summarizes the keys and trust you need to configure on the client and service side to use SSL policies:

• Service-side configuration: For SSL security policies, you need to setup the private keys at the SSL termination point. These termination points typically consist of one of the following:

  • Java EE container, such as WebLogic Server. For configuration details, see "Configuring Keystores for SSL".

  • Oracle HTTP Server, if you have configured it as a Web proxy between the client and WebLogic Server. For configuration details, see "Configuring SSL on Oracle HTTP Server".

  • Load balancer, if you have a load balancer in front of WebLogic Server or Oracle HTTP Server.

  Note:

  With SSL you can only have one private key per server, so if there are multiple Web services running on the same server, they all use the same private key. This SSL private key needs to be generated with the same DN as the host name, although for testing purposes, you can turn off the host name verifier on the client side.

  Sample basic configuration: Use the demonstration digital certificates, private keys, and trusted CA certificates that are included with WebLogic Server. These keys and certificates are provided for development use only and should not be used in a production environment.

  Advanced configuration: In a production environment, use an internal or external CA.

• Client-side configuration: On the client side, you need to import the server certificates into the client truststore. If the server side is using self-signed certificates, you need to include them directly. If the server side is using certificates that are signed using a CA, import the CA root certificate into the client truststore. Note that each type of Web service client has a different client truststore:

  • For WebLogic Server Web services, you need to import the keys into the WebLogic Server trust store. The demonstration CA certificate is already present in the WebLogic Server truststore.

  • For Oracle Infrastructure Web services you need to specify the truststore using javax.net.ssl* system properties, or specify it in the connection. For details, see "Configuring SSL for a Web Service Client".

  • For SOA composite applications, you need to specify the truststore using the javax.net.ssl* property as described in "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 asynchronous Web services, you need to configure the truststore as described in "Configuring SSL for Asynchronous Web Services" in Developer's Guide for Oracle Infrastructure Web Services.

Setting up Private Keys and Certificates for Message Protection Policies

For Oracle WSM message protection security policies, you need to setup your private keys in the Oracle WSM keystore.

There is a single Oracle WSM keystore per domain, and it is shared by all Web services and clients running in the domain. This keystore contains both private keys and trust certificates. The JDK cacerts file is not used by Oracle WSM.

Sample Basic Configuration

The easiest way to set up the Oracle WSM keystore is to create a single self-signed private key and use it for the entire domain. When you create the private key and keystore, you specify a name and a password for the keystore, for example default-keystore.jks as the keystore name and password as the password for the keystore. You also specify an alias name and password to use when referring to the private key, for example orakey as the alias name and password as the key password. You can use the same key and alias for both the signature key alias and the encryption key alias, and the same password for both the keystore and the alias. You do not need to add any trusted certificates, as certificates associated with private keys are automatically considered as trusted.

Once you have created the keys and keystore, you need to provide the keystore password, and alias names and passwords to Oracle Web Services Manager.You can do so using either Fusion Middleware Control or WLST.

The procedures in "Generating Private Keys and Creating the Java Keystore" and "Configuring the Oracle WSM Keystore" describe how to setup this basic configuration using the names and passwords specified in this example. In your own environment, you should use names and passwords that are appropriate for your configuration.

As long as your client and server are on the same domain, this set up is sufficient to work with most of the policies. That is, you can use any wss10 or wss11 policies with or without SAML.

If you have multiple related domains that share a common JPS root, you can copy this keystore file to all the domains. By doing so, all the related domains will share this single key for all encryption and signing.

Advanced Setup Considerations

As described in "Sample Basic Configuration", the simplest way to set up message protection security is to have a single private key for all Web services in the domain.

For more sensitive Web services, you need to configure each Web service to use its own distinct private encryption key. These private keys need to exist in the Oracle WSM keystore. Ensure that each one uses a different alias name, for example ServiceA, and ServiceB, and that you add the aliases to the credential store. When you attach a policy to the service, you need to use a configuration override to indicate the specific alias name that the Web service requires, otherwise it will use the default alias that you configured for the domain, for example orakey.

The procedure in "Adding Keys and User Credentials to the Credential Store" describes how to add these sample aliases to the credential store.

You should also use trusted certificates issued by an internal or external CA, instead of self-signed certificates, because it is much easier to manage the trusted CA certificates. Be sure, however, to set up the SAML signers Trusted DN list, as described in "Defining Trusted Issuers and a Trusted DN List for Signing Certificates". This is especially important if you import external CA certificates into the Oracle WSM Keystore, otherwise any user with a certificate will be able to sign a SAML token and impersonate any user.

Configuring Keystores for Message Protection

Note:

To configure keystores for message protection using the REST API, see "JKS Keystore Management" in REST API for Managing Credentials and Keystores with Oracle Web Services Manager.

Message protection involves encrypting the message for message confidentiality and signing the message for message integrity. To sign and encrypt SOAP messages, you use public and private signature and encryption keys that you store in the Oracle Web Services Manager (WSM) keystore for the WebLogic domain. The keystore configuration is domain wide: all Web services and Web service clients in the domain use this keystore.

Note:

The Oracle WSM run time does not use the WebLogic Server keystore that is configured using the WebLogic Server Administration Console and used for SSL as documented in "Configuring Keystores for SSL".

To create and configure the Java Keystore for message protection, use the procedures in the following sections:

• Generating Private Keys and Creating the Java Keystore

• Configuring the Oracle WSM Keystore

Note:

These procedures describe how to setup the basic configuration, using the names and passwords specified in the example, as described in "Sample Basic Configuration", and illustrated in Figure 10-8. In your own environment, you should use names and passwords that are appropriate for your configuration.

Generating Private Keys and Creating the Java Keystore

The following section provides an outline of how to create a private key pair and the Java keystore (JKS) using the keytool utility. 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. Go to the domain_home/config/fmwconfig directory, where domain_home is the name and location of the domain for which the keystore is to be used.

2. Enter a keytool command such as the following to generate the key pair, and to create the keystore if it does not already exist:

   keytool -genkeypair -keyalg RSA -alias orakey -keypass password -keystore default-keystore.jks -storepass password -validity 3600

   Note:

   You may need to add the jdk/bin directory to your PATH variable definition to invoke the keytool command.

   In this command:

   • genkeypair creates a new public/private key pair that is stored in an entry specified by the alias parameter

   • keyalg specifies the algorithm to be used to generate the key pair, in this example RSA

     Note:

     The default key pair generation algorithm is Digital Signature Algorithm (DSA). DSA keys can only be used for signing, whereas RSA keys can be used for both signing and encryption. Therefore, if you are using the same key for encryption and signing (which is a typical scenario), make sure you explicitly specify -keyalg RSA, otherwise keytool will default to DSA.

   • alias specifies the alias name orakey to use when referring to the keypair

   • keypass specifies that the password be used to protect the private key of the generated key pair

   • keystore creates a keystore named default-keystore.jks. If the keystore already exists, the key pair will be added to the keystore.

   • storepass specifies password as the password used to protect the integrity of the keystore.

   • validity indicates that the keypair is valid for 3600 days.

   The keytool utility prompts for the name, organizational unit and organization, locality (city, state, country) to be used to create the key:

   What is your first and last name?
     [Unknown]:  orcladmin
   What is the name of your organizational unit?
     [Unknown]:  Doc
   What is the name of your organization?
     [Unknown]:  Oracle
   What is the name of your City or Locality?
     [Unknown]:  US
   What is the name of your State or Province?
     [Unknown]:  US
   What is the two-letter country code for this unit?
     [Unknown]:  US
   Is CN=orcladmin, OU=Doc, O=Oracle, L=US, ST=US, C=US correct?
     [no]:  y
   

3. Optionally, import trusted certificates into the keystore as described in "Obtaining a Trusted Certificate and Importing it into the Keystore"

4. Optionally, use the keytool -list command to view the contents of the keystore:

   keytool -list -keystore default-keystore.jks

   When prompted, provide the password for the keystore that you specified when you created the keystore.

   Enter keystore password:
    
   Keystore type: JKS
   Keystore provider: SUN
    
   Your keystore contains 1 entry
    
   Alias name: orakey
   Creation date: Mar 9, 2011
   Entry type: PrivateKeyEntry
   Certificate chain length: 1
   Certificate[1]:
   Owner: CN=orcladmin, OU=Doc, O=Oracle, L=US, ST=US, C=US
   Issuer: CN=orcladmin, OU=Doc, O=Oracle, L=US, ST=US, C=US
   Serial number: 4d77aff6
   Valid from: Wed Mar 09 11:51:02 EST 2011 until: Fri Jan 15 11:51:02 EST 2021
   Certificate fingerprints:
            MD5:  DF:EC:3C:60:CF:8B:10:A7:73:3A:51:99:4C:A3:D0:2E
            SHA1: E0:52:58:EB:34:51:E4:9B:D4:13:C2:CB:F3:CC:08:89:EF:4E:4E:05
            Signature algorithm name: SHA1withRSA
            Version: 3
    
    
   *******************************************
   *******************************************
   

Configuring the Oracle WSM Keystore

The following section describes how to use Oracle Enterprise Manager Fusion Middleware Control to configure the Oracle WSM keystore. This is the recommended method for configuring the keystore. If your environment does not include Fusion Middleware Control, you can also use WebLogic Scripting Tool (WLST) commands, as described in "Using WLST".

Using Fusion Middleware Control

When you use Fusion Middleware Control to configure the Oracle WSM keystore, entries are created in the credential store for the credential map oracle.wsm.security, and any keys that you define. Use the following procedure to configure the 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. From the WebLogic Domain menu, select Security then Security Provider Configuration, as shown in Figure 10-1.

   Figure 10-1 Security Provider Configuration Menu

   
   Description of ''Figure 10-1 Security Provider Configuration Menu''
   
   

   The Security Provider Configuration page is displayed, as shown in Figure 10-2.

   Figure 10-2 Security Provider Configuration Page

   
   Description of ''Figure 10-2 Security Provider Configuration Page''
   
   

3. Click Configure in the Keystore section of the page.

   The Keystore Configuration page is displayed, as shown in Figure 10-3.

   Figure 10-3 Keystore Configuration

   
   Description of ''Figure 10-3 Keystore Configuration''
   
   

4. In the Keystore Type drop-down, select Java Key Store (JKS), if it is not already selected.

   Notes:

   Hardware security modules (HSM) are also certified to operate with Oracle Advanced Security. For more information, see "Using Hardware Security Modules With Oracle WSM"

   You can also select Public Key Cryptographic Standards (PKCS-11) when using cryptographic acceleration, as described in Step 6 of "Configuring Message-level Security for Cryptographic Acceleration". You use the PKCS-11 keystore type when hardware token support is required.

5. In the Access Attributes section of the page, provide the name and path of the keystore, and the passwords as follows:

   • In the Keystore Path field, enter the path and name for the keystore that you created as described in "Generating Private Keys and Creating the Java Keystore". This field defaults to ./default-keystore.jks, which represents the default Java keystore name, default-keystore.jks, located in the domain_name/config/fmwconfig directory. If you used a different name or location for the keystore, enter that value instead.

   • In the Password and Confirm Password fields, enter the password for the keystore. This password must match the password you used when you created the keystore using the keytool utility, as described in "Generating Private Keys and Creating the Java Keystore", for example password.

6. In the Identity Certificates section of the page, enter the alias and passwords for the signature and encryption keys as follows:

   • For the Signature Key, enter the alias name in the Key Alias field, and the password for the alias in the Signature Password and Confirm Password fields. The values you specify here must match the values in the keystore. For example, orakey and password.

   • For the Encryption Key, enter the alias name in the Crypt Alias field, and the password for the alias in the Crypt Password and Confirm Password fields. The values you specify here must match the values in the keystore. For example, orakey and password.

   The alias and password for the signature and encryption keys define the string alias and password used to store and retrieve the keys. These values are created in the credential store as sign-csf-key and enc-csf-key.

7. Click OK to submit the changes.

   If you used a file-based keystore provider, the changes require a server restart to take effect. A restart is not required for database or LDAP-based keystore service providers.

Using WLST

Follow these steps to configure the credential store to access the Oracle WSM keystore using WLST commands.

1. Go to the Oracle Common home directory for your installation, for example /home/Oracle/Middleware/oracle_common.

   For information about the Oracle Common home directory and installing Oracle Fusion Middleware, see the Oracle Fusion Middleware Installation Planning Guide.

2. Start WLST using the WLST.sh/cmd command located in the oracle_common/common/bin directory. For example:

   • /home/Oracle/Middleware/oracle_common/common/bin/wlst.sh (UNIX)

   • C:\Oracle\Middleware\oracle_common\common\bin\wlst.cmd (Windows)

   When executed, these commands start WLST in offline mode. To use the credential store WLST commands, you must use WLST in online mode.

3. Start Oracle WebLogic Server.

   For more information, see "Start and stop servers" in the Oracle WebLogic Server Administration Console Help.

4. Connect to the running WebLogic Server instance using the connect() command. For example, the following command connects WLST to the Administration Server at the URL myAdminServer.example.com:7001 using the username/password credentials weblogic/password:

   connect("weblogic","password","t3://myAdminServer.example.com:7001")
   

5. Enter the createCred command to create an entry in the credential store for the keystore name and password as follows:

   createCred(map="oracle.wsm.security", key="keystore-csf-key", user="Oracle WSM", password="password", desc="Keystore key")
   

   Note that you can enter any value for user. This field is ignored for the keystore-csf-key entry. The value of password must match the password that you specified when you created the keystore as described in "Generating Private Keys and Creating the Java Keystore" (in this example password).

6. Enter the createCred command to create an entry in the credential store for the signature key alias and password as follows:

   createCred(map="oracle.wsm.security", key="sign-csf-key", user="orakey", password="password", desc="Signing key")
   

   The values of user and password must match the alias name and password for the signature key in the keystore that you specified when you created the keystore as described in "Generating Private Keys and Creating the Java Keystore". In this example, the values are orakey and password.).

7. Enter the createCred command to create an entry in the credential store for the encryption key alias and password as follows:

   createCred(map="oracle.wsm.security", key="enc-csf-key", user="orakey", password="password", desc="Encryption key")
   

   The values of user and password must match the alias name and password for the encryption key in the keystore that you specified when you created the keystore as described in "Generating Private Keys and Creating the Java Keystore". In this example, the values are orakey and password.).

Obtaining a Trusted Certificate and Importing it into the Keystore

You can obtain a certificate from a Certificate Authority (CA), such as Verisign or Entrust.net, and include it 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.

To obtain a trusted certificate and import the certificate into the keystore:

1. Generate the private key and self-signed certificate. The self-signed certificate will be replaced by the trusted certificate.

   Note:

   If your keystore already contains a self-signed certificate that you created previously, as described in "Generating Private Keys and Creating the Java Keystore", you can ignore this step and proceed to step 2.

   Use the keytool -genkeypair command to generate the key pair for a specified alias, in this example orakey. It will create the keystore if it did not exist.

   keytool -genkeypair -keyalg RSA -alias orakey -keypass password -keystore default-keystore.jks -storepass password -validity 3600

2. Generate the certificate request.

   Use the keytool -certreq command to generate the request. The following command generates a certificate request for the orakey alias and a Certificate Signing Request (CSR) named certreq_file.

   keytool -certreq -alias orakey -sigalg "SHA1withRSA" -file certreq_file -storetype jks -keystore default-keystore.jks

3. Submit the CSR file to a CA such as VeriSign, for example. The CA will authenticate the request and return a certificate or a certificate chain.

4. Import the CA root certificate which authenticates the CA's public key.

   Use the keytool -importcert command to import the trusted CA root certificate (named VerisignCAcert.cer in this example), using the alias verisignca into the default-keystore.jks keystore. The keytool utility prompts for the needed password.

   keytool -importcert -alias verisignca -trustcacerts -file VerisignCAcert.cer -keystore default-keystore.jks

5. Replace the self-signed certificate with the trusted CA certificate issued by the CA in response to the certificate request.

   Use the keytool -importcert command. The following command replaces the self-signed certificate for the alias orakey with the trusted CA certificate named, in this example, MyCertIssuedByVerisign.cer. The keytool utility prompts for the needed password.

   keytool -importcert -trustcacerts -alias orakey -file MyCertIssuedByVerisign.cer -keystore default-keystore.jks

Setting Up the Web Service Client Keystore

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 the requirements for the different types of message protection policies, how to create and use these keystores, and how to obtain trusted certificates.

• "How Different Security Policies Use Private Keys and Certificates"

• "Generating Private Keys and Creating the Java Keystore"

• "Obtaining a Trusted Certificate and Importing it into the Keystore"

Managing Java Keystore Certificates

You can use WebLogic Scripting Tool (WLST) commands to manage Java keystore (JKS) certificates.

• Listing all aliases within a keystore

• Displaying a certificate within a keystore

• Exporting and importing trusted certificates or a certificate chain associated with a private key:

  • Certificates - Base64 encoded X.509 (.cer)

  • Certificate Chain - PKCS7 (.p7b) or as an array of certificates

• Deleting certificates from the keystore

Using WLST

Follow these steps to manage JKS certificates using WLST commands.

1. Go to the Oracle Common home directory for your installation, for example /home/Oracle/Middleware/oracle_common.

   For information about the Oracle Common home directory and installing Oracle Fusion Middleware, see the Oracle Fusion Middleware Installation Planning Guide.

2. Start WLST using the WLST.sh/cmd command located in the oracle_common/common/bin directory. For example:

   • /home/Oracle/Middleware/oracle_common/common/bin/wlst.sh (UNIX)

   • C:\Oracle\Middleware\oracle_common\common\bin\wlst.cmd (Windows)

   When executed, these commands start WLST in offline mode. To use the credential store WLST commands, you must use WLST in online mode.

3. Start Oracle WebLogic Server.

   For more information, see "Start and stop servers" in the Oracle WebLogic Server Administration Console Help.

4. Connect to the running WebLogic Server instance using the connect() command. For example, the following command connects WLST to the Administration Server at the URL myAdminServer.example.com:7001 using the username/password credentials weblogic/password:

   connect("weblogic","password","t3://myAdminServer.example.com:7001")
   

5. Use these commands to manage your keystore:

   • displayWSMCertificate – displays the string representing the contents of a user's certificate if the alias specifies a KeyStore.TrustedCertificateEntry. Displays the certificates in the chain if the alias points to a certificate chain specified by the KeyStore.PrivateKeyEntry. For example:

     wls:/DefaultDomain/serverConfig> displayWSMCertificate('testalias')
     

   • listWSMKeystoreAliases – Lists all the aliases in the keystore. For example:

     wls:/DefaultDomain/serverConfig> listWSMKeystoreAliases()
     

   • deleteWSMKeyStoreEntry – Deletes a single KeyStore.TrustedCertificateEntry entry from the keystore. For example:

     wls:/DefaultDomain/serverConfig> deleteWSMKeyStoreEntry(alias='testalias')
     

   • deleteWSMKeyStoreEntries – Deletes all KeyStore.TrustedCertificateEntry entries from the keystore, except those identified by the aliases in the exclusion list.

     In this example, all key store entries are deleted from the keystore, except for the testalias and testalias2 aliases, which are specified on the exclusion list:

     wls:/DefaultDomain/serverConfig> deleteWSMKeyStoreEntries(exclusionList=['testalias', 'testalias2'])
     

   • exportWSMKeyStoreCertificate – Exports a trusted certificate or a certificate chain associated with a private key, indicated by a specified alias, to a specified location.

     In this example, the trusted certificate testalias is identified by type as Certificate and is exported to the specified certificate.cer file:

     wls:/DefaultDomain/serverConfig> exportWSMCertificate(alias='testalias',certFile='/tmp/certificate.cer',type='Certificate')
     

     In this example, the certificate chain testalias2 is identified by type as PKCS7 and is exported to the specified certificatechain.p7b file:

     wls:/base_domain/serverConfig> exportWSMCertificate(alias='testalias2',certFile='/tmp/certificatechain.p7b', type='PKCS7')
     

   • importWSMKeyStoreCertificate – Imports a trusted certificate or a certificate chain associated with a private key indicated by the specified alias. The Base64 encoded certificate will be imported from the specified location.

     In this example, the trusted certificate testalias is identified by type as Certificate and is imported from the specified certificate.cer file:

     wls:/DefaultDomain/serverConfig> importWSMCertificate(alias='testalias',certFile='/tmp/certificate.cer',type='Certificate')
     

     In this example, the certificate chain testalias is identified by type as PKCS7 and is imported from the specified certificatechain.p7b file:

     wls:/base_domain/serverConfig> importWSMCertificate(alias='testalias',certFile='/tmp/certificatechain.p7b',type='PKCS7')
     

For more information about these WLST commands, see "Web Services Custom WLST Commands" in the WebLogic Scripting Tool Command Reference.

Configuring the Credential Store

Note:

To configure the credential store using the REST API, see "Credential Store Management" in REST API for Managing Credentials and Keystores with Oracle Web Services Manager.

Oracle WSM uses the Credential Store Framework (CSF) to manage the credentials in a secure form. The CSF provides a way to store, retrieve, and delete credentials for a Web Service and other applications. Oracle WSM uses the credential store to look up the following:

• Alias names and passwords for keys in the Java keystore

  For details about how Oracle WSM uses the credential store to look up alias names and passwords from the Java keystore, see "How Oracle WSM Locates Keystore And Key Passwords".

• Usernames and passwords used for authentication

  Suppose, for example, that you have a Web service that accepts a username token for authentication. If you create a Web service client to talk to this Web service, you need to configure the Web service client with a username and password that can be sent to the Web service. You store this username and password in the credential store (using either Fusion Middleware Control or WLST) and assign it a csf key.

  For example, the oracle/wss_username_token_client_policy policy includes the csf-key property, with a default value of basic.credentials. To use the wss_username_token_client_policy, you should create a new password credential in the CSF using the credential name basic.credentials, and the username and password with which the client needs to connect. If you have two Web service clients that use this same client policy, these clients can either share the same password credential, which defaults to basic.credentials, or each one can have its own credential. In the latter case, you need to create two password credentials in the CSF, for example App1.credentials and App2.credentials, for Client1 and Client2 respectively. For Client1, you set the csf-key configuration override to App1.credentials, and for Client2, you set the csf-key property to App2.credentials. For more information, see "Attaching Client Policies Permitting Overrides". Note that in both cases, the usernames and passwords must represent valid users in the OPSS identity store.

A password credential can store a username and password. A generic credential can store any credential object.

The CSF configuration is maintained in the jps-config.xml file in the domain-home/config/fmwconfig directory.

When you configure the Oracle WSM keystore using Fusion Middleware Control, as described in "Configuring the Oracle WSM Keystore", the aliases and passwords that you specify are securely stored in the credential store. If, however, you add other aliases to the keystore, or you need to add authentication credentials for a client, you need to ensure that they are configured and stored in the credential store also, as described in the following section.

Adding Keys and User Credentials to the Credential Store

You can use Fusion Middleware Control or WLST commands to add keys and user credentials to the credential store. Both methods are described in the following procedures.

Note:

The example procedures in this section describe how to add user credentials for the basic.credentials key as described above, and the example ServiceA and ServiceB aliases described in "Advanced Setup Considerations". In your own environment, you should use aliases and passwords that are appropriate for your configuration.

Before adding key credentials to the credential store, ensure that the private keys and aliases exist in the keystore. You can create them using commands such as the following:

keytool -genkeypair -keyalg RSA -alias ServiceA -keypass password -keystore default-keystore.jks -storepass password -validity 3600

keytool -genkeypair -keyalg RSA -alias ServiceB -keypass welcome3 -keystore default-keystore.jks -storepass password -validity 3600

For more information about the keystore, see "Generating Private Keys and Creating the Java Keystore".

Using Fusion Middleware Control

Follow these steps in Fusion Middleware Control to add keys and certificates to the credential store:

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

2. From the WebLogic Domain menu, select Security then Credentials.

   Figure 10-4 Credential Store Menu

   
   Description of ''Figure 10-4 Credential Store Menu''
   
   

   The Credentials page is displayed, as shown in Figure 10-5.

   Figure 10-5 Credential Store Provider Configuration Page

   
   Description of ''Figure 10-5 Credential Store Provider Configuration Page''
   
   

   Note that in this configuration, the oracle.wsm.security credential map already exists in the credential store. This credential map was created when you configured the Oracle WSM keystore as described in "Configuring the Oracle WSM Keystore". If you do not see this credential map in your configuration, you can create it by clicking the Create Map button, and entering oracle.wsm.security in the Map Name field.

3. Optionally, expand the oracle.wsm.security map in the Credential table to view the keys that have been configured in the map. Figure 10-6 illustrates a sample Oracle WSM credential store configuration.

   Figure 10-6 Keys Configured in Oracle WSM Credential Map

   
   Description of ''Figure 10-6 Keys Configured in Oracle WSM Credential Map''
   
   

   You can edit the keys in the credential map by selecting the key and clicking Edit. Make sure that any changes you make in the credential store are consistent with the definition of the key in the Oracle WSM Java keystore.

4. Click Create Key to create new entries in the oracle.wsm.security credential map, for example for the ServiceA and ServiceB aliases. The Create Key dialog box appears, as shown in Figure 10-7.

   Figure 10-7 Create Key Dialog Box

   
   Description of ''Figure 10-7 Create Key Dialog Box''
   
   

   1. From the Select Map menu, select the map name oracle.wsm.security if it is not already selected.

   2. In the Key field, enter csfServiceA to create a key-value pair to access the key store.

   3. From the Type menu, select Password.

   4. In the User Name field, enter the alias name that you specified for the private key in the keystore, for example ServiceA.

   5. In the Password and Confirm Password fields, enter the password that you specified for the alias in the keystore, for example password.

   6. In the Description field, enter a description of for the entry, for example, Key for ServiceA.

   7. Click OK.

   8. Click Create Key again and provide the values for any additional keystore aliases, such as csfServiceB for the ServiceB alias.

5. Optionally, click Create Key to create entries in the oracle.wsm.security credential map for the any csf-key user credentials, for example basic.credentials, as follows:

   1. From the Select Map menu, select the map name oracle.wsm.security if it is not already selected.

   2. In the Key field, enter basic.credentials. In this example, we use basic.credentials but you can specify any name you choose for the key.

   3. From the Type menu, select Password.

   4. In the User Name field, enter a valid username that exists in the OPSS identity store, for example AppID.

   5. In the Password and Confirm Password fields, enter a valid password for the user, for example password.

   6. In the Description field, enter a description of for the entry, for example, Username and Password for basic.credential key.

   7. Click OK.

6. Restart the server.

Using WLST

Follow these steps to add additional keys and user credentials to the credential store using WLST commands.

1. Go to the Oracle Common home directory for your installation, for example /home/Oracle/Middleware/oracle_common.

   For information about the Oracle Common home directory and installing Oracle Fusion Middleware, see the Oracle Fusion Middleware Installation Planning Guide.

2. Start WLST using the WLST.sh/cmd command located in the oracle_common/common/bin directory. For example:

   • /home/Oracle/Middleware/oracle_common/common/bin/wlst.sh (UNIX)

   • C:\Oracle\Middleware\oracle_common\common\bin\wlst.cmd (Windows)

   When executed, these commands start WLST in offline mode. To use the credential store WLST commands, you must use WLST in online mode.

3. Start Oracle WebLogic Server.

   For more information, see "Start and stop servers" in the Oracle WebLogic Server Administration Console Help.

4. Connect to the running WebLogic Server instance using the connect() command. For example, the following command connects WLST to the Administration Server at the URL myAdminServer.example.com:7001 using the username/password credentials weblogic/password:

   connect("weblogic","password","t3://myAdminServer.example.com:7001")
   

5. Use the createCred command to create entries in the oracle.wsm.security credential map for the ServiceA and ServiceB aliases. For example, create an entry csfServiceA for the ServiceA alias, using a command such as the following:

   wls:/DefaultDomain/serverConfig> createCred(map="oracle.wsm.security", key="csfServiceA", user="ServiceA", password="password", desc="Key for ServiceA")
   

6. Repeat step 5 to create an entry for any additional aliases, for example csfServiceB, for the ServiceB alias.

7. Use the createCred command to create entries in the oracle.wsm.security credential map for the any csf-key user credentials, for example basic.credentials.

   wls:/DefaultDomain/serverConfig> createCred(map="oracle.wsm.security", key="basic.credentials", user="AppID", password="password", desc="Key for ServiceA")
   

How Oracle WSM Locates Keystore And Key Passwords

Oracle WSM expects keystore and key passwords to be in the Credential Store Framework (CSF). Here is how it works.

• A JKS keystore file is protected by a keystore password.

• A keystore file consists of zero or more private keys, and zero or more trusted certificates. Each private key has its own password, (although it is common to set the key passwords to be the same as the keystore password). Oracle WSM needs to know both the keystore password and key password.

• The CSF consists of many maps, each with a distinct name. Oracle WSM only uses the map oracle.wsm.security.

• Inside each map is a mapping from multiple csf-key entries to corresponding credentials. A csf-key is just a simple name, but there can be many different types of credentials. The most common type of credential is a password credential which is primarily comprised of a username and a password.

  Oracle WSM refers to the following csf-keys inside the oracle.wsm.security map:

  • keystore-csf-key - This key should contain the keystore password. The username is ignored.

  • enc-csf-key - This key should contain the encryption key alias as the username, and the corresponding key password.

  • sign-csf-key - This key should contain the signature key alias as the username, and the corresponding key password.

  In addition to these csf-keys, you should add a csf-key entry for every new private key that you want Oracle WSM to use, for example when you want to specify signature and encryption keys in configuration overrides.

Figure 10-8 illustrates the relationship between the keystore configuration in the OPSS, the oracle.wsm.security map in the credential store, and the Oracle WSM Java keystore.

Note:

For federated environments, an application-level credential map name can be set by an administrator as a csf.map configuration override on certain predefined policies and assertion templates. For more information, see "Creating an Application-level Credential Map".

Figure 10-8 Oracle WSM Java Keystore Configuration for Message Protection

Description of ''Figure 10-8 Oracle WSM Java Keystore Configuration for Message Protection''

As shown in the figure:

• The keystore.csf.map property points to the Oracle WSM map in the credential store that contains the CSF aliases. In this case keystore.csf.map is defined as the recommended name oracle.wsm.security, but it can be any value.

• The keystore.pass.csf.key property points to the CSF alias keystore-csf-key that is mapped to the username and password of the keystore. Only the password is used; username is redundant in the case of the keystore.

• The keystore.sig.csf.key property points to the CSF alias sign-csf-key that is mapped to the username and password of the private key that is used for signing.

• The keystore.enc.csf.key property points to the CSF alias enc-csf-key that is mapped to the username and password of the private key that is used for decryption.

Creating an Application-level Credential Map

An application-level credential map name can be set in certain predefined policies using the csf.map configuration property, which can be used to override the domain-level credential map on a per-attachment basis. The csf.map configuration override is available in all policies and assertion templates that have either a csf-key or keystore-related csf keys.

For more information about configuring overrides, see "Attaching Client Policies Permitting Overrides".

For a list of the available predefined policies, see Policies that Can Be Used to Access an Application-level CSF Map.

How CSF Keys Are Retrieved from an Application-level Credential Map

The domain-level oracle.wsm.security credential map is created in the credential store when you configure the Oracle WSM keystore, as described in "Configuring the Oracle WSM Keystore".

When an application-level credential map is configured, then the client csf-keys (csf-key and user keys sts.auth.user.csf.key) are retrieved only from that map, and not the domain-level map, as follows:

• If an application-level csf map is configured, csf keys are retrieved from it. An exception is thrown if the csf key is not found.

• If an application-level map is not configured, csf keys are retrieved from the domain-level csf map. An exception is thrown if the csf key is not found.

Note that the behavior is different for shared cfs-keys, as follows:

• keystore-csf-key – This csf key will always be retrieved from the domain-level credential map (oracle.wsm.security).

• enc-csf-key – If an application-level map is configured, this csf key will be retrieved from it first; if not found, then from the domain-level csf map.

• sign-csf-key – If an application-level map is configured, this csf key will be retrieved from it first; if not found, then from the domain-level csf map.

Granting Permission to Access an Application-level Credential Map

In order to access an application-level credential map, you must:

• Configure the csf.map Property Override

• Grant CredentialAccessPermission to wsm-agent-core.jar

• Grant WSIdentityPermission to wsm-agent-core.jar

Configure the csf.map Property Override

For an application to access its own credential map, the csf.map configuration override must be set for the policy that is attached to the application.

1. Navigate to the Web Services Policy page, as described in "Navigating to the Web Services Policies Page in Fusion Middleware Control".

2. From the Web Services Policies page, select the policy for which you want to edit a property from the Policies table and click Edit.

3. On the Edit Policy page, click the Configurations tab.

4. Select the csf.map configuration property and click Edit. The Edit Configure Property dialog box shown in Figure 10-9 appears.

   Figure 10-9 Edit Configure Property Dialog

   
   Description of ''Figure 10-9 Edit Configure Property Dialog''
   
   

5. In the value field, enter the name of the application-level map for the policy to use and click OK.

6. Validate the policy.

7. Click Save.

Grant CredentialAccessPermission to wsm-agent-core.jar

Grant CredentialAccessPermission to the wsm-agent-core.jar. This permission is required for Oracle Platform Security Services (OPSS) to allow access to the credential map in the CSF store.

Using Oracle Enterprise Manager

You can grant CredentialAccessPermission to an application-level credential map from the domain's System Policies page.

1. In the Navigator pane, expand WebLogic Domain to select the domain that you want to configure a new system policy in.

2. From the WebLogic Domain menu, select Security then System Policies.

3. Click Create to open the Create System Grant page.

4. If necessary, in the Grant To drop box, select Codebase as the policy type.

5. Enter the following string in the Codebase field:

   file:${common.components.home}/modules/oracle.wsm.agent.common_${jrf.version}/wsm-agent-core.jar
   

6. Click Add above the Permissions table.

7. In the Add Permission dialog, click the Select here to enter details for a new permission check box, and enter the following information:

   Permission Class – oracle.security.jps.service.credstore.CredentialAccessPermission

   Resource Name – context=SYSTEM,mapName=application.csf.map.name,keyName=*

   Where mapName is the name of the application-level credential map that needs to be configured.

   Permission Actions – *

8. Click OK to return to the Create System Grant page. The selected permission is added to the table Permissions.

9. Click OK to return to the System Policies page. A message at the top of the page informs you the result of the operation. If successful, the policy is added to the table at the bottom of the page.

For more information about configuring system policies, see "Managing System Policies" in Oracle Fusion Middleware Application Security Guide.

Using WLST

You can grant CredentialAccessPermission to an application-level credential map using the grantPermission WLST command.

1. Start WLST and connect to the running WebLogic Server instance, as described in Using WLST.

2. Use the grantPermission command to create the codebase system policy:

   grantPermission(appStripe=None, codeBaseURL='file:${common.components.home}/modules/oracle.wsm.agent.common_${jrf.version}/wsm-agent-core.jar',principalClass=None,principalName=None,permClass='oracle.security.jps.service.credstore.CredentialAccessPermission',permTarget='context=SYSTEM,mapName=application.csf.map.name,keyName=*',permActions='*')
   

For more information about this WLST command, see "Infrastructure Security Custom WLST Commands" in the WebLogic Scripting Tool Command Reference.

Grant WSIdentityPermission to wsm-agent-core.jar

Grant WSIdentityPermission to wsm-agent-core.jar by using the mapName term and the getKey action. If this permission is not given to a particular application, it will not be able to access the application-level credential map.

Using Oracle Enterprise Manager

You can grant CredentialAccessPermission to an application-level credential map from the domain's System Policies page.

1. In the Navigator pane, expand WebLogic Domain to select the domain that you want to configure a new system policy in.

2. From the WebLogic Domain menu, select Security then System Policies.

3. If you already completed the steps in Grant CredentialAccessPermission to wsm-agent-core.jar, in the Search section, select Codebase as the type and search for the following string in the Name field:

   file:${common.components.home}/modules/oracle.wsm.agent.common_${jrf.version}/wsm-agent-core.jar
   

4. Select the codebase grant in the Search table and click Edit.

5. On the Edit System Grant page, click Add above the Permissions table.

6. On the Add Permission dialog, click the Select here to enter details for a new permission check box, and enter the following information:

   Permission Class – oracle.wsm.security.WSIdentityPermission

   Resource Name – resource=usermessagingserver,mapName=application.specific.map

   Where resource is the name of the application for which permission is required and mapName is the name of the application-level credential map that needs to be configured.

   Permission Actions – getKey

7. Click OK to return to the Create System Grant page. The selected permission is added to the table Permissions.

8. Click OK to return to the System Policies page. A message at the top of the page informs you the result of the operation and the new permissions added for codebase grant.

For more information about configuring system policies, see "Managing System Policies" in Oracle Fusion Middleware Application Security Guide.

Using WLST

You can grant CredentialAccessPermission to an application-level credential map using the grantPermission WLST command.

1. Start WLST and connect to the running WebLogic Server instance, as described in Using WLST.

2. Use the grantPermission command to create the codebase system policy:

   grantPermission(appStripe=None, codeBaseURL='file:${common.components.home}/modules/oracle.wsm.agent.common_${jrf.version}/wsm-agent-core.jar',principalClass=None,principalName=None,permClass='oracle.wsm.security.WSIdentityPermission',permTarget='resource=usermessagingserver,mapName=application.specific.map',permActions='getKey')
   

For more information about this WLST command, see "Infrastructure Security Custom WLST Commands" in the WebLogic Scripting Tool Command Reference.

Example of Granting Permission for Application-level In system-jazn-data.xml

Here is an example of granting permission in system-jazn-data.xml when used to access an application-level credential map and restrict access to a specific application. resource is the name of application for which application credential map needs to be configured and mapName is the name of the application-level credential map that needs to be configured.

<grant>
   <grantee>
      <codesource>
         <url>
file:${common.components.home}/modules/oracle.wsm.agent.common_${jrf.version}/wsm-agent-core.jar
         </url>
      </codesource>
   </grantee>
   <permissions>
      <permission>
            <class>oracle.wsm.security.WSIdentityPermission</class>
            <name>resource=usermessagingserver,mapName=application.specific.map</name>
            <actions>getKey</actions>
      </permission>
    </permissions>
</grant>

The resource term and mapName term also support asterisk (*) wildcards. Here are some examples of legal permission names when the action is getKey:

• resource=usermessagingserver,mapName=application.specific.map

  Only the usermessagingserver application can access the credential map application.specific.map.

• resource=*,mapName=application.specific.map

  All applications can access the credential map application.specific.map.

• resource=usermessagingserver,mapName=*

  The application usermessagingserver can access all credential maps.

• resource=usermessagingserver,mapName=intel-*

  The application usermessagingserver can access all credential maps that start with intel-.

• resource=intel-*,mapName=application.specific.map

  All applications that have a name starting with intel-* can access the credential map application.specific.map.

Note:

When using WSMIdentityPermission to access an application-level credential map:

• The permissions are checked only for managed applications. For Java SE applications, permissions are not checked.

• The permissions do not work in Oracle Java Cloud Service environments where java.security.AllPermission is given to Oracle WSM JARs.

• The permission is not required for accessing the domain-level credential map. See "Adding Keys and User Credentials to the Credential Store"

Policies that Can Be Used to Access an Application-level CSF Map

An application-level credential map name can be set in the following predefined policies using the csf.map configuration override property, enabling you to override the domain-level credential map on a per-attachment basis.

For more information about predefined security assertion templates that contain the csf.map configuration property, see "Security Assertion Templates".

• http_basic_auth_over_ssl_client_policy

• http_jwt_token_client_policy

• http_jwt_token_identity_switch_client_policy

• http_jwt_token_over_ssl_client_policy

• http_jwt_token_over_ssl_service_policy

• http_jwt_token_service_policy

• http_oauth2_token_client_policy

• http_oauth2_token_identity_switch_opc_oauth2_over_ssl_client_policy

• http_oauth2_token_identity_switch_over_ssl_client_policy

• http_oauth2_token_opc_oauth2_client_policy

• http_oauth2_token_opc_oauth2_over_ssl_client_policy

• http_oauth2_token_over_ssl_client_policy

• oauth2_config_client_policy

• http_saml20_token_bearer_client_policy

• http_saml20_token_bearer_over_ssl_client_policy

• multi_token_over_ssl_rest_service_policy

• multi_token_rest_service_policy

• wss10_message_protection_client_policy

• wss10_message_protection_service_policy

• wss10_saml20_token_client_policy

• wss10_saml20_token_with_message_protection_client_policy

• wss10_saml20_token_with_message_protection_service_policy

• wss10_saml_hok_token_with_message_protection_client_policy

• wss10_saml_hok_token_with_message_protection_service_policy

• wss10_saml_token_client_policy

• wss10_saml_token_with_message_integrity_client_policy

• wss10_saml_token_with_message_integrity_service_policy

• wss10_saml_token_with_message_protection_client_policy

• wss10_saml_token_with_message_protection_service_policy

• wss10_saml_token_with_message_protection_ski_basic256_client_policy

• wss10_saml_token_with_message_protection_ski_basic256_service_policy

• wss10_username_id_propagation_with_msg_protection_client_policy

• wss10_username_id_propagation_with_msg_protection_service_policy

• wss10_username_token_with_message_protection_client_policy

• wss10_username_token_with_message_protection_service_policy

• wss10_username_token_with_message_protection_ski_basic256_client_policy

• wss10_username_token_with_message_protection_ski_basic256_service_policy

• wss10_x509_token_with_message_protection_client_policy

• wss10_x509_token_with_message_protection_service_policy

• wss11_message_protection_client_policy

• wss11_message_protection_service_policy

• wss11_saml20_token_with_message_protection_client_policy

• wss11_saml20_token_with_message_protection_service_policy

• wss11_saml_or_username_token_with_message_protection_service_policy

• wss11_saml_token_identity_switch_with_message_protection_client_policy

• wss11_saml_token_with_message_protection_client_policy

• wss11_saml_token_with_message_protection_service_policy

• wss11_sts_issued_saml_hok_with_message_protection_client_policy

• wss11_sts_issued_saml_hok_with_message_protection_service_policy

• wss11_sts_issued_saml_with_message_protection_client_policy

• wss11_username_token_with_message_protection_client_policy

• wss11_username_token_with_message_protection_service_policy

• wss11_x509_token_with_message_protection_client_policy

• wss11_x509_token_with_message_protection_service_policy

• wss_http_token_client_policy

• wss_http_token_over_ssl_client_policy

• wss_saml20_token_bearer_over_ssl_client_policy

• wss_saml20_token_over_ssl_client_policy

• wss_saml_token_bearer_client_policy

• wss_saml_token_bearer_over_ssl_client_policy

• wss_saml_token_bearer_identity_switch_client_policy

• wss_saml_token_over_ssl_client_policy

• wss_sts_issued_saml_bearer_token_over_ssl_client_policy

• wss_username_token_client_policy

• wss_username_token_over_ssl_client_policy

Configuring the OPSS Keystore Service for Message Protection

Note:

To configure the OPSS keystore service for message protection using the REST API, see "KSS Keystore Management" in REST API for Managing Credentials and Keystores with Oracle Web Services Manager.

As described in "Managing Keys and Certificates with the Keystore Service" in Oracle Fusion Middleware Application Security Guide, the OPSS Keystore Service provides an alternate mechanism to manage keys and certificates for message security. You use the OPSS Keystore Service to create and maintain keystores of type KSS.

Note:

Keystores can be exported and imported. Migration is supported for JKS and JCEKS certificate formats.

There is a single Oracle WSM keystore per domain, and it is shared by all Web services and clients running in the domain. Therefore, if you choose to configure the KSS keystore as described in this section, Oracle WSM uses only that KSS keystore and ignores any JKS keystores you might have also defined.

You can perform the OPSS Keystore Service operations using both Fusion Middleware Control and WLST. This section focuses on the Fusion Middleware Control steps, but "Managing Keys and Certificates with the Keystore Service" describes both options.

Perform these steps to configure an OPSS Keystore Service for message protection:

1. Create a stripe and name it Oracle WSM. (See "Creating a Keystore with Fusion Middleware Control" in Oracle Fusion Middleware Application Security Guide for more information.)

   1. From the WebLogic Domain menu, select Security then Keystore.

   2. Click Create Stripe. The Create Stripe screen is shown in Figure 10-10.

   3. Enter Oracle WSM and click OK. You must use this name.

   Figure 10-10 Create Stripe

   
   Description of ''Figure 10-10 Create Stripe''
   
   

2. Create a keystore named keystore in the Oracle WSM stripe. (See "Creating a Keystore with Fusion Middleware Control" in Oracle Fusion Middleware Application Security Guide for more information.)

   1. Select the Oracle WSM stripe you created and click Create Keystore.

      The Create Keystore page is shown in Figure 10-11.

      Figure 10-11 Create Keystore

      
      Description of ''Figure 10-11 Create Keystore''
      
      

   2. Name this keystore keystore. You must use this name.

   3. Set the protection type to Policy.

   4. Clear the Grant Permission check box.

   5. Do not specify a value in the Code Base URL field.

   6. Click OK.

3. Select the keystore you just created and click Manage.

   The Manage Certificates screen is shown in Figure 10-12.

   Figure 10-12 Manage Certificates

   
   Description of ''Figure 10-12 Manage Certificates''
   
   

4. Click Generate Keypair to generate a private/public key pair.

   You typically use this keypair to both sign and encrypt requests. However, you can create separate key pairs for signing and encryption if you so choose.

   The Generate Keypair screen is shown in Figure 10-13.

   Figure 10-13 Generate Keypair

   
   Description of ''Figure 10-13 Generate Keypair''
   
   

   1. Specify an alias such as orakey for the key pair.

   2. Specify other site-specific information as appropriate.

   3. You can accept the default RSA key size if appropriate for your environment. Oracle requires a key length of 1024 bits or larger.

   4. Click OK.

5. The certificate is generated by default as being issued by CN=CertGenCAB, OU=FOR TESTING ONLY, O=MyOrganization, L=MyTown, ST=MyState, C=US. This issuer does not exist in the keystore in the Oracle WSM stripe. Before you can use this certificate, you must do one of the following:

   • Export the democa certificate from the castore keystore in the system stripe and import it into the keystore keystore in the Oracle WSM stripe as a trusted certificate.

   • Export the certificate you generated to a file, sign it using a CA, and import the CA as well as the certificate into the keystore keystore in the Oracle WSM stripe.

6. Configure Oracle WSM to use this keystore and alias.

   From the WebLogic Domain menu, select Security then Security Provider Configuration, as shown in Figure 10-14.

   Figure 10-14 Security Provider Configuration Menu

   
   Description of ''Figure 10-14 Security Provider Configuration Menu''
   
   

   The Security Provider Configuration page is displayed, as shown in Figure 10-15.

   Figure 10-15 Security Provider Configuration Page

   
   Description of ''Figure 10-15 Security Provider Configuration Page''
   
   

7. Click Configure in the Keystore section of the page.

   The Keystore Configuration page is displayed, as shown in Figure 10-16.

   Figure 10-16 Keystore Configuration

   
   Description of ''Figure 10-16 Keystore Configuration''
   
   

8. In the Keystore Type field, select Keystore Service (KSS) as the type.

   The KSS configuration page appears, as shown in Figure 10-17.

   Figure 10-17 KSS Keystore Configuration Page

   
   Description of ''Figure 10-17 KSS Keystore Configuration Page''
   
   

9. In the Identity Certificates section of the page, enter the alias for the signature and encryption keys as follows:

   • For the Signature Key, enter the alias name in the Key Alias field. The value you specify here must match the value in the keystore. For example, orakey.

   • For the Encryption Key, enter the alias name in the Crypt Alias field. The value you specify here must match the value in the keystore. For example, orakey.

   The alias for the signature and encryption keys is used to store and retrieve the keys.

   Note:

   As described in "Configuring the Oracle WSM Keystore", when you use Fusion Middleware Control to configure the Oracle WSM keystore, Oracle WSM creates entries in the credential store for the credential map oracle.wsm.security, and any keys that you define. No action on your part is required.

   This is true for the KSS keystore as well, with one notable difference: the created keystore.sig.csf.key and keystore.enc.csf.key properties in the credential store point directly to the alias. (For JKS, these properties point to a CSF key that points to the sign key and password.)

10. Click OK to submit the changes.

    If you used a file-based keystore provider, the changes require a server restart to take effect. A restart is not required for database or LDAP-based keystore service providers.

11. Optionally, obtain trusted certificates, as described in "Importing a Certificate or Trusted Certificate with Fusion Middleware Control" in Oracle Fusion Middleware Application Security Guide.

12. Set up the Web service client keystore, as described in "Setting Up the Web Service Client Keystore".

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:

• 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_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:

• Oracle WebLogic Server Administration Console Help for complete information, particularly the topic "Servers: Configuration: Keystores."

• Securing Oracle WebLogic Server, particularly Configuring Identity and Trust.

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

Configuring Synchronization of JKS Keystore File on Cluster

If you configure JKS keystore in fresh installs or use JKS in upgrade scenarios and want synchronization of JKS keystore file to happen on cluster without server restart, then perform the following steps:

1. Open the wsm-client-mbeans.xml file in a text editor.

2. Add the following property manually to wsm-client-mbeans.xml:

   <config-file path="../default-keystore.jks"/>
   

   Note:

   The default-keystore.jks can have other name as well. Therefore, the file path must be provided accordingly.

   JKS MBean in the wsm-client-mbeans.xml file should be similar to:

   <?xml version = '1.0' encoding = 'UTF-8' standalone='yes'?>
   <application-mbeans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/11/application-mbeans-11_1.xsd" schema-major-version="11" schema-minor-version="1">
   <config-mbeans>
         <jmx-config-mbean
                objectname="oracle.wsm:type=security,name=JKSKeystoreMBean"
                class="oracle.wsm.security.store.jks.mgmt.KeystoreMBeanImpl"
               
    management-interface="oracle.wsm.security.store.jks.mgmt.KeystoreMBean">
               <description>MBean to access and manage JKS
   Keystore</description>
               <config-file path="../default-keystore.jks"/>
           </jmx-config-mbean>
       </config-mbeans>
   </application-mbeans>
   

3. Save the wsm-client-mbeans.xml file.

4. After adding the config file path, restart the server.

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:

• "Configuring SSL in Oracle Fusion Middleware", in Oracle Fusion Middleware Administrator's Guide

• "Configuring SSL" in Securing Oracle WebLogic Server

• "Set Up SSL" in the Oracle WebLogic Server Administration Console Help

• "Configuring Secure Sockets Layer" in Oracle Fusion Middleware Administrator's Guide for Oracle HTTP Server

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 "Configuring SSL in Oracle Fusion Middleware" in Oracle Fusion Middleware Administrator's Guide.

   4. Restart Oracle HTTP Server.

      For more information, see "Configuring SSL 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 password -auto_login
   ./orapki wallet display -wallet <wallet_location> -pwd password
   ./orapki cert display -cert <wallet_location>/ohs.crt
       
   ./orapki wallet add -wallet <wallet_location> -keysize 512 -dn "CN=<host_name>,OU=st,O=Oracle WSM,L=N,ST=delhi,C=IN"
   -self_signed -validity 700 -serial_num 20 -cert <wallet_location>/ohs.crt -user_cert -pwd password
       
   ./orapki wallet display -wallet <wallet_location> -pwd password
       
   JAVA_HOME/bin/keytool -import -trustcacerts -file ohs.crt -alias sslcert -keystore client_keystore.jks -storepass password
   

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:\\Oracle WSM_
QA\\11g\\PS2\\OHS\\wallet\\client_keystore.jks");
    System.setProperty("javax.net.ssl.trustStorePassword","password");
    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 "Configuring SSL in Oracle Fusion Middleware" in Oracle Fusion Middleware Administrator's Guide.

   4. Restart Oracle HTTP Server.

      For more information, see "Configuring SSL 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 password -validity 700
   ./orapki wallet add -wallet <wallet_location> -cert
    <wallet_location>/twowayssl.crt -trusted_cert -pwd password
   

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, "password");
    System.setProperty("javax.net.ssl.trustStore","D:\\Oracle WSM_
QA\\11g\\PS2\\OHS\\wallet\\twowaykeystore.jks");  
    System.setProperty("javax.net.ssl.trustStorePassword","password");
    System.setProperty("javax.net.ssl.trustStoreType","JKS");   
    System.setProperty("javax.net.ssl.keyStore","D:\\Oracle WSM_QA\\11g\\PS2\\OHS\\wallet\\twowaykeystore.jks");
    System.setProperty("javax.net.ssl.keyStorePassword","password");
    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);
  }

Hardware Integration

This section describes setup information for the following hardware-related topics:

• "Using Hardware Security Modules With Oracle WSM"

• "Configuring Oracle WSM for Oracle SPARC T4 Cryptographic Acceleration"

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"

• "Configuring the JRE Used By Oracle WSM"

• "Logging On to Luna SA"

• "Copying Keys and Certificates from JKS to Luna SA"

• "Configuring Oracle WSM to Use Luna SA"

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

   Figure 10-18 Web Services Manager Keystore Configuration Page

   
   Description of ''Figure 10-18 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-19.

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

   
   Description of ''Figure 10-19 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.

Configuring Oracle WSM for Oracle SPARC T4 Cryptographic Acceleration

Oracle WSM supports the use of Oracle SPARC T4 processor-based servers, which eliminate the need for third-party security hardware by integrating computing, security, and I/O on a single chip. Deploying Oracle WSM on Oracle SPARC T4 based servers transparently leverages the T4 processor based cryptographic capabilities. This delivers high-performance security for scenarios that rely on compute-intensive cryptographic operations, such as those imposed by transport-layer and message-layer protection policies.

This section describes how to configure Oracle WSM to take advantage of cryptographic acceleration capabilities of Oracle SPARC T4 processor-based servers.

This section applies only to users who are running Oracle SPARC T4 processor-based servers running Oracle Solaris 10 8/11 or later.

The following topics are described:

• "Terms You Need to Understand"

• "Overview of Oracle SPARC T4 Hardware Assisted Cryptographic Acceleration"

• "Configuring Transport-Level Security for Cryptographic Acceleration"

• "Configuring Message-level Security for Cryptographic Acceleration"

• "Additional Reading"

Terms You Need to Understand

This section uses the following terms that you need to understand. Refer to the whitepaper described in "Additional Reading" for a complete discussion of these terms.

• PKCS#11 token — A token that generically refers to all the hardware and software tokens that implement the PKCS#11 API. The PKCS#11 API is an RSA standard for integrating hardware cryptographic accelerators, cryptographic tokens (for example, SCA-6000), and smart cards.

  A software based PKCS#11 token is a PKCS#11 token implemented entirely in software (for example, Solaris PKCS11 Softtoken.)

• Solaris Cryptographic Framework — The Solaris Cryptographic Framework (SCF) library plays a vital role in providing application access to hardware-assisted cryptographic acceleration provided by Oracle T-series processors and Hardware Security Modules (HSM), including the Oracle Sun Crypto Accelerator 6000 PCIe Card (SCA-6000) and third-party HSMs. SCF is based on PKCS#11 standard interfaces and provides a set of cryptographic services for kernel-level and user-level consumers to perform cryptographic operations.

Overview of Oracle SPARC T4 Hardware Assisted Cryptographic Acceleration

The Oracle SPARC T4 processor is part of Oracle's SPARC T-series processors family, which combines multiprocessing at the processor core level and hardware multithreading inside of each core with an efficient instruction pipeline to enable Chip Level Multi-Threading (CMT). These processors present a unique "System-on-a-Chip" design principle that incorporates specialized features such as on-chip/on-core cryptographic acceleration, 10 Gigabit Ethernet networking, and hardware-enabled virtualization capabilities. Each core of the Oracle SPARC T4 processor contains a Stream Processing Unit (SPU) to perform processing of cryptographic operations at the same clock speed as the core. The SPU is designed to achieve wire-speed encryption and decryption on the processor's 10 GbE ports.

Configuring and deploying Oracle WSM on Oracle SPARC T4 based servers delivers high performance by leveraging the T4 on-core cryptographic instructions to perform computationally intensive cryptographic operations as part of Web service security transactions using SSL and WS-Security mechanisms. For example, all message protection policies are computationally intensive.

Oracle WSM makes use of SPARC T4 processor based cryptographic acceleration in the following scenarios:

• Transport-level security, as described in "Configuring Transport-Level Security for Cryptographic Acceleration".

  Oracle WSM and WebLogic Server rely on the underlying Java Cryptographic Extensions (JCE) provider for supporting SSLv3/TLSv1 based secure communication. On Oracle Solaris/SPARC-based deployments, the Sun JCE provider is bundled with the Java runtime environment.

  The Java PKCS#11 interfaces off-load and accelerate the compute-intensive cryptographic workloads (for example, RSA, AES and ECC) of SSL/TLS protocols by using the on-core cryptographic instructions of SPARC T4 processor.

• Message-level security, as described in "Configuring Message-level Security for Cryptographic Acceleration".

  Message-level security builds on cryptographic operations that support Web Services security standards such as WS-Security, WS-SecurityPolicy, and WS-Trust.

  In particular, Web services security makes use of public-key encryption, digital signature (for example, RSA, DSA and ECC), bulk encryption (for example, AES, 3DES, and DES) and message digest (for example, SHA-1, SHA-2, and MD5) functions intended for supporting XML encryption, XML digital signature and related cryptographic operations.

  Oracle WSM implements a dedicated PKCS#11 interface to delegate cryptographic operations (via SCF) to on-core cryptographic instructions of SPARC T4 processor.

Configuring Transport-Level Security for Cryptographic Acceleration

Perform the following tasks to configure cryptographic acceleration for transport-level security:

1. Configure the WebLogic Server keystore, as described in "Configure keystores" in the Oracle WebLogic Server Administration Console Help.

   Choose "Custom Identity and Java Standard Trust" and Java KeyStore (JKS).

2. Enable JSSE SSL for WebLogic Server.

   Using JSSE based SSL automatically leverages the SunPKCS11 provider implementation pre-configured with the Java runtime environment on Solaris SPARC.

   See "Enabling and Disabling the JSSE-Based SSL Implementation" in Securing Oracle WebLogic Server for the steps to follow.

3. Confirm the use of the SunPKCS11 provider.

   The SunPKCS11 provider is a Java based PKCS#11 implementation that integrates with underlying PKCS#11 implementations provided by the SCF and its exposed cryptographic providers.

   In a typical WebLogic server installation on Solaris, the Java runtime environment is pre-configured to make use of the SunPKCS11 provider.

   Therefore, make sure that the SunPKCS11 provider is listed as the first provider in the $JAVA_HOME/jre/lib/security/java.security properties file:

   security.provider.1=sun.security.pkcs11.SunPKCS11 ${java.home}/lib/security/sunpkcs11-solaris.cfg
   
   

   The relevant portion of the default Solaris $JAVA_HOME/jre/lib/security/java.security file is shown in Example 10-7.

   Example 10-7 Partial java.security File

   #
   # List of providers and their preference orders (see above):
   #
   security.provider.1=sun.security.pkcs11.SunPKCS11 ${java.home}/lib/security/sunpkcs11-solaris.cfg
   security.provider.2=sun.security.provider.Sun
   security.provider.3=sun.security.rsa.SunRsaSign
   security.provider.4=com.sun.net.ssl.internal.ssl.Provider
   security.provider.5=com.sun.crypto.provider.SunJCE
   security.provider.6=sun.security.jgss.SunProvider
   security.provider.7=com.sun.security.sasl.Provider
   security.provider.8=org.jcp.xml.dsig.internal.dom.XMLDSigRI
   security.provider.9=sun.security.smartcardio.SunPCSC
   
   

4. Restart WebLogic Server.

5. Verify that the SSL configuration is working.

Configuring Message-level Security for Cryptographic Acceleration

Perform the following tasks to configure cryptographic acceleration for message-level security:

1. From the Solaris command line, create a PKCS11 keystore.

   To create and initialize a PKCS11 keystore, use the pktool setpin command.

   When you specify keystore=pkcs11, the keystore defaults to "Sun Software PKCS#11 softtoken."

   If the softoken keystore has not yet been initialized, use "changeme" as the original passphrase.

   # pktool setpin keystore=pkcs11
   Enter token passphrase:
   Create new passphrase:
   Re-enter new passphrase:
   Passphrase changed.
   
   

2. Generate private keys for the keystore.

   # pktool genkeypair keystore=pkcs11 keytype=rsa keylen=1024 hash=sha1
   
   

3. Alternatively, you can choose to import the key from a Java keystore to the Solaris Softtoken keystore by using the following command.

   # keytool –importkeystore
   -srckeystore /opt/Oracle/Middleware/default-keystore.jks
   -destkeystore NONE -srcstoretype JKS
   -deststoretype PKCS11
           -srcstorepass changeme -deststorepass your-scfpassword
   

4. From the Solaris command line, verify that the keys are present in the Solaris Softtoken keystore.

   keytool -list -storetype pkcs11 -keystore NONE
   

5. Make sure that the algorithm suites of the policies you use are not in the disabledMechanisms list in the $JAVA_HOME/jre/lib/security/sunpkcs11-solaris.cfgsunpkcs11-solaris.cfg configuration file.

   For example, if the specified algorithm suite for a policy is Basic256Rsa15 as shown in Figure 10-20, it uses Aes256 encryption and KwAes256/kwRsA15 for key wrap. In this case, make sure that CKM_AES is not in the disabledMechanisms list in the configuration file.

   Figure 10-20 Sample Algorithm Suite

   
   Description of ''Figure 10-20 Sample Algorithm Suite''
   
   

   See Appendix A Sun PKCS#11 Provider's Supported Algorithms in the Java PKCS#11 Reference Guide for the list of supported algorithms.

6. Configure the Oracle WSM keystore.

   Follow these steps to configure the PKCS11 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-18.

      Figure 10-21 Web Services Manager Keystore Configuration Page

      
      Description of ''Figure 10-21 Web Services Manager Keystore Configuration Page''
      
      

   4. In the Keystore Type drop-down, select Public Key Cryptographic Standards (PKCS-11), as shown is Figure 10-19.

      Figure 10-22 Web Services Manager PKCS-11 Keystore

      
      Description of ''Figure 10-22 Web Services Manager PKCS-11 Keystore''
      
      

   5. Enter the password for the keystore and confirm it. This password must match the PKCS11 keystore password you entered in Step 1.

   6. In the Key Alias and Crypt Alias fields, enter an alias for the signature and encryption keys and the corresponding key passwords. The alias and password for the signature and encryption keys define the string alias and passwords used to store and retrieve these keys. These keys must be present in the PKCS11 keystore.

   7. Click OK to submit the changes.

   8. Restart Fusion Middleware Control.

7. Verify the configuration.

   To ensure the hardware-assisted cryptographic acceleration is correctly configured and working, use the following Solaris DTrace script.

   #!/usr/sbin/dtrace -s 
   pid$1:libsoftcrypto:yf*:entry, 
   pid$1:libmd:yf*:entry 
   { 
     @[probefunc] = count(); 
   } 
   tick-10sec 
   { 
     printa(@); 
     clear(@); 
     trunc(@,0); 
   } 
   tick-100sec 
   {exit(0);} 
   
   

   Save this script as a file named cryptoverify.d. Run this script with the WebLogic Server's Java process ID as a command line argument, as follows:

   # dtrace -s cryptoverify.d  <WeblogicServer Process ID>
   

   For example, in an encryption scenario using the AES algorithm, a positive and growing value of AES jobs indicates that cryptographic acceleration is operational on the target AES bulk encryption payloads.

Additional Reading

For information on deploying Oracle WSM on Oracle SPARC T2+/T3 processors, refer to the whitepaper "High Performance Security for SOA and XML Web Services Using Oracle Web Services Manager and Oracle SPARC Enterprise T-series Servers," which is available at http://www.oracle.com/technetwork/articles/systems-hardware-architecture/hi-perf-soa-xml-svcs-172821.pdf.

The whitepaper is the definitive source for cryptographic acceleration information for using Oracle SPARC T2+ and T3 processor based servers

The whitepaper covers many additional pertinent topics such as Solaris Cryptographic Framework components, using Solaris Kernel SSL (KSSL), and performance characteristics.

Using Service Identity Certification Extension

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.

Note:

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

The certificate in the WSDL is the service's public key by default, as determined by the Encryption Key you specified when you configured the keystore as described in "Configuring Keystores for Message Protection".

If this certificate is not found in the WSDL, 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 for the Certificate Included in WSDL

The hostname verification feature 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 "Configuring Keystores for Message Protection".

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

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

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

2. 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:

By default, if the certificate is published in the WSDL, then the client override property value for keystore.recipient.alias is ignored.

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

Policies that use any of the supported token types -- including username, X.509, Kerberos, SAML, HTTP BASIC and so forth -- require an authentication provider, such as the WebLogic Default Authentication 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

• 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 configure any of the WebLogic Server Authentication providers for use with Oracle WSM. That is, you can use any of the following Web logic Server Authentication providers, regardless of the token type:

• The WebLogic Authentication provider, also known as the DefaultAuthenticator.

• Oracle Internet DirectoryAuthenticator or Oracle Virtual Directory Authenticator.

• LDAP Authenticator or Open LDAP Authenticator.

• RDBMS Authentication providers.

Note:

If you use an RDBMS authentication provider, or any other non-LDAP-based provider, there is a limitation that you cannot specify custom attributes to be added to the SAML assertion that Oracle WSM generates. This limitation does not exist for any of the LDAP-based providers.

This means that for policies that use SAML, Kerberos, and X.509 tokens, you do not have to configure a WebLogic Server provider to handle these specific token types.

More specifically, the Oracle WSM runtime does not use any other WebLogic Server providers, including but not limited to:

• Any Identity Assertion provider

• X509 providers

  Oracle WSM policies based on an X509 token do not use the WebLogic Server X509 Identity Assertion provider.

• SAML providers

  Oracle WSM policies based on a SAML token do not use the WebLogic Server SAML providers.

• Credential Mapper providers

• Authorization providers

• Role Mapper providers

• Certification Path provider

• Auditing provider

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:

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

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

• krb5.loginmodule—The Kerberos login module is a JAAS login module that authenticates users using Kerberos protocols. The Kerberos login module has optional properties that you can configure.

(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-23is displayed.

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

   
   Description of ''Figure 10-23 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 Authentication 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:

• 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_saml20_token_service_policy

• oracle/wss10_saml20_token_client_policy

• oracle/wss10_saml_token_with_message_protection_client_policy

• oracle/wss10_saml_token_with_message_protection_service_policy

• oracle/wss10_saml20_token_with_message_protection_client_policy

• oracle/wss10_saml20_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

• oracle/wss11_saml20_token_with_message_protection_service_policy

• oracle/wss11_saml20_token_with_message_protection_client_policy

The following sections provide more information about SAML configuration:

• "How the SAML Token is Validated"

• "How to Configure SAML Web Service Client at Design Time"

• "Including User Attributes in the Assertion"

• "Including User Roles in the Assertion"

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

• "Adding an Additional SAML Assertion Issuer Name"

• "Configuring Web Service Clients for Identity Switching"

• "Defining a Trusted Distinguished Name (DN) List for SAML Signing Certificates"

• "Using Anonymous Users with SAML Policies"

• "Configuring Web Service Clients for Identity Switching"

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

Which Authentication Provider is Used?

Any configured Authentication provider as described in "Configuring an Authentication Provider in WebLogic Server" can then be invoked.

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. (If subject.precedence is true, the user name to create the SAML assertion is obtained only from the Subject.)

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

   Figure 10-24 Identity Store Configuration Page

   
   Description of ''Figure 10-24 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-25.

   Figure 10-25 Adding the virtualize property

   
   Description of ''Figure 10-25 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 Authentication 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 "Configuring Keystores 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 a SAML predefined Web service 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.

Note:

Although you can add an issuer by the mechanism described here, it is for backward compatibility only. The preferred method is to configure trusted issuers at the platform policy configuration level. See "Defining Trusted Issuers and a Trusted DN List for Signing Certificates".

There is a hierarchy that determines how trusted issuers are determined:

1. First, the list of trusted issuers configured for policies (or overridden) is checked and used.

2. If not configured for policies (or overridden), the configuration at the platform policy configuration is checked and used. See "Defining Trusted Issuers and a Trusted DN List for Signing Certificates".

3. If not configured for policies (or overridden) or configured at the platform policy configuration, only then is the Issuers list defined in the SAML login module used.

If you do define the SAML issuers by the mechanism described here, the issuers are persisted in jps-config.xml, and any changes take effect only after a restart of the domain.

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

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

   
   Description of ''Figure 10-26 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.

Defining a Trusted Distinguished Name (DN) List for SAML Signing Certificates

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

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

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

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

Using Anonymous Users with SAML Policies

All SAML policies allow anonymous users to be propagated. For example if you have an ADF application that can work with either authenticated users or an anonymous user, and this ADF application needs to make a call to a Web service and propagate the current user, then you can propagate both the authenticated users and the anonymous user using any of the SAML policies. From the security perspective, propagating the anonymous user over SAML is equivalent to the client not sending any authentication tokens to the service.

Allowing anonymous users over SAML is provided as a convenience so that you can have one policy that supports both authenticated and anonymous users. Note, however, that anonymous propagation over SAML is non-standard and will not interoperate with other vendors. It should only be used when both the client and the Web service are using Oracle WSM.

Using JSON Web Token (JWT) with Oracle WSM

JSON Web Token (JWT) is a means of representing claims to be transferred between two parties. JWT is a compact token format intended for space- constrained environments such as HTTP Authorization headers and URI query parameters.

The following sections provide a high-level example and the necessary configuration steps to use JWT with Oracle WSM:

• Example JWT Use Case (High Level Steps)

• Configuring the Client and Service for Propagating the JWT Token

Example JWT Use Case (High Level Steps)

This example use case demonstrates the following scenario:

• Using a browser, an end user points to a partner-embedded user interface within a client Web application.

• To display user-customized information and perform further transactional work, the browser calls an external partner application and authenticates/authorizes.

• The partner application retrieves end user related data (such as email) from the client application.

• The transactional work is completed by calling back to a secure SOAP or RESTful Web service (on behalf of the end user that initially logged into the client Web application, thus performing identity propagation).

The following high-level steps describe how to implement this example use case by passing a JWT token between the client Web application, the partner application, and an Oracle WSM protected Web service.

Figure 10-27 illustrates this example.

Figure 10-27 Propagating JWT Token Example

Description of ''Figure 10-27 Propagating JWT Token Example''

Note:

This example assumes the client and service have been properly configured as described in "Configuring the Client and Service for Propagating the JWT Token".

1. The client Web application invokes the OPSS Trust Service to obtain the JWT token.

   To do so, it needs to pass the UserID to the TokenManager. Optionally, it can also pass other UserInfo (such as email, firstName, and so on) and AppInfo (such as orgID, opportunityID) as new Claims, as shown in Example 10-8.

   Example 10-8 Invoking OPSS Trust Service to Obtain JWT Token

   javax.security.auth.Subject subject = javax.security.auth.Subject.getSubject(AccessController.getContext());
    String userName = oracle.security.jps.util.SubjectUtil.getUserName(subject);      
     JpsContextFactory ctxFactory = JpsContextFactory.getContextFactory();
           JpsContext jctx = ctxFactory.getContext();
           TrustService trustService = jctx.getServiceInstance(TrustService.class);
           final TokenManager tokenMgr = trustService.getTokenManager();
    
           // Issue token
       final ExtendedTokenContext ectx = (ExtendedTokenContext) tokenMgr.createTokenContext(TokenConfiguration.PROTOCOL_EMBEDDED);
           ectx.setTokenType(JwtToken.JWT);
           TrustToken tsToken = new TrustToken(TokenConstants.TOKEN_TYPE_USERID, userName);
           ectx.setTrustToken(tsToken);
           ectx.setIssuer("www.oracle.com");
                   
           Map<String, Object> ctxProperties = ectx.getOtherProperties();
           ctxProperties.put("trust.tokenSigningMethod", JwtToken.SIGN_ALGORITHM.RS256.toString());
   // Passing parameters like email, opportunityID 
   ArrayList<Object> emailValue = new ArrayList<Object>();
   emailValue.add("[e-mail]");
   Claim emailClaim = new Claim("oracle:apps:attributes:email", emailValue);
    
   ArrayList<Object> oppIDValue = new ArrayList<Object>();
   oppIDValue.add("200");
   Claim oppIDClaim = new Claim("oracle:apps:attributes:opportunityID", oppIDValue);
   List<Claim> list = new ArrayList<Claim>();
   list.add(emailClaim);
   list.add(oppIDClaim);
    
   ectx.setClaims(list)
    
           Object tokenData = AccessController.doPrivileged(new PrivilegedExceptionAction<Object>() {
                                   @Override
                                   public Object run() throws Exception {
                                           try {
                                                   return  tokenMgr.issueTrustToken(ectx);
    
                                           } catch (Exception ex) {
                                                       throw ex;
                                   }
                                   }
                           });
              Object tokValue = ectx.getTrustToken().getTokenValue(); //base 64 encoded JWT token 
   

   For more information about obtaining a token from the OPSS Trust Service, see the following topics in Oracle Fusion Middleware Application Security Guide:

   • The OPSS Trust Service

   • Propagating Identities with the OPSS Trust Service

2. The client Web application passes the JWT token to the partner application in the URL parameter:

   ?token=<tokValue>
   

   Note:

   The transport channel used to pass the token must be secured using SSL.

3. The partner application extracts the token from the URL parameter and verifies the token signature.

4. The partner application passes the token extracted from the URL parameter to a SOAP or RESTful Web service protected with an Oracle WSM service policy in the Authorization:Bearer HTTP header:

   Authorization:Bearer <tokValue>
   

   Note:

   The transport channel used to pass the token must be secured using SSL.

5. Oracle WSM verifies the JWT token and establishes the subject with the user identity. Note that the user identity being propagated must exist in the identity store on the service side.

Configuring the Client and Service for Propagating the JWT Token

It is necessary to perform configuration on both the client side and the service side, as described in the following sections:

• Client-side Configuration for JWT Token Propagation

• Service-side Configuration for JWT Token Propagation

There is no configuration required for the customer application.

Client-side Configuration for JWT Token Propagation

The OPSS Trust Service uses the KSS keystore, and Oracle WSM uses the JKS keystore (default-keystore.jks). It is necessary to sync these two keystores by copying the JKS keystore into the OPSS KSS keystore, and then grant the client application the appropriate permission to access the OPSS Trust Service.

Step 1: Sync the KSS and JKS Keystores

1. Make a copy of the Oracle WSM JKS keystore:

   1. Create a directory called kss on your filesystem.

   2. Copy the Oracle WSM keystore default-keystore.jks from the $DOMAIN_HOME/config/fmwconfig directory into kss directory:

      cp default-keystore.jks default-keystore-copy.jks                       chmod 777 default-keystore-copy.jks
      

2. Change the orakey alias to trustservice alias in the keystore:

   keytool -changealias -alias orakey -keypass orakey -destalias trustservice -storepass password -keystore ./default-keystore-copy.jks
   

   Note:

   In this example, the keypass is orakey and the storepass is password. Be sure to use the appropriate passwords for your keystore.

3. Upload the keystore in KSS by executing the following CLI commands:

   Note:

   The stripeName and KeystoreName are configured as follows:

   stripeName=opss and keystoreName=trustservice_ks, which contains KeyPair with the alias specified as trustservice

   stripeName=opss, keystoreName=trustservice_ts, which contains Certificate, with alias specified as trustservice

   svc = getOpssService(name='KeyStoreService')
   svc.deleteKeyStoreEntry(appStripe='opss', name='trustservice_ks', password='', alias='trustservice', keypassword='password')
   svc.deleteKeyStoreEntry(appStripe='opss', name='trustservice_ts', password='', alias='trustservice', keypassword='password')
    
   svc.importKeyStore(appStripe='opss', name='trustservice_ks', password='', aliases='trustservice', keypasswords='password', type='JKS', permission=true, filepath=Oracle WSMkeystorecopy)
   svc.importKeyStore(appStripe='opss', name='trustservice_ts', password='', aliases='trustservice', keypasswords='password', type='JKS', permission=true, filepath=Oracle WSMkeystorecopy)
    
   print '--------\--list keystore alias-\-------------------------------------------'
    
   svc.listKeyStoreAliases(appStripe='opss', name='trustservice_ks', password='', type='*')
   svc.listKeyStoreAliases(appStripe='opss', name='trustservice_ts', password='', type='*')
   

Step 2: Grant OPSS Trust Service Permission to Client Web Application

Before it can invoke the OPSS Trust Service to obtain the JWT token, the client Web application must be granted the TrustServiceAccessPermission using the grantPermission WLST command, as follows:

grantPermission(codeBaseURL="file:${oracle.deployed.app.dir}/MyApp${oracle.deployed.app.ext}",
permClass="oracle.security.jps.service.trust.TrustServiceAccessPermission",permTarget="appId=*", permActions="issue")

In this command line, replace MyApp with the name of the client application.

Service-side Configuration for JWT Token Propagation

On the service side, you must secure the Web service with an Oracle WSM policy that supports the JWT token, and configure the JWT trusted issuer for the domain.

Step 1: Secure the Web Service

Secure the SOAP Web service or RESTful servlet application using one of the following policies:

• For a SOAP Web service, use wss11_saml_or_username_token_with_message_protection_service_policy. For details about attaching policies to SOAP Web services, see "Attaching Policies to Web Services".

• For RESTful servlet applications, use multi_token_rest_service_policy. For details about attaching policies to RESTful servlet applications, see "Attaching Policies to Servlet Applications".

For instructions on configuring Web services with policies that enable identity switching for JWT tokens, see "Configuring Web Service Clients for Identity Switching".

Step 2: Define the Trusted Issuer for the JWT Token

You define the JWT Trusted Issuer using the setWSMTokenIssuerTrust WLST command as described in "Defining Trusted Issuers and Managing DN Lists Using WLST". For example:

setWSMTokenIssuerTrust('dns.jwt','www.oracle.com',['CN=weblogic, OU=Orakey Test Encryption Purposes Only, O=Oracle, C=US'])

Using OAuth2 with Oracle WSM

This section describes using the Oracle Mobile and Social OAuth2 authorization framework with Oracle WSM.

The section assumes that you are familiar with both the terminology and the conceptual and configuration information described in the following sections of Oracle Fusion Middleware Administrator's Guide for Oracle Access Management:

• "Understanding OAuth Services"

• "Configuring OAuth Services"

Understanding OAuth2 with Oracle WSM

OAuth2 support in Oracle WSM is based on "The OAuth 2.0 Authorization Framework" specification, which is available at http://tools.ietf.org/html/rfc6749. Oracle WSM uses the Oracle Mobile and Social OAuth2 service as the authorization server for the OAuth2.0 protocol interactions.

Oracle WSM allows web service clients to interact with the Mobile and Social OAuth2 server implementation for both SOAP and REST web services, for "2-legged" authorization.

2-Legged Authorization

In 2-legged OAuth2, the interaction is application-to-application without user consent.

The client requests authorization from the resource owner. In response, the client receives an authorization grant, which is a credential representing the resource owner's authorization. Then:

1. The client requests an access token (AT) by authenticating with the authorization server and presenting the authorization grant.

2. The authorization server authenticates the client and validates the authorization grant, and if valid, issues an AT.

3. The client requests the protected resource from the resource server and authenticates by presenting the AT.

4. The Oracle WSM server side agent validates the AT and accepts the request if valid or rejects the request if invalid.

You attach the OAuth2 client policy such as oracle/http_oauth2_token_client_policy and the oracle/oauth2_config_client_policy to the client application. The required token.uri property of the oracle/oauth2_config_client_policy policy specifies the OAuth2 server token endpoint.

You also attach any of the following Oracle WSM JWT service policies to the web service. The Oracle WSM server-side agent validates the access token.

• oracle/http_jwt_token_service_policy

• oracle/http_jwt_token_over_ssl_service_policy

• multi_token_rest_service_policy

• multi_token_over_ssl_rest_service_policy

(See "Using JSON Web Token (JWT) with Oracle WSM" for information on the Oracle WSM JWT service policies.)

Supported Authorization Grant Types in 2-Legged Authorization

As previously described, an authorization grant is a credential representing the resource owner's authorization. Oracle WSM supports the following authorization grant types in 2-legged authorization. You specify which types you want to use when you configure the OAuth2 OWSM client profile, as described in "Prerequisites for Using the Oracle WSM OAuth2 Policies".

• Client credentials grant - In this case the client credentials are sent in the "Authorization: Basic" HTTP header as explained in Client Credentials Grant - OAuth2.0 Authorization Framework.

  You set the client token policy oauth2.client.csf.key property to specify the user name and password to use. Ensure that the federated.client.token property is set to false.

• Client credentials JWT (Federation use case) - In this case the client credentials are sent in the form of a JWT assertion, as explained in Using JWTs for Client Authentication.

  Oracle WSM generates the JWT token locally based on client credentials stored in the Oracle WSM credential store. You set the client token policy federated.client.token property to specify whether a JWT token is generated for the client using the values of the oauth2.client.csf.key and keystore.sig.csf.key properties.

• Client credentials are sent in the Basic Auth Header, plus user credentials in the JWT assertion, as explained in Client Credentials Grant - OAuth2.0 Authorization Framework and Using JWTs for Client Authentication.

  You set the client token policy oauth2.client.csf.key property to specify the user name and password to use in the Basic Auth Header.

• Client credentials are sent in the JWT assertion, plus user credentials in the JWT assertion, as explained in Using JWTs for Client Authentication.

How Client Credentials Are Determined in 2-Legged Authorization

The client credential is always included in the request to the OAuth2 server. The federated.client.token property determines whether the JWT is used for the client ID in the client credential, or whether the client ID and password are used for the client credential.

• If federated.client.token is true (the default), then the JWT is used for the client ID in the client credential.

• If federated.client.token is false, then the client ID and password are used for the client credential.

Relationship of User Credentials, Client Credentials, and Subject in 2-Legged Authorization

The subject.precedence property specifies the location from which the subject used to create the JWT token is obtained.

As shown in Table 10-2, if subject.precedence is set to true, the user name to create the JWT token is obtained only from the authenticated subject.

If subject.precedence is set to false, the user name to create the JWT token is obtained only from the csf-key property.

Table 10-2 User Credential, Subject, and Access Token

subject.precedence	csf-key	Authenticated User Subject	Client Credential	User Credential	Access Token Principal/Subject
True (default)	N/A	Available	See How Client Credentials Are Determined in 2-Legged Authorization.	JWT for authenticated end user.	End-user name.
True (default)	N/A	Not available	See How Client Credentials Are Determined in 2-Legged Authorization.	Not included	Client ID
False	Not configured (default)	N/A	See How Client Credentials Are Determined in 2-Legged Authorization.	Not included	N/A
False	Configured	N/A	See How Client Credentials Are Determined in 2-Legged Authorization.	JWT for the identity from the csf-key entry.	The user name from the csf-key/user name is configured.

Prerequisites for Using the Oracle WSM OAuth2 Policies

Perform these steps to configure Mobile and Social OAuth2 for use with Oracle WSM. The steps assume that you are familiar with the configuration information described in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

1. Enable OAuth services, as described in "Enabling OAuth Services".

2. For REST, create an Authorization and Consent Service Plug-ins plug-in profile, as described in Configuring OAuth Plug-Ins.

   Consider the following example:

   • Coarse grain (Recommended)

     • Name: PermissionRESTPlugin

     • Description: Permission Authorization REST Coherence Plug-in

     • Security Handler Class: oracle.security.idaas.oauth.consent.impl.CoherenceAuthorizationUserConsentImpl

   • Fine Grained (with endpoint)

     • Name: PermissionRESTPlugin

     • Description: Permission Authorization REST Callback Plug-in

     • Security Handler Class: oracle.security.idaas.oauth.consent.impl. AuthorizationRESTCallbackImpl

     • Attributes: rest.permission.service.endpoint=endpoint.

3. Create a resource server profile, as described in "Creating an OAuth Resource Server".

   If you created an Authorization and Consent Service Plug-ins in Step2, specify it in the resource server profile.

4. Configure the client profile, as described in "Understanding OAuth Client Profiles Configuration". Use the Create Oauth Web Client page.

   1. Specify a client ID and a client secret. Make a note of these values, you must use them when you later configure the OWSM client policy.

   2. Under Privileges, select Allow Access to All Scopes.

   3. Under Privileges, select the grant types you want to use:

      For 2-legged authorization, select Client Credentials and JWT bearer.

5. Update the OAuth2 server profile configuration, as described in "Editing or Deleting an OAuth Service Profile".

   If you are using JWT Bearer as one of the client credentials:

   • Set the jwt.issuer to www.oracle.com

   • Set jwt.CryptoScheme to RS256

   • Set jwt.trusted.issuer.1 to http://www.oracle.com

   • Set jwt.trusted.issuer.size to 1.

6. Create an oauth2.client.csf.key key of type password in the Oracle WSM credential store, as described in "Adding Keys and User Credentials to the Credential Store".

   Use the client ID from Step 4 as the username and the client secret as the password.

   Note:

   The username and password must represent a valid user in the OPSS identity store.

7. Export the Oracle WSM client certificate and import it into the OAuth2 server truststore to verify the JWT token generated by the Oracle WSM client.

   See "Configuring Keystores for Message Protection" for information on exporting the Oracle WSM client certificate.

8. Export the OAuth2 server certificate and import it into the Oracle WSM trust store on the web service side so that Oracle WSM can verify the signed AT generated by the OAuth2 server.

   The default OAuth Service Profile included in the default domain uses the Java Keystore (JKS) included with Oracle Access Management. See "Configuring OAuth Services" for information on the OAuth2 keystore.

   See "Configuring Keystores for Message Protection" for information on importing the OAuth2 server certificate into the Oracle WSM keystore.

Proceed to Chapter 11, "Configuring Policies" for information on configuring the Oracle WSM OAuth2 policies.

See Chapter 8, "Attaching Policies to Web Services" for information on attaching policies.

Configuring Web Service Clients for Identity Switching

Oracle WSM includes SAML and JWT client policies that enable identity switching. Identity switching means that the policy propagates a different identity than the one based on the authenticated Subject. The identity switch policies are:

• wss11_saml_token_identity_switch_with_message_protection_client_policy – This policy can be used for outbound SOAP requests using mechanisms described in WS-Security 1.1. For more information, see "oracle/wss11_saml_token_identity_switch_with_message_protection_client_policy".

• wss_saml_token_bearer_identity_switch_client_policy – This policy can be attached to any SOAP client endpoint. For more information, see "oracle/wss_saml_token_bearer_identity_switch_client_policy".

• http_jwt_token_identity_switch_client_policy – This policy can be enforced on any HTTP-based, SOAP, or REST client endpoint. For more information, see "oracle/http_jwt_token_identity_switch_client_policy".

You might have a scenario in which your SOA or REST 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 or JWT token in the outbound Web service request. Instead of using the username from the Subject, these policies allow you to set a new user name when sending the SAML or JWT Web service request.

For example, 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.

Compatibility

The identity switch client policies are compatible with the following policies on the Web service:

• wss11_saml_token_identity_switch_with_message_protection_client_policy

  • wss11_saml_token_with_message_protection_service_policy

  • wss11_saml_or_username_token_with_message_protection_service_policy

• wss_saml_token_bearer_identity_switch_client_policy

  • wss_saml_token_bearer_service_policy

  • wss_saml_bearer_or_username_token_service_policy

• http_jwt_token_identity_switch_client_policy

  • http_jwt_token_service_policy

  • multi_token_rest_service_policy

  • wss11_saml_or_username_token_with_message_protection_service_policy

Use Case Example

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 or with a similar client policy over SSL. It communicates with the SOA entry point as user end_user1.

• The SOA entry point is protected by a corresponding type of service policy, such as wss11_username_with_message_protection_service_policy or wss_username_over_ssl_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 an appropriate identity switch policy, such as the wss11_saml_identity_switch_message_protection_client_policy policy for SAML tokens, 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, as described in "Directly from the Message Context". 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 Java EE application (replacing SOA in this scenario with the Java EE application) that establishes the Subject based on an end user but then needs to propagate a different identity. In the case of Java EE, you can set the user name programmatically as follows:

  ((BindingProvider) port).getRequestContext().put(BindingProvider.USERNAME_PROPERTY, config.get(USERNAME));
  

• Use Fusion Middleware Control or WLST to add the WSIdentityPermission permission to the SOA reference binding component, as described in "Set the WSIdentityPermission Permission".

  The identity switch policies require 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 identity switch policies (wss11_saml_token_identity_switch_with_message_protection_client_policy, wss_saml_token_bearer_identity_switch_client_policy, and http_jwt_token_identity_switch_client_policy) disable local optimization (see "Configuring Local Optimization for a Policy" for SOA-to-SOA interactions on the same server.)

How the Username Is Picked Up by an Identity Switch Policy on the Client Side

This section describes the ways in which the username can be picked up for use by an identity switch policy on the client side.

Directly from the Message Context

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. Therefore, 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 Java EE:

Set the BindingProvider.USERNAME_PROPERTY property.

From the csf-key in the Message Context

Set the SecurityConstants.ClientConstants.WSS_CSF_KEY property in the request context.

Overriding the csf-key in the Client Policy

Provide a value for the ClientConstants.WSS_CSF_KEY field for any given identity switch policy. For example, for an HTTP identity switch policy, the csf-key configuration override can be configured by client, as follows:

PropertyFeature csfKey = new PropertyFeature( SecurityConstants.ClientConstants.CO_CSF_KEY, "Oracle WSMtest.credentials");

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.

Using Fusion Middleware Control

To use Fusion Middleware Control to add the oracle.wsm.security.WSIdentityPermission permission to the SOA reference binding component as a System Grant, perform these 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_${jrf.version}/wsm-agent-core.jar in the Codebase field.

   Note:

   When defining the grant details, Oracle recommends that you avoid using product version numbers in the directory or JAR names. This will minimize impact when upgrading to a new release in the future.

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 Java EE client. The action is always assert, as shown in Figure 10-28.

   Figure 10-28 Editing the WSIdentityPermission

   
   Description of ''Figure 10-28 Editing the WSIdentityPermission''
   
   

Using WLST

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_${jrf.version}/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 Java EE client.

• permActions is always "assert".

Propagating Identity Context with Oracle WSM

Identity Context allows organizations to meet growing security threats by using the context-aware policy management and authorization capabilities built into the Oracle Access Management platform. Identity Context secures access to resources using traditional security controls (such as roles and groups) and as dynamic data established during authentication and authorization (such as authentication strength, risk levels, device trust, and so on).

For example, an application could use Identity Context to:

• Disable a particular business function if the user is not authenticated using a strong credential such as smart card.

• Secure access to a transaction based on the identity data supplied by a business partner (by using Identity Federation) with whom the organization does business.

• Request additional authentication credentials if it detects that access is originating from a location known for fraudulent activities.

• Limit the scope of administrative authority if the Administrator's industry certification (as maintained by a third party) has expired.

• Disable certain business functions if it detects that access is originating from an unknown device.

Oracle WSM can propagate the Identity Context from the Web service client to the Web service, and then make it available ("publish it") to other components for authentication and authorization purposes.

The Identity Context is opaque to your Web service client and Web service, and you need not perform any additional coding or processing in your Web service client or Web service to support it once you enable Identity Context propagation for your policies.

Note:

Identity Context propagation is not supported for SOA, WebCenter, and WebLogic (Java EE) Web service applications.

For more information on Identity Context, configuring the Identity Context Service, and using the Identity Context API, see "Using Identity Context" in Administrator's Guide for Oracle Access Management.

Using SAML and JWT Policies to Propagate Identity Context

To use this feature, you must specifically enable Identity Context propagation by using the propagate.identity.context configuration property for both the Web service policy and the Web service client policy. That is, Oracle WSM can propagate the Identity Context only if you specifically allow both the Web service client policy and Web service policy to do so.

Oracle WSM propagates the Identity Context from Web service clients to Web services by using SAML 1.1, SAML 2.0, or JWT assertions. Therefore, only SAML and JWT policies include the propagate.identity.context configuration property.

The following Oracle WSM policies contain the propagate.identity.context configuration property:

• oracle/http_jwt_token_service_policy and oracle/http_jwt_token_client_policy

• oracle/http_jwt_token_over_ssl_service_policy and oracle/http_jwt_token_over_ssl_client_policy

• oracle/http_saml20_token_bearer_service_policy and oracle/http_saml20_token_bearer_client_policy

• oracle/http_saml20_token_bearer_over_ssl_service_policy and oracle/http_saml20_token_bearer_over_ssl_client_policy

• oracle/wss_saml_or_username_token_service_policy

• oracle/wss_saml_or_username_token_over_ssl_service_policy

• oracle/wss_saml_token_bearer_over_ssl_service_policy and oracle/wss_saml_token_bearer_over_ssl_client_policy

• oracle/wss_saml_token_over_ssl_service_policy and oracle/wss_saml_token_over_ssl_client_policy

• oracle/wss_saml20_token_bearer_over_ssl_service_policy and oracle/wss_saml20_token_bearer_over_ssl_client_policy

• oracle/wss_saml20_token_over_ssl_service_policy and oracle/wss_saml20_token_over_ssl_client_policy

• oracle/wss10_saml_token_service_policy and oracle/wss10_saml_token_client_policy

• oracle/wss10_saml_token_with_message_integrity_service_policy and oracle/wss10_saml_token_with_message_integrity_client_policy

• oracle/wss10_saml_token_with_message_protection_service_policy and oracle/wss10_saml_token_with_message_protection_client_policy

• oracle/wss10_saml_token_with_message_protection_ski_basic256_service_policy and oracle/wss10_saml_token_with_message_protection_ski_basic256_client_policy

• oracle/wss10_saml20_token_service_policy and oracle/wss10_saml20_token_client_policy

• oracle/wss10_saml20_token_with_message_protection_service_policy and oracle/wss10_saml20_token_with_message_protection_client_policy

• oracle/wss11_saml_token_with_message_protection_service_policy and oracle/wss11_saml_token_with_message_protection_client_policy

• oracle/wss11_saml_or_username_token_with_message_protection_service_policy

• oracle/wss11_saml20_token_with_message_protection_service_policy and oracle/wss11_saml20_token_with_message_protection_client_policy

Configuring Identity Context Propagation: Main Steps

You can specify a value for propagate.identity.context on the Configurations tab in the policy as described in this section, or override it when you attach the policy.

Note:

For JWT token policies, the Configurations tab is not available. For these policies, you must edit the properties in the Assertion Content XML directly, as described in "Configuring Identity Context Propagation for JWT Token Policies".

For information about overriding the propagate.identity.context property after you attach the policy, see the following topics:

• "Attaching Web Service Policies Permitting Overrides"

• "Attaching Client Policies Permitting Overrides"

• "Overriding Configuration Properties for Globally Attached Policies"

Note:

Oracle recommends that you do not edit the predefined policies so that you will always have a known set of valid policies. You can, however, create new policies (both server and client) using the predefined policies listed in "Using SAML and JWT Policies to Propagate Identity Context". For additional information about creating a new policy, see "Creating a Web Service Policy from an Existing Policy". Once you have created the new policy, you can edit the policy and set the propagate.identity.context property as described below.

By default, the propagate.identity.context configuration property is not set, which is equivalent to False. To use Identity Context propagation, you must specifically set propagate.identity.context to True.

Configuring Identity Context Propagation for SAML Policies

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

2. In the content pane, select WebLogic Domain, then Web Services, and then Policies.

3. Select the SAML policy for which you want to enable Identity Context propagation and click Edit. Remember that you have to enable Identity Context propagation for both the Web service client and Web service policies.

4. On the Edit Policy page, select the Configurations tab.

5. Select propagate.identity.context from the list of properties and click Edit.

6. Change the value field to True and click OK, as shown in Figure 10-29.

   Figure 10-29 Setting the propagate.identity.context Property to True

   
   Description of ''Figure 10-29 Setting the propagate.identity.context Property to True''
   
   

7. Click Save to submit the changes.

8. Repeat Steps 3 through 7 for the corresponding client or service policy, as appropriate.

Configuring Identity Context Propagation for JWT Token Policies

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

2. In the content pane, select WebLogic Domain, then Web Services, and then Policies.

3. Select the JWT policy for which you want to enable Identity Context propagation and click Edit. Remember that you have to enable Identity Context propagation for both the Web service client and Web service policies.

4. On the Edit Policy page, locate the propagate.identity.context property in the Assertion Content section of the page.

5. Change the value field to true as follows:

   <orawsp:Property orawsp:contentType="optional" orawsp:name="propagate.identity.context" orawsp:type="string">
   <orawsp:Value>true</orawsp:Value>
   </orawsp:Property>
   

6. Click Save to submit the changes.

7. Repeat Steps 3 through 6 for the corresponding client or service policy, as appropriate.

Using Kerberos Tokens

Oracle Fusion Middleware 11g Release 1 (11.1.1.9) 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

• oracle/wss11_kerberos_token_with_message_protection_basic128_client_policy

• oracle/wss11_kerberos_token_with_message_protection_basic128_service_policy

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

• oracle/http_spnego_token_client_template

• oracle/http_spnego_token_service_template

• 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 B, "Predefined Policies" and Appendix C, "Predefined Assertion Templates" for more information on these policies and assertions.

Follow the steps described in this section to configure Kerberos for use by the Web service client and Web service.

You can also use Microsoft Active Directory with the Key Distribution Center (KDC). See "Using Active Directory with Kerberos and Message Protection".

• "Initializing and Starting the MIT Kerberos KDC"

• "Creating Principals"

• "Configuring the Web Service Client to Use the Correct KDC"

• "Setting the Service Principal Name In the Web Service Client"

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

• "Configuring the Web Service to Use the Correct KDC"

• "Using the Correct Keytab File in Enterprise Manager"

• "Authenticating the User Corresponding to the Service Principal"

• "Creating a Ticket Cache for the Web Service Client"

• "Configuring Kerberos With SPNEGO Negotiation"

Initializing and Starting the MIT Kerberos KDC

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

root# /usr/kerberos/sbin/krb5_util -r example.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 password
>kadmin.local> addprinc SOAP/myhost.example.com -randkey
>kadmin.local>listprincs # to see the added principals

The Web service principal name (SOAP/myhost.example.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-9. 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

  • default_tgs_enctypes

  • permitted_enctypes

  The order of cipher suites is significant and should comply with the algorithm suite used in the client-side Kerberos policy. For example, if the KDC-supported enc-types are des3-cbc-sha1, des-cbc-md5, des-cbc-crc, arcfour-hmac, then the following order of enc-types entries should be used in client's krb5.conf for the following policies:

  • wss11_kerberos_with_message_protection_client_policy:

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

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

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

  • wss11_kerberos_with_message_protection_basic128_client_policy:

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

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

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

Example 10-9 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 = example.com
dns_lookup_realm = false
dns_lookup_kdc = false
default_tkt_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac
default_tgs_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac
permitted_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac
 
[realms]
example.com =
{kdc = exampleadminserver.com:88  admin_server = exampleadminserver.com:749   
 
 
default_domain = us.example.com  }
[domain_realm]
us.example.com = example.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/[e-mail].

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/[e-mail]);

Configuring the Web Service to Use the Correct KDC

Configure the Web service to authenticate against the correct 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-9. 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.example.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/[e-mail]

• 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/[e-mail]. In this example, a user with the name SOAP/myhost.example.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 these 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 password
   

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: [e-mail], 1 entry found.
   [1]  Service Principal:  krbtgt/[e-mail]
        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.

Configuring Kerberos With SPNEGO Negotiation

SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) is a standard that enables a client and a service to negotiate a method to use for authentication. Because SPNEGO uses HTTP headers to perform the negotiation, it is especially useful in a cross-platform context such as the web, where SOAP and REST endpoints that use HTTP are common.

When Kerberos is used in SPNEGO negotiation, the Kerberos token is wrapped in the HTTP header under the auth-scheme Negotiate. The WWW-Authenticate and Authorization headers are used to communicate the SPNEGO token between the client and the service, as follows:

1. The client requests access to a protected service on the server without any Authorization Header.

2. Since there is no Authorization Header in the request, server responds with the status code 401 (Unauthorized) and WWW-Authenticate: Negotiate.

3. The client uses the user credentials to obtain the Kerberos token and then sends it to the server in the Authorization header of the new request. For example, Authorization: Negotiate a87421000000492aa874209....

4. The server decodes this token by passing it to the acceptSecContext() GSS-API. If the context is not complete (in the case of Mutual Authentication) the server responds with a 401 status code and a WWW-Authenticate header containing the GSS-API data. For example, WWW-Authenticate: Negotiate 74900a2a....

5. The client decodes this data and sends new data back to the server. This cycle will continue until the security context is established.

Oracle WSM provides the following assertion templates to enable clients and services using SPNEGO negotiation to use Kerberos for authentication:

• oracle/http_spnego_token_client_template

• oracle/http_spnego_token_service_template

These assertion templates can be used by policies attached to SOAP or REST endpoints.

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"

• "Create a Keytab File"

• "Set the Service Principal Name"

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 crypto 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 these 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/[e-mail]
   

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"

  • "Requirements of the wss11_saml_token_with_message_protection_service_policy"

  • "How Are Messages Protected Via Symmetric Keys?"

  • "What Keys Must Be in the Keystore?"

  • "Multi-Domain Use Case (Keystore Hardening)"

  • "When to Override the SAML Issuer"

• "Main Steps"

  • "Create a WebLogic Server User"

  • "Create a Java Keystore"

  • "Configure the Web Services Manager Keystore"

  • "Store the Password for the Decryption Key in the Credential Store"

  • "Attach the Policy to Your Web Service"

  • "Attach the Policy to Your Web Service Client"

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"

• "How Are Messages Protected Via Symmetric Keys?"

• "What Keys Must Be in the Keystore?"

• "Multi-Domain Use Case (Keystore Hardening)"

• "When to Override the SAML Issuer"

Requirements of the wss11_saml_token_with_message_protection_service_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-3.

Table 10-3 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.

• If the certificates is not published in the WSDL, 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 approach, 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"

• "Create a Java Keystore"

• "Configure the Web Services Manager Keystore"

• "Store the Password for the Decryption Key in the Credential Store"

• "Attach the Policy to Your Web Service"

• "Attach the Policy to Your Web Service Client"

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

Any configured WebLogic Server authentication provider can then be invoked, including the default Authentication provider.

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 certreq_file -keystore default-keystore.jks
   

Configure the Web Services Manager Keystore

Perform these 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-3.

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 "Adding Keys and User Credentials to the Credential Store". 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"

• "Setting Up Automatic Policy Configuration for STS"

• "Programmatic Configuration Overrides for WS-Trust Client Policies"

• "Supported STS Servers"

• "Available WS-Trust Policies"

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"

• "Typical Token Request and Response"

• "Example WS-Trust Use Case"

• "Token Lifetime"

• "What Token Types Are Exchanged?"

• "Overview of Sender Vouches in WS-Trust"

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 the Oracle WSM Repository. (For details about the repository, see Chapter 17, "Maintaining the Oracle WSM Repository."

  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-30 illustrates the message flows between the requestor, STS, and the Web service.

Figure 10-30 STS Use Case Message Flow

Description of ''Figure 10-30 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-4. 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 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"

• "Setting Up Automatic Policy Configuration: Main Steps"

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

Requirements for Automatic Policy Configuration

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

• Automatic Policy Configuration does not work with JSE clients. If you are using JSE clients in a WS-TRUST scenario, you need to provide all the STS configuration information to the client by attaching both the sts_trust_config_client_policy and the issued token client policy.

• 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 "Configuring Keystores 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 these 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 these 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 DN of the STS to the Trusted STS list, as described in "Defining Trusted Issuers and a Trusted DN List for 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 these steps to configure a Web service client for automatic policy configuration:

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

   The following predefined issued 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-4 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 "Configuring Keystores 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.

   Note:

   You must attach both the sts_trust_config_service_policy policy and an STS issued-token service policy. The policies work as a pair.

2. Attach the issued-token service policy (corresponding to the one attached to the client). There are two predefined issued 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 Oracle WSM 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, in the following situations you must configure it from the Web service client:

• If you did not configure the STS config policy from the Web service, or

• If you are using the SAML sender vouches confirmation method, or

• If you are using a JSE client. Automatic Policy Configuration does not work with JSE clients.

Perform these 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-10. At a minimum, you need to provide the following information:

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

   • Oracle WSM 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 issued 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-10 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 issued token client policy from the client policies listed in Table 10-4. 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 issued 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 issued 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-4.

Table 10-4 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-5 describes a series of sample use cases that show how to override STS properties programmatically.

Table 10-5 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"

• "SAML Holder-of-Key With Message Protection Scenario"

• "SAML Sender Vouches with Message Protection Scenario"

• "SAML Bearer with Message Protection Scenario"

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.

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-6 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 these 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 these 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 Oracle WSM

         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 Oracle WSM -file Oracle WSM.csr -keystore keystore.jks -storepass password

         The request that is generated and written to the Oracle WSM.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 Oracle WSM -file Oracle WSM.cert -keystore keystore.jks -storepass password

         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 password

      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 Oracle WSM.

      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-4, 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 and password you specified under the Credential for User Token section for the OpenSSO STS instance. 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"

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_with_message_protection_client_policy policy to the SOA composite client and override the client configuration properties described in Table 8-4, 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-4. 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 password.

   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_${jrf.version}/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-4, 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 and password Under the Credential for User Token section for the OpenSSO STS instance. 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".

Understanding Fine-Grained Authorization Using Oracle Entitlements Server

Oracle Entitlements Server (OES) is a fine-grained authorization service you can use to secure applications and services across the enterprise. It supports centralized definition of complex application entitlements and the distributed runtime enforcement of those entitlements.  OES allows you to externalize entitlements and thereby remove security decisions from the application.

Oracle WSM OES integration supports advanced authorization use cases using OES and provides the following capabilities:

• You can apply OES authorization to your SOAP-based web services. The OES authorization policy provides a grant or deny for a subject to perform a certain action on a given resource.

• OES can make grant/deny decisions based on context attributes. The context attributes could be based on information from the SOAP request message extracted using XPath statements, or they could be based on HTTP headers.

• Data masking. Oracle WSM OES can mask (with character of your choice) certain information in the response for the web service request.

This section describes how Oracle Entitlements Server (OES) is integrated with Oracle WSM, and how you can use OES together with Oracle WSM for fine-grained authorization.

The following topics are described:

• "Prerequisite OES Reading"

• "OES Integration: The Big Picture"

• "Oracle WSM OES Policies"

• "Resource Mapping and Naming"

• "How Attributes Are Processed"

• "Use of Guard Element"

See "Configuring Fine-Grained Authorization Using Oracle Entitlements Server" for configuration information.

Prerequisite OES Reading

This section references many OES concepts and features. However, the focus of the section is the integration with Oracle WSM, and it does not attempt to provide an in-depth discussion of the OES concepts. If you are not already familiar with OES, you should first refer to the following OES documentation:

Note:

Oracle WSM supports version 11.1.2.2.0 or later of OES.

• Administrator's Guide for Oracle Entitlements Server

• Fine Grained Authorization: Technical Insights for using Oracle Entitlements Server

OES Integration: The Big Picture

When you integrate Oracle WSM and OES, you:

• Attach an Oracle WSM authentication policy to your web service.

• Attach the Oracle WSM oracle/binding_oes_authorization_policy or oracle/component_oes_authorization_policy policy, alone or in combination with the oracle/binding_oes_masking_policy policy as described in this section.

• Use the OES console to create authorization and data masking policies, typically with separate policies for Obligations.

Note:

Oracle WSM does not expose any OES-related configuration; you use the OES console for this purpose.

The Oracle WSM agent checks the authorization of a soap request for a protected web service based on the policies defined in OES. To do this, Oracle WSM passes to OES the authenticated subject, the target resource and requested action, as well as a set of implicit attributes that are always passed in authorization requests.

In your OES policy you can define additional required values based on context attributes from the SOAP request, HTTP headers, message context properties or identity information like the subject, roles, and groups. If you configure OES to require any extra of these context attributes to make a permit/deny decision, Oracle WSM passes them as well.

Specifically, there are two ways to contact OES for the authorization decision: a two-step method and a single-step method. You select which via the use.single.step attribute in oracle/binding_oes_authorization_policy and oracle/component_oes_authorization_policy.

The methods function as follows:

• In the two-step process, you must have previously identified attributes required for fine-grained authorization in the OES console and you now want Oracle WSM to use them.

  Oracle WSM first calls to OES to find out what attributes are needed, gets the attributes from the request payload, and then calls OES a second time to perform the actual authorization using the OES authorization policy. This means that you actually define two OES policies: one to get the needed attributes, and one for the authorization itself.

  You can also use always-passed implicit attributes, plus OES predefined attributes such as time, date, and so forth.

  This method is used for fine-grained authorization, as described in "OES Fine- and Coarse-Grained Authorization".

• In the single-step process, Oracle WSM makes only one call to OES to perform the authorization using the OES authorization policy. The single-step process does not require any previously-identified attributes. As with the two-step process, you can also use the always-passed implicit attributes, plus OES predefined attributes such as time, date, and so forth.

  This method can be used for coarse-grained authorization, as described in "OES Fine- and Coarse-Grained Authorization".

Data Masking

Oracle WSM with OES integration can mask (with asterisks) certain information in the response from the web service, without changing any of the web services code.

Assume you want to ensure that sensitive data is not passed over the wire in response to a web service client request. You use the OES console together with the oracle/binding_oes_masking_policy policy to replace any sensitive data leaving the web service such as a social security number or financial information with asterisks, as shown in Figure 10-31.

Figure 10-31 Masking Sensitive Data

Description of ''Figure 10-31 Masking Sensitive Data''

Masking sensitive data is based on who asked for it, and on other context attributes present in the request.

Consider the following code flow for the web service response shown in Figure 10-31.

Data Masking Code Flow

1. The web service client sends a request.

2. On the inbound request, Oracle WSM enforces the request policy and performs the appropriate authentication and authorization for user Bob Doe.

3. If the request is permitted, Oracle WSM passes the payload to the service provider. The service provider acts on the payload and prepares a response to be sent back to the caller.

4. During response processing, Oracle WSM invokes the oracle/binding_oes_masking_policy policy to determine if there is any sensitive data that needs to be masked.

   Oracle WSM passes the caller's information and any of the user-defined attributes extracted from the response payload.

5. The data masking rules defined in OES take into consideration the client information (through transport attributes), the current subject, resource, action and any response attributes configured on the policy.

6. For each payload attribute, OES responds with Obligations that specify whether the attribute should be passed as-is, or masked.

7. Oracle WSM honors the Obligations returned by OES and masks attributes marked as sensitive by OES.

Obligations

OES supports the XACML concept of Obligations. As described in "Understanding the Policy Model" in Administrator's Guide for Oracle Entitlements Server, when used in a policy, an Obligation may impose an additional requirement for the policy enforcing component.

You configure the Obligation in the OES console. An Obligation is any attribute name/value pair (or any other simple name/value pair) that is returned back to the caller (Oracle WSM). For Oracle WSM OES integration, the Obligation can be an XPath query, HTTP transport header properties, or message context properties.

Another use of Obligations is data masking. In certain applications, such as data security use-cases, a simple yes or no answer may not be sufficient and the OES authorization policy might return an Obligation that specifies what data is to be masked and with what value, as previously shown in Figure 10-31.

OES Fine- and Coarse-Grained Authorization

There are two ways to do authorization with the Oracle WSM OES policies: fine- and coarse-grained authorization. The authorization types are defined as follows:

• Fine (Obligations) — You want to determine access to the resource based on the identity of the consumer, plus specific content from the transport header or the payload specified in Obligations. This is the common use case.

  In this use case, you define attributes in the OES access policy that Oracle WSM will then extract from the request and pass back to OES during authorization. That is, the OES access policy is based on a combination of identity attributes or attributes extracted from the request payload.

  For example, you might have an OES access check of "Allow access if the SOAP Body contains a particular customer ID and if the authenticated user belongs to group TrustedPartners."

  Figure 10-32 shows the fine-grained authorization use case.

  Figure 10-32 Fine-Grained Authorization

  
  Description of ''Figure 10-32 Fine-Grained Authorization''
  
  

  Consider the following code flow for the web service response shown in Figure 10-32.

  1. The web service client sends a SOAP request.

  2. The web service is secured with an Oracle WSM authentication policy and an Oracle WSM OES authorization policy.

  3. Oracle WSM performs authentication and invokes OES for authorization.

  4. Oracle WSM provides the subject, resource, lookup action and all predefined properties to OES.

  5. OES calls the lookup action configured for the protected resource and responds with the configured Obligations (if any) to Oracle WSM. Returned obligations can be returned based on actions; for each action you can define different XPaths, and so forth.

  6. Oracle WSM evaluates the Obligations and executes the XPath on the SOAP/XML payload or finds the property values from the transport header or message context.

  7. Oracle WSM again provides the subject, resource, and action, plus all of the attributes evaluated in Step 6 to OES.

  8. OES determines access based on the subject, resource, action and attributes.

  9. OES responds with permit or deny.

  10. If permit, Oracle WSM passes on the message to the service provider.

  11. If deny, Oracle WSM rejects the request with an authentication failure fault.

• Fine-grained with SAML — You want to determine access to the resource based on the identity of the consumer and on the attributes passed in a SAML token.

  Oracle WSM passes attributes from a SAML assertion. SAML attributes are part of the implicit attributes that are always extracted (if present) and sent automatically. The name of the attribute is the name of the attribute inside the SAML assertion and the value is the list of strings. OES can determine access based on these SAML attributes, as well as the subject, resource and action.

  There are two ways to implement this use case. The first approach is to create an OES custom attribute retriever, as described in "Creating Custom Attribute Retrievers" in Developer's Guide for Oracle Entitlements Server. The second approach is to have OES respond using Obligations with XPaths that point to the SAML attribute values.

  Consider the following code flow for the approach of using an OES custom attribute retriever:

  1. The web service client sends a SAML token with an attribute statement in a SOAP request.

  2. The web service is secured with oracle/wss10_saml_token_service_policy and an Oracle WSM OES authorization policy.

  3. Oracle WSM performs authentication and checks the SAML assertion for an AttributeStatement. If attributes are present, then Oracle WSM extracts them and passes them as attributes while invoking OES for the access request.

  4. Oracle WSM provides the subject, resource, and action, along with any other pre-defined attributes.

  5. OES determines access based on the SAML attributes, subject, resource and action. OES uses a custom attribute retriever to get the SAML attributes.

  6. OES responds with permit or deny.

  7. If permit, Oracle WSM passes on the message to the service provider.

  8. If deny, Oracle WSM rejects the request with an access-denied fault.

• Coarse — You want OES to determine access to the resource based on the identity of the consumer and the web service operation being called. The OES access check is based on the identity attributes, which are limited to user name, group, and role. You can also use the implicit attributes, plus OES predefined attributes such as time, date, and so forth.

  You must set use.single.step to true in the Oracle WSM OES policy to use this mode.

  Figure 10-33 shows the coarse-grained authorization use case. In this use case, assume that you want to secure the service with an authorization policy that determines whether the consumer is allowed to access the service. You want to determine access to the resource based on the identity (authenticated subject) of the consumer and the web service operation being invoked. For example, in Figure 10-33 user Bob Doe might be authorized to get the customer detail but not to delete the customer record.

  Figure 10-33 Coarse-Grained Authorization

  
  Description of ''Figure 10-33 Coarse-Grained Authorization''
  
  

  Consider the following code flow for the web service response shown in Figure 10-33.

  1. The web service client sends a SOAP or XML request.

  2. The web service is secured with an Oracle WSM authentication policy and an Oracle WSM OES policy.

  3. Oracle WSM performs authentication and invokes OES for the access request. Oracle WSM provides the subject, resource and action information to OES.

  4. OES determines access based on the subject, resource and action information.

  5. OES responds with permit or deny.

  6. If permit, Oracle WSM passes on the message to the service provider.

  7. If deny, Oracle WSM rejects the request with an access-denied fault.

Oracle WSM OES Policies

Oracle WSM includes the following OES authorization and masking policies:

• oracle/binding_oes_authorization_policy — This policy does user authorization based on the policy defined in OES. Authorization is based on attributes, the current authenticated subject, and the web service action invoked by the client.

  This policy is used for coarse- or fine-grained authorization on any operation on a web service, as determined by the use.single.step attribute. (See "OES Fine- and Coarse-Grained Authorization".)

  You must use an authentication policy with the Oracle WSM OES authorization policy because the Oracle WSM OES policy requires an authenticated subject.

  This policy also uses the guard element (see orawsp:guard) to define resource, action, and constraint match values. These values allow the assertion execution only if the result of the guard is true. If the accessed resource name and action match, only then is the assertion allowed to execute. By default, resource name and action use the wildcard asterisk "*" and everything is allowed.

  This policy can be attached to any SOAP-based endpoint.

• oracle/component_oes_authorization_policy — This policy does user authorization based on the policy defined in OES.

  This policy is used for coarse- or fine-grained authorization on any operation on a SOA component, as determined by the use.single.step attribute. (See "OES Fine- and Coarse-Grained Authorization".)

  You must use an authentication policy with the Oracle WSM OES authorization policy because the Oracle WSM OES policy requires an authenticated subject. Authorization is based on attributes, the current authenticated subject, and the web service action invoked by the client.

  This policy also uses the guard element (see orawsp:guard) to define resource, action, and constraint match values. These values allow the assertion execution only if the result of the guard is true. If the accessed resource name and action match, only then is the assertion allowed to execute. By default, resource name and action use the wildcard asterisk "*" and everything is allowed.

  This policy is used for fine-grained authorization on a SOA component.

• oracle/binding_oes_masking_policy — This policy does response masking based on the policy defined in OES. You can use an authentication policy with the Oracle WSM OES masking policy. (If there is no subject, the masking decision does not consider the user when making a decision.) Masking is based on attributes, the current authenticated subject, and the web service action invoked by the client.

  This policy uses the guard element (see orawsp:guard) to define resource, action, and constraint match values. These values allow the assertion execution only if the result of the guard is true. If the accessed resource name and action match, only then is the assertion allowed to execute. By default, resource name and action use the wildcard asterisk "*" and everything is allowed.

  This policy is used for fine-grained masking on any operation of a web service.

Resource Mapping and Naming

You must map the OES resource name to the Oracle WSM resource name. When making an authorization call from Oracle WSM, the resource name is passed to OES, and this name must exactly match the one defined in the OES policy.

Table 10-7 shows how to construct the resource string for the OES policy.

If you follow the naming conventions, you do not have to set the resource name in the Oracle WSM policy, Oracle WSM derives it.

Note:

This is the default mapping. If you need to change this mapping, use configuration overrides, as described in "Configuration Properties and Overrides".

Table 10-7 Determining Resource String

OES Field	Value to Use
Application	Deployed Application Name. For SOA, the composite name is used as the application name.
Resource Type	Fixed, based on subject type. For SOAP must be WS_SERVICE. For SOA component, must be COMPONENT.
Resource Name	For SOAP and SOA reference, must be of the form web-service-name/port/web service operation. For SOA component, must be of the form SOA component name/web service operation.
Action	By default, one of: request.lookup (Obligation policy for authorization.) response.lookup (Obligation policy for masking.) mask (Real masking policy.) authorize (Real authorization policy.)

Example of OES Policies

Assume that a SOA composite (soa1) has two service bindings (Serv1 and Serv2).

• Serv1 has port11

• Serv2 has port21

• port11 has oper11, oper12

• port21 has oper21

In OES, the application, resource type, resource name and actions should be defined as shown in Table 10-8.

Table 10-8 Resource String Example

OES Field	Value to Use
Application	soa1
Resource Type	WS_SERVICE
Resource Name	Serv1/port11/oper11, Serv1/port11/oper12, Serv2/port21/oper21
Action	One of: request.lookup (Obligation policy for authorization.) response.lookup (Obligation policy for masking.) mask (Real masking policy.) authorize (Real authorization policy.)

The authorization and masking OES policies based on Table 10-8 are as follows:

• Returning Obligations

  • One policy that returns obligations for any operation:

    GRANT (action: request.lookup; Resource: WS_SERVICE/Serv1/Port11, WS_SERVICE/Serv2/Port21; User: any) Obligation: XPath11
    

  • Multiple policies for returning operation-specific Obligations:

    GRANT (action: request.lookup; Resource: WS_SERVICE/Serv1/Port11/oper11;User:any) Obligation: XPath11
    GRANT (action: request.lookup; Resource: WS_SERVICE/Serv1/Port11/oper12;User:any) Obligation: XPath12
    GRANT (action: request.lookup; Resource: WS_SERVICE/Serv2/Port21/oper21;User:any) Obligation: XPath21
    

• Real authorization

  • One policy performing same authorization regardless of resource and action:

    GRANT/DENY (action: authorize; Resource: WS_SERVICE/Serv1/Port11, WS_SERVICE/Serv2/Port21; User:<actual user>)
    

  • Multiple policies for performing operation-specific authorization:

    GRANT/DENY (action: authorize; Resource: WS_SERVICE/Serv1/Port11/oper11;User:<actual user>)
    GRANT/DENY (action: authorize; Resource: WS_SERVICE/Serv1/Port11/oper12;User:<actual user>)
    

• Returning masking Obligations:

  GRANT (action: response.lookup; Resource: WS_SERVICE/Serv1/Port11/oper11;User:any) Obligation: XPath11
  GRANT (action: response.lookup; Resource: WS_SERVICE/Serv1/Port11/oper12;User:any) Obligation: XPath12
  GRANT (action: response.lookup; Resource: WS_SERVICE/Serv2/Port21/oper21;User:any) Obligation: XPath21
  

• Real masking:

  GRANT/DENY (action: mask; Resource: WS_SERVICE/Serv1/Port11/oper11;User:<actual user>)
  GRANT/DENY (action: mask; Resource: WS_SERVICE/Serv2/Port21/oper21;User:<actual user>)
  

How Attributes Are Processed

As the OES administrator, you define attributes in the OES policy as Obligations, which Oracle WSM then extracts from the payload and sends back to OES.

Specifically, OES allows you to create an Obligation in the OES console and provide multiple attribute name/value pairs. For example, you can create an Obligation called Employee and have multiple attributes such as {Name=John, Age=21, SSN=123456}.

The attributes can be obtained from an XPath, an HTTP header, a message context, and constants (name/value). These attributes must follow a specific naming convention, as described in Table 10-9.

Table 10-9 Attribute Types Supported for OES Policies

Attribute Type	Description	Required Format
XPath query	You provide the attribute name and value as an XPath query in the OES console. Oracle WSM runs this XPath query on the SOAP message and uses the value as the attribute value. The XPath query can result in a single value or multiple values. In case of multiple values, a list of strings is used to pass all values. If any XPath query fails to evaluate on the SOAP message, it is ignored and a warning message is generated in the logs. Oracle WSM continues to evaluate next XPath query.	Use XPath (case insensitive) as the Obligation name to signify that it is an XPath. The Obligation should also return all the namespaces being used in the XPath query. All namespaces should be returned with an attribute name of NAMESPACE (case insensitive) and the value should be the comma separated namespaces. For example, if you want to use the SAML issuer name for authorization, use the following Obligation format: Name = XPath, values = {saml_issuer=.//saml:Assertion/@Issuer, CC_Name=ns1:sayHello/arg0, NAMESPACE=ns1=http://...,wsse=http://...} In the authorization phase, Oracle WSM passes the attribute name saml_issuer and the value is the result of the XPath query. The default namespace has to be mapped to a prefix. (The prefix name must be unique within the application.) For example: saml=urn:oasis:names:tc:SAML:1.0:assertion,ns0=http://wsm.oracle.com,myPrefix=http://default_namespace Namespace definitions are separated using a comma.
HTTP Header	You provide HTTP header names in the OES console. The value is fetched from the current request HTTP header.	To get HTTP Header properties, define an Obligation with the name "HTTPHeader" (case insensitive). It can have multiple HTTP header names. The name of the attribute should be the name to which you want to assign the value; the value should be the actual HTTP header name. For example: Name = HTTPHeader, values = {AuthHeader=Authorization} In the authorization phase, Oracle WSM retrieves the HTTP header and assigns it to the name given in the attribute name.
Message Context Properties	You provide message context property names in the OES console. The value is fetched from the current message context.	Define an Obligation with the name "MessageContext" (case insensitive). It can have multiple message context property names. The name of the attribute should be the name to which you want to assign a value; the value should be the actual message context property name. For example: Name = MessageContext, values = {authMethod=oracle.wsm.internal.authentication.method, endpoint=oracle.j2ee.ws.runtime.endpoint-url} In the authorization phase, Oracle WSM retrieves the message context property and assigns it to the name given in the attribute name. For example, the previous example might resolve to: authMethod=USERNAME_TOKEN & endpoint=http://localhost:7001/myService
Constants	Constants are user-defined attributes that Oracle WSM does not understand and passes "as is."	An Obligation named Employee is an example of a constant.
Implicit	Oracle WSM passes implicit attributes in all authorization requests. You do not perform any configuration to pass them. The following implicit attributes are always passed: serviceURL — The URL of the web service. serviceNS — The namespace of the web service. clientIP — The client's IP address. processingStage — Whether this is a request or response. Possible values are request, response, and fault. isRequestOverSSL — Boolean. True if the request is over one- or two-way SSL.) authenticationMethod — The authentication method. Possible values are SAML_SV, KERBEROS, SAML_HOK, X509_TOKEN_AUTHENTICATION, SAML_BEARER, and USERNAME_TOKEN requestOrigin — Where the request came from, internal or external, as determined from the VIRTUAL_HOST_TYPE transport header. clientSigningCertDN — Either the X509 signing cert or the client cert in two-way SSL. operationName — The operation name invoked by the user. samlIssuer — The SAML issuer extracted from the SAML assertion. type — The type of the request to OES. Values can be request.lookup, response.lookup, authorize or mask. This attribute is always sent.	None required, they are always passed. You would typically use these constants in a Condition in the OES console.

Use of Guard Element

The Oracle WSM OES authorization policies uses the orawsp:guard element. It allows the assertion to execute only if the result of the guard is true. That is, if the accessed resource name and action match, only then is the OES authorization engine called.

By default, resource name and action use the wildcard asterisk "*" and everything is allowed. However, if you set a specific resource name, action, and constraint, that requirement must be satisfied before any of the configuration properties and any OES policies are considered.

The resource naming convention for guard differs from the OES standard naming convention. The resource name for the guard must be in the form <Webservice_NS>/<SERVICE_NAME>.