This use case leads you though the steps of adding a SAML policy to a Web service and client. In this use, case you create a WebLogic Server user, create and configure a Java keystore, store the password, and attach a SAML policy to a Web service and service client.
This chapter contains the following sections:
Assume that you have a Web service client that you want to protect with the SAML token with message protection client policy (wss11_saml_token_with_message_protection_client_policy), and a corresponding Web service that you want to protect with the SAML token with message protection service policy (wss11_saml_token_with_message_protection_service_policy).
This section steps through the procedure for using these two policies.
The following topics are described:
This section describes what you need to know to configure this SAML message protection use case. The following topics are described:
The 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.
This policy uses symmetric key technology. Symmetric key cryptography relies on a single, shared secret key, as follows:
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.
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 OWSM agent does the following:
Generates the shared symmetric key and uses it to both sign and encrypt the request message.
Uses its own private key to "endorse" the signature of the request message.
Uses the Web service's public key to encrypt the symmetric key.
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:
Uses its private key to decrypt the symmetric key.
Uses the symmetric key to decrypt the request message and to verify its signature.
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:
Uses the same client-generated symmetric key sent along with the request to sign the response message.
Uses the same client-generated symmetric key to encrypt the response message.
When the OWSM agent receives the response message, it does the following:
Uses the symmetric key it generated initially to decrypt the response message.
Uses the symmetric key it generated initially to verify signature of the response message.
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.
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 13-1.
Table 13-1 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 the Service Identity Certificate Extensions". 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.
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.
This section describes the steps you follow to configure the SAML message protection use case. The following topics are described:
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 SAML2 Login Modules Using Fusion Middleware Control" 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.
You use the WebLogic Server Administration Console to add the user to the identity store, as described in the Oracle WebLogic Server Administration Console Online Help.
The steps are repeated here for ease of use.
To create a user in the WebLogic Server Administration Console:
In the left pane select Security Realms.
On the Summary of Security Realms page select the name of the realm (for example, myrealm).
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.
Click New.
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: <>, #, |, &, ?, ( ), { }
(Optional) In the Description field, enter a description. The description might be the user's full name.
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.
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.
Re-enter the password for the user in the Confirm Password field.
Click OK to save your changes.
The user name appears in the User table.
For demonstration purposes, this use case uses the JKS 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/7/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.
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.
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
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
After you have created the keystore, you need to configure OWSM at the domain level to use the JKS keystore. You can do so using Fusion Middleware Control or WLST commands.
Refer to the following sections for more information:
In this use case, orakey is the alias for both the signature and encryption keys. This use case keystore name is default-keystore.jks.
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 a copy of wss11_saml_token_with_message_protection_service_policy to your Web service as described in "Attaching Policies Directly to a Single Subject Using Fusion Middleware Control".
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 "Overview of Policy Configuration 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 a copy of wss11_saml_token_with_message_protection_client_policy to your Web service client, as described in "Attaching Policies Directly to Web Service Clients Using Fusion Middleware Control".
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 the Service Identity Certificate Extensions". 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.