This chapter describes how to secure inbound SOAP requests using SAML message protection.
| Use Case | Secure inbound SOAP requests to:
|
| Solution | Attach an Oracle Web Services Manager (OWSM) SAML policy that is in accordance with WS-Security 1.1 to the web service and client, and configure the required keys and keystores. |
| Components |
|
| Required Documentation | To complete this use case, see the following documentation resources:
|
This chapter contains the following sections:
This use case demonstrates the steps required to:
Attach the appropriate OWSM security policies to enforce message-level protection using SAML-based authentication for inbound SOAP requests.
Specifically, you attach the following policies to the client and service, respectively:
wss11_saml_token_with_message_protection_client_policy
wss11_saml_token_with_message_protection_service_policy
Configure the required keys and keystores.
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. 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. For more information about supported algorithm suites, see "Supported Algorithm Suites" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
The following sections provide additional background about the SAML message protection use case:
For more information, see "Understanding Keys and Certificates" and "wss11" in Understanding Oracle Web Services Manager.
The SAML security policies in this use case use 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 web 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 performs the following steps:
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 receives the request, it performs the following steps:
Decrypts the symmetric key using its private key.
Decrypts the request message and to verify its signature using the symmetric key.
Verifies the endorsement signature using the client's public key in the request message.
To send the response back to the client, the web service performs the following steps:
Signs the response message using the same client-generated symmetric key sent along with the request.
Encrypts the response message using the same client-generated symmetric key.
When the OWSM agent receives the response message, it performs the following steps:
Decrypts the response messages using the symmetric key it generated initially.
Verifies the signature of the response messages using the symmetric key it generated initially.
In this use case, the client and web service are in the same domain with access to the same keystore. As a result, they can share the same private/public key pair.
Specifically, 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.
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 requirements in a multiple-domain use case, described in Table 2-1.
Table 2-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" in Securing Web Services and Managing Policies with Oracle Web Services Manager. In this case, 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. For more information, see "Adding an Additional SAML Assertion Issuer Name" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
This use case describes the following tasks to implement SAML message protection:
Prior to implementing this use case, ensure you
You need to ensure that the user in the SAML token exists in the WebLogic Server identity store. If it does not, you must create it. Add a user to the identity store using the WebLogic Server Administration Console, as described in "Create users" in Oracle WebLogic Server Administration Console Online Help.
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 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. For more information, see "Configuring the SAML and SAML2 Login Modules Using Fusion Middleware Control" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
Any configured WebLogic Server authentication provider can then be invoked, including the default Authentication provider.
Create a keystore and load the private key and trusted CA certificates.
The following procedure create a and manages the Java keystore using the keytool utility. This use case uses the JKS keystore. For the complete procedure, see "Generating Private Keys and Creating the Java Keystore" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
Note:
You specify an alias when you perform either of the following tasks:Add an entity to the keystore using the -genkey command to generate a key pair (public and private key).
Add a certificate or certificate chain to the list of trusted certificates using the -import command.
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 in the default-keystore.jks keystore an RSA key with RSA-SHA1 as the signature algorithm and alias name orakey. You can specify any alias name; you do not need to set the alias name to orakey.
keytool -genkey -alias orakey -keyalg "RSA" -sigalg "SHA1withRSA" -dname "CN=test, C=US" -keystore default-keystore.jks
The keytool utility prompts for the required key and keystore passwords. You need these passwords later.
Generate a certificate request to the certificate authority (CA).
Use the -certreq command to generate the request. The CA will return a certificate or a certificate chain.
The following command generates a certificate request for the orakey alias.
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
Configure the OWSM keystore. For the complete procedure, see "Configuring the OWSM Keystore" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
Store the password for the decryption key in the credential store. Use keystore.enc.csf.key as the key name. For the complete procedure, see "Adding Keys and User Credentials to the Credential Store" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
Attach wss11_saml_token_with_message_protection_service_policy to your web service and configure the policy assertion for message signing and message encryption. For the complete procedure, see "Attaching Policies" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
By default, the policy signs and encrypts the entire body for the request and response. You have the option to specify individual body elements that you want to sign and encrypt. Additionally, you can specify header elements that you want to sign and encrypt. You can configure the messaging signing and encryption as desired; however, it must match the client policy settings.
For more information about configuring the policy, see "oracle/wss11_saml_token_with_message_protection_service_policy" in Securing Web Services and Managing Policies with Oracle Web Services Manager
Attach wss11_saml_token_with_message_protection_client_policy to your web service client and configure the policy assertion for message signing, message encryption, or both. For the complete procedure, see "Attaching Policies" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
By default, the policy signs and encrypts the entire body for the request and response. You have the option to specify individual body elements that you want to sign and encrypt. Additionally, you can specify header elements that you want to sign and encrypt. You can configure the messaging signing and encryption as desired; however, it must match the service policy settings.
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. For more information about overriding the saml.issuser.name property, see "When to Override the SAML Issuer".
For more information about configuring the policy, see "oracle/wss11_saml_token_with_message_protection_client_policy" in Securing Web Services and Managing Policies with Oracle Web Services Manager