| Oracle® Fusion Middleware Security and Administrator's Guide for Web Services 11g Release 1 (11.1.1.5) Part Number B32511-05 |
|
|
PDF · Mobi · ePub |
| Oracle® Fusion Middleware Security and Administrator's Guide for Web Services 11g Release 1 (11.1.1.5) Part Number B32511-05 |
|
|
PDF · Mobi · ePub |
This chapter describes how to set up your Fusion Middleware Control and WebLogic Server environments for security policies.
This chapter includes the following sections:
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.
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.
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".The types of message protection policies and how they work are described in the following sections.
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.
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:
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.
When the service receives the message, it decrypts the encrypted key first, and then decrypts and verifies the whole message.
The Web service then uses the same symmetric key to encrypt and sign the response that it sends back to the client.
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.
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.
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.
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.
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.
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 a Trusted Distinguished Name List for SAML Signing Certificates".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.
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:
J2EE 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 Concepts Guide for Oracle Infrastructure Web Services.
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 welcome1 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 welcome1 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 a Trusted Distinguished Name List for SAML 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.
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:
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.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
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.
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 welcome1 -keystore default-keystore.jks -storepass welcome1 -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 welcome1 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 welcome1 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
Optionally, import trusted certificates into the keystore as described in "Obtaining a Trusted Certificate and Importing it into the Keystore"
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
*******************************************
*******************************************
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".
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:
In the Navigator pane, expand WebLogic Domain to show the domain for which you need to configure the keystore. Select the domain.
From the WebLogic Domain menu, select Security then Security Provider Configuration, as shown in Figure 10-1.
Figure 10-1 WebLogic Domain Security Provider Configuration Menu
The Security Provider Configuration page is displayed, as shown in Figure 10-2.
Figure 10-2 Security Provider Configuration Page
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.
Figure 10-3 Web Services Manager Keystore Configuration
In the Keystore Type drop-down, select Java Key Store (JKS), if it is not already selected.
Note:
Hardware security modules (HSM) are also certified to operate with Oracle Advanced Security. For more information, see "Using Hardware Security Modules With Oracle WSM"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 welcome1.
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 welcome1.
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 welcome1.
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.
Click OK to submit the changes.
Note that all fields on this page require a server restart to take effect.
Note:
The Oracle WSM agent caches the keystore name and object. If you make subsequent changes to the contents of the keystore or to its name, you must restart the server.Follow these steps to configure the credential store to access the Oracle WSM keystore using WLST commands.
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.
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.
Start Oracle WebLogic Server.
For more information, see "Start and stop servers" in the Oracle WebLogic Server Administration Console Online Help.
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.oracle.com:7001 using the username/password credentials weblogic/welcome1:
connect("weblogic","welcome1","t3://myAdminServer.oracle.com:7001")
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="owsm", password="welcome1", 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 welcome1).
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="welcome1", 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 welcome1.).
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="welcome1", 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 welcome1.).
View the details about a key in the credential store using the listCred command as shown in the following example:
listCred(map="oracle.wsm.security", key="enc-csf-key")
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:
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 welcome1 -keystore default-keystore.jks -storepass welcome1 -validity 3600
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
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.
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
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
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.
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.
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 thebasic.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 welcome1 -keystore default-keystore.jks -storepass welcome1 -validity 3600 keytool -genkeypair -keyalg RSA -alias ServiceB -keypass welcome3 -keystore default-keystore.jks -storepass welcome1 -validity 3600
For more information about the keystore, see "Generating Private Keys and Creating the Java Keystore".
Follow these steps in Fusion Middleware Control to add keys and certificates to the credential store:
In the Navigator pane, expand WebLogic Domain to show the domain for which you need to configure the keystore. Select the domain.
From the WebLogic Domain menu, select Security then Credentials.
The Credentials page is displayed, as shown in Figure 10-5.
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.
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
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.
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.
From the Select Map menu, select the map name oracle.wsm.security if it is not already selected.
In the Key field, enter csfServiceA to create a key-value pair to access the key store.
From the Type menu, select Password.
In the User Name field, enter the alias name that you specified for the private key in the keystore, for example ServiceA.
In the Password and Confirm Password fields, enter the password that you specified for the alias in the keystore, for example welcome1.
In the Description field, enter a description of for the entry, for example, Key for ServiceA.
Click OK.
Click Create Key again and provide the values for any additional keystore aliases, such as csfServiceB for the ServiceB alias.
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:
From the Select Map menu, select the map name oracle.wsm.security if it is not already selected.
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.
From the Type menu, select Password.
In the User Name field, enter a valid username that exists in the OPSS identity store, for example AppID.
In the Password and Confirm Password fields, enter a valid password for the user, for example AppPWord%.
In the Description field, enter a description of for the entry, for example, Username and Password for basic.credential key.
Click OK.
Restart the server.
Follow these steps to add additional keys and user credentials to the credential store using WLST commands.
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.
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.
Start Oracle WebLogic Server.
For more information, see "Start and stop servers" in the Oracle WebLogic Server Administration Console Online Help.
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.oracle.com:7001 using the username/password credentials weblogic/welcome1:
connect("weblogic","welcome1","t3://myAdminServer.oracle.com:7001")
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="welcome1", desc="Key for ServiceA")
Repeat step 5 to create an entry for any additional aliases, for example csfServiceB, for the ServiceB alias.
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="AppPWord%", desc="Key for ServiceA")
View the details about a key in the credential store using the listCred command as shown in the following example:
listCred(map="oracle.wsm.security", key="csfServiceA")
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.
Figure 10-8 Oracle WSM 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.
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.
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.
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
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:
Obtain digital certificates, private keys, and trusted CA certificates from Sun Microsystem's keytool utility, or a reputable vendor such as Entrust or Verisign, and include them in the keystore.
To get the certificate, you must create a Certificate Request and submit it to the CA. The CA will authenticate the certificate requestor and create a digital certificate based on the request.
The PEM (Privacy Enhanced Mail) format is the preferred format for private keys, digital certificates, and trusted certificate authorities (CAs).
If you use the keytool utility, the default key pair generation algorithm is Digital Signature Algorithm (DSA). WebLogic Server does not support DSA. Specify another key pair generation and signature algorithm such as RSA when using WebLogic Server. For more information about Sun's keytool utility, see the keytool-Key and Certificate Management Tool description at http://download.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html.
You can also use the digital certificates, private keys, and trusted CA certificates provided by the WebLogic Server kit. The demonstration digital certificates, private keys, and trusted CA certificates should be used only in a development environment.
Create one keystore for identity and one for trust. The preferred keystore format is JKS (Java KeyStore).
Load the private keys and trusted CAs into the keystores.
In the left pane of the Console, expand Environment and select Servers.
Click the name of the server for which you want to configure the identity and trust keystores.
Select Configuration, and then Keystores.
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.
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.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.
The changes are automatically activated.
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:
In the left pane of the WebLogic Server Administration Console, expand Environment and select Servers.
Click the name of the server for which you want to configure SSL.
Select Configuration, and then the SSL page, and choose the location of identity (certificate and private key) and trust (trusted CAs) for WebLogic Server.
Set SSL attributes for the private key alias and password.
At the bottom of the page, click Advanced.
Set Hostname Verification to None.
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.
Set the Two Way Client Cert Behavior control to Client Certs Not Requested.
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.
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:
In the left pane of the WebLogic Server Administration Console, expand Environment and select Servers.
Click the name of the server for which you want to configure SSL.
Select Configuration, and then the SSL page, and choose the location of identity (certificate and private key) and trust (trusted CAs) for WebLogic Server.
Set SSL attributes for the private key alias and password.
At the bottom of the page, click Advanced.
Set Hostname Verification to None.
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.
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.
Set the Two Way Client Cert Behavior control to Client Certs Requested and Enforced.
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.
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:
Ensure that WebLogic Server obtains a digital certificate that the client automatically trusts, because it has been issued by a trusted certificate authority.
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:
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.
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.
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.
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:
Ensure that the client application obtains a digital certificate that WebLogic Server automatically trusts, because it has been issued by a trusted certificate authority.
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:
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.
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.
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.
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
"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
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:
Configure the Oracle HTTP Server as follows:
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>
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
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.
Restart Oracle HTTP Server.
For more information, see "Configuring SSL in Oracle Fusion Middleware" in Oracle Fusion Middleware Administrator's Guide.
Create a wallet as described at "Managing Keystores, Wallets, and Certificates" in Oracle Fusion Middleware Administrator's Guide and replace the default wallet. The default wallet is located in the ORACLE_INSTANCE/config/OHS/<ohs_name>/keystores/default directory. See Example 10-2 for sample commands for creating a wallet.
Example 10-2 Sample Commands for One-Way SSL
./orapki wallet create -wallet <wallet_location> -pwd welcome1 -auto_login ./orapki wallet display -wallet <wallet_location> -pwd welcome1 ./orapki cert display -cert <wallet_location>/ohs.crt ./orapki wallet add -wallet <wallet_location> -keysize 512 -dn "CN=<host_name>,OU=st,O=owsm,L=N,ST=delhi,C=IN" -self_signed -validity 700 -serial_num 20 -cert <wallet_location>/ohs.crt -user_cert -pwd welcome1 ./orapki wallet display -wallet <wallet_location> -pwd welcome1 JAVA_HOME/bin/keytool -import -trustcacerts -file ohs.crt -alias sslcert -keystore client_keystore.jks -storepass welcome1
In the Oracle WebLogic Administration Console, perform the following:
Navigate to the Servers page in the Environment tab.
Click Adminserver and in Configuration, select General.
In the Advanced section, check the following: WebLogic Plug-In Enabled, and Client Cert Proxy Enabled.
Save the changes.
Set the same parameters for the SOA server.
For more information, see "Server: Configuration: General" in the Oracle WebLogic Server Administration Console Help.
To modify the client to use one-way (server authentication mode), create a JSE client from the Web service using JDeveloper. Modify the parameters and properties as described in Example 10-3.
Example 10-3 JSE Client Using SSL
public static void main(String [] args)
{
class1Service = new Class1Service();
SecurityPolicyFeature[] securityFeatures =
new SecurityPolicyFeature[] { new SecurityPolicyFeature("oracle/wss_
saml_token_over_ssl_client_policy") };
Class1 class1 = class1Service.getClass1Port(securityFeatures);
((BindingProvider) class1).getRequestContext().put(BindingProvider.ENDPOINT_
ADDRESS_PROPERTY,
"https://<host>:4443/myWlsService/Class1Port");
((BindingProvider) class1).getRequestContext().put(BindingProvider.USERNAME_
PROPERTY, "weblogic");
System.setProperty("javax.net.ssl.trustStore","D:\\OWSM_
QA\\11g\\PS2\\OHS\\wallet\\client_keystore.jks");
System.setProperty("javax.net.ssl.trustStorePassword","welcome1");
System.setProperty("javax.net.ssl.trustStoreType","JKS");
System.setProperty("weblogic.security.SSL.ignoreHostnameVerification" ,
"true");
System.setProperty("java.protocol.handler.pkgs",
"com.sun.net.ssl.internal.www.protocol");
System.setProperty("javax.net.debug","all");
System.out.println("Call to the SSL service...");
String response1 = class1.sayHello("test");
System.out.println("Response = " + response1);
}
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:
Configure the Oracle HTTP Server as follows:
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>
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.
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.
Restart Oracle HTTP Server.
For more information, see "Configuring SSL in Oracle Fusion Middleware" in Oracle Fusion Middleware Administrator's Guide.
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.
In the Oracle WebLogic Administration Console, perform the following:
Navigate to the Servers page in the Environment tab.
Click Adminserver and in Configuration, select General.
In the Advanced section, check the following: WebLogic Plug-In Enabled, and Client Cert Proxy Enabled.
Save the changes.
Set the same parameters for the SOA server.
For more information, see "Server: Configuration: General" in the Oracle WebLogic Server Administration Console Help.
To modify the client to use two-way (mutual authentication mode) SSL, create a JSE client from the Web service using JDeveloper. Modify the parameters and properties as described in Example 10-6.
Example 10-6 JSE Client Using SSL
public static void main(String [] args)
{
class1Service = new Class1Service();
SecurityPolicyFeature[] securityFeatures =
new SecurityPolicyFeature[] { new SecurityPolicyFeature("oracle/wss_
username_token_over_ssl_client_policy") };
Class1 class1 = class1Service.getClass1Port(securityFeatures);
((BindingProvider) class1).getRequestContext().put(BindingProvider.ENDPOINT_
ADDRESS_PROPERTY,
"https://<host>:4443/myWlsService/Class1Port");
((BindingProvider) class1).getRequestContext().put(BindingProvider.USERNAME_
PROPERTY, "weblogic");
((BindingProvider) class1).getRequestContext().put(BindingProvider.PASSWORD_
PROPERTY, "welcome1");
System.setProperty("javax.net.ssl.trustStore","D:\\OWSM_
QA\\11g\\PS2\\OHS\\wallet\\twowaykeystore.jks");
System.setProperty("javax.net.ssl.trustStorePassword","welcome1");
System.setProperty("javax.net.ssl.trustStoreType","JKS");
System.setProperty("javax.net.ssl.keyStore","D:\\OWSM_QA\\11g\\PS2\\OHS\\wallet\\twowaykeystore.jks");
System.setProperty("javax.net.ssl.keyStorePassword","welcome1");
System.setProperty("javax.net.ssl.keyStoreType","JKS");
System.setProperty("weblogic.security.SSL.ignoreHostnameVerification" ,
"true");
System.setProperty("java.protocol.handler.pkgs",
"com.sun.net.ssl.internal.www.protocol");
System.setProperty("javax.net.debug","all");
System.out.println("Call to the SSL service...");
String response1 = class1.sayHello("test");
System.out.println("Response = " + response1);
}
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.
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:
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
After installing the Luna SA client, you need to configure the JRE that will be used by the Oracle WSM setup.
Copy the following JAR files from the /usr/lunasa/jsp/lib directory to the $JAVA_HOME/jre/lib/ext directory:
LunaJCASP.jar
LunaJCESP.jar
Copy the libLunaAPI.so file to the java.library.path.
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.
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.
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>; }
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.
To log out of the Luna SA server, enter:
salogin -c -s <slot number> -i <AppIdMajor>:<AppIdMinor>
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.
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:
In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure the keystore. Select the domain.
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, and then click Configure.
The Web Services Manager Keystore Configuration page is displayed, as shown in Figure 10-9.
Figure 10-9 Web Services Manager Keystore Configuration Page
In the Keystore Type drop-down, select Hardware Security Module (HSM).
After the Keystore Configuration page refreshes, enter Luna in the HSM Provider Type field, as shown is Figure 10-10.
Figure 10-10 Web Services Manager Keystore Configuration Page (Refreshed)
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.
Click OK to submit the changes.
Restart Fusion Middleware Control.
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 thekeystore.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.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.
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:
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.
From the navigation pane, expand WebLogic Domain.
Select the domain in which you want to enable or disable service identity certificate extension and hostname verification.
Using Fusion Middleware Control, click WebLogic Domain.
Select Web Services, and then select Platform Policy Configuration.
Select the Identity Extension tab.
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.
To delete an existing property, select it and then click Delete.
Click Apply to apply the property updates.
Note:
By default, if the certificate is published in the WSDL, then the client override property value forkeystore.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");
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");
This section introduces WebLogic Server security features that are described in detail in Securing Oracle WebLogic Server and in the Oracle WebLogic Server Administration Console Help. This section provides only a brief introduction to the security features, and concentrates on how they relate to configuring policies.
The security policies that you use determine what types of security providers you must configure in WebLogic Server. You can categorize the policies based on their token type:
Policies that use the username token require an authentication provider that can handle the NameCallback and PasswordCallback. The WebLogic Default Authentication provider is one such provider.
The following policies fall into this category:
oracle/wss_http_token_service_policy
oracle/wss_username_token_service_policy
oracle/wss_username_token_over_ssl_service_policy
oracle/wss11_username_token_with_message_protection_service_policy
oracle/wss10_username_token_with_message_protection_service_policy
oracle/wss10_username_token_with_message_protection_ski_basic256_service_policy
Policies that use the X.509 and SAML tokens require an authentication provider (or Identity Assertion provider) that can handle perimeter authentication via the NameCallback. The Web service run-time process the tokens on your behalf to determine the username, and then invokes the Oracle Platform Security Service (OPSS) layer to complete the authentication. In this way, the security providers do not handle the X.509 or SAML tokens directly, and the WebLogic providers do not have to support these token types.
The following policies fall into this category:
oracle/wss10_x509_token_with_message_protection_service_policy
oracle/wss10_saml_token_service_policy
oracle/wss10_saml_token_with_message_protection_service_policy
oracle/wss_saml_token_over_ssl
oracle/wss_saml_token_bearer_over_ssl_service_policy
oracle/wss10_saml_hok_token_with_message_protection_service_policy
oracle/wss11_saml_token_with_message_protection_service_policy
oracle/wss10_saml_token_with_message_protection_ski_basic256_service_policy
oracle/wss11_x509_token_with_message_protection_service_policy
You can use any WebLogic Authentication provider that can validate the credentials in the NameCallback and PasswordCallback callbacks, or the NameCallback alone, as appropriate. This means that you can use the WebLogic Default Authentication provider and authenticate the user against the embedded LDAP data store if you so choose, or the Default Identity Asserter, and so forth. See "Configure Authentication and Identity Assertion Providers" in the Oracle WebLogic Server Administration Console Help for information on how to do this.
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:
In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure the login module. Select the domain.
Using Fusion Middleware Control, click WebLogic Domain, then Security, and then Security Provider Configuration.
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-11is displayed.
Figure 10-11 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
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".
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:
|
|
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 |
|
|
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. |
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 to Configure Oracle Platform Security Services (OPSS) for SAML Policies"
"Configuring SAML Web Service Clients for Identity Switching"
"Defining a Trusted Distinguished Names List for SAML Signing Certificates"
The SAML login module verifies the SAML tokens on behalf of the Web service. The SAML login module then extracts the username from the verified token and (indirectly) passes it to Oracle Platform Security Services (OPSS) to complete the perimeter authentication.
Any configured Identity Assertion provider (that handles the NameCallback, as described in "Configuring an Authentication Provider in WebLogic Server" can then be invoked.
The provider then simply checks whether the user exists (identity assertion mode) and, if it does, the user is asserted and a subject is established.
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.
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.
SAML client policies include the user.attributes property that you can use to add user attributes to the SAML assertion.
To do this, you specify the attributes to be included as a comma-separated list. For example, attrib1,attrib2. The attribute names you specify must exactly match valid attributes in the configured identity store.
user.attributes requires that the Subject is available and subject.precedence is set to true.
The Oracle WSM runtime reads the values for these attributes from the configured identity store, and then includes the attributes and their values in the SAML assertion.
The user.attributes property is supported for a single identity store, and by default only the first identity store in the list is used. The user must therefore exist and be valid in the identity store used by the configured WebLogic Server Authentication provider. Authentication providers are described in "Configuring an Authentication Provider in WebLogic Server".
If you have more than one identity store configured, and you want to search for the user in all identity stores, follow these steps to enable searching in all configured identity stores.
In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure the identity store provider. Select the domain.
Using Fusion Middleware Control, click WebLogic Domain, then Security, and then Security Provider Configuration.
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-12.
Figure 10-12 Identity Store Configuration Page
Click Add to add a custom property.
Add the property "virtualize" with a value of "true", as shown in Figure 10-13.
Figure 10-13 Adding the virtualize property
Click OK to submit the changes.
Restart Fusion Middleware Control.
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.
Follow these steps to configure OPSS for the predefined SAML policies:
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.
Configure the identity assertion provider in the WebLogic Server Administration Console.
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".
If you will be using policies that require SSL, you need to configure SSL, as described in "Configuring Keystores for SSL".
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 client-side policy or assertion, you set a value for the saml.issuer.name property. If you set a value for this property, you must add that trusted issuer to the Issuers list with the same value.
If a different client, for instance .NET/STS, is talking to a Web service protected by a predefined SAML policy, then you need to add that issuer to the Issuers list.
To add an additional SAML assertion issuer to the Issuers list:
In the navigator pane, expand WebLogic Domain to show the domain for which you need to add the issuer. Select the domain.
Using Fusion Middleware Control, click WebLogic Domain, then Security, and then Security Provider Configuration.
Select the SAML or SAML2 login module as appropriate and click Edit.
From the SAML Specific Attributes section of the page, click Add to add an additional issuer name, as shown in Figure 10-14.
Figure 10-14 Adding a SAML Issuer to the Login Module
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.
Oracle WSM includes the wss11_saml_token_identity_switch_with_message_protection_client_policy policy that enables identity switching. Identity switching means that the policy propagates a different identity than the one based on the authenticated Subject.
You might have a scenario in which your SOA application needs to specify which user identity to use in client-side Web service policies, and then dynamically switch the user associated with the SAML token in the outbound Web service request. Instead of using the username from the Subject, this policy allows you to set a new user name when sending the SAML Web service request.
The wss11_saml_token_identity_switch_with_message_protection_client_policy policy creates the SAML token based on the user ID set via the property javax.xml.ws.security.auth.username.
Consider the following use case in which a Web service client calls a SOA application, which in turn becomes the client for a Web service.
client -> SOA -> web service
In this use case:
The client is secured with the wss11_username_with_message_protection_client_policy policy. It communicates with the SOA entry point as user end_user1.
The SOA entry point is protected by wss11_username_with_message_protection_service_policy. The SOA application authenticates the end user and establishes the Subject based on end_user1. However, it wants to propagate a different identity to the external Web service.
Therefore, to do identity switching, attach the wss11_saml_identity_switch_message_protection_client_policy policy to the SOA reference binding component.
The username that is propagated is determined dynamically by the BPEL process, which is a component in the SOA application. The username is set as BPEL property javax.xml.ws.security.auth.username with the dynamically determined username value. The external Web service can be protected by wss11_saml_with_message_protection_service_policy. It receives the switched user and not end_user1.
A similar scenario can be used by a J2EE application (replacing SOA in this scenario with the J2EE application) that establishes the Subject based on an end user but then needs to propagate a different identity. In case of J2EE, you can set the user name programmatically as follows:
((BindingProvider) port).getRequestContext().put(BindingProvider.USERNAME_PROPERTY, config.get(USERNAME));
Use Fusion Middleware Control to add the WSIdentityPermission permission to the SOA reference binding component.
The wss11_saml_token_identity_switch_with_message_protection_client_policy policy requires that an application to which the policy is attached must have the WSIdentityPermission permission. That is, applications from which Oracle WSM accepts the externally-supplied identity must have the WSIdentityPermission permission.
This is to avoid potentially rogue applications from providing an identity to Oracle WSM.
Note:
Thewss11_saml_token_identity_switch_with_message_protection_client_policy policy disables local optimization (see "Configuring Local Optimization for a Policy" for SOA to SOA interactions on the same server.)
This policy is compatible with the wss11_saml_token_with_message_protection_service_policy policy on the Web service.
For SOA:
The SOA composite has a BPEL process as one SOA service component. A BPEL process provides process orchestration and storage of synchronous and asynchronous processes.
You can define a BPEL property with the exact name javax.xml.ws.security.auth.username. The value for this property can be the identity that the SOA application wants to propagate, which could potentially be determined dynamically by the BPEL process.
For J2EE:
Set the BindingProvider.USERNAME_PROPERTY property.
The Web service client (for example, the SOA reference binding component) to which you attached the wss11_saml_token_identity_switch_with_message_protection_client_policy policy must have the oracle.wsm.security.WSIdentityPermission permission.
To use Fusion Middleware Control to add the oracle.wsm.security.WSIdentityPermission permission to the SOA reference binding component as a System Grant, perform the following steps:
In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure the application. Select the domain.
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.
From the System Policies page, select the arrow icon in the Permission field to search the system security grants.
Select one of the codebase permissions to use as a starting point and click Create Like.
In the Grant Details section of the page, enter file:${common.components.home}/modules/oracle.wsm.agent.common_11.1.1/wsm-agent-core.jar in the Codebase field.
In the Permissions section of the page, select the starting point permission class and click Edit.
Enter oracle.wsm.security.WSIdentityPermission in the Permission Class field. The resource name is the composite name for SOA, and the application name for a J2EE client. The action is always assert, as shown in Figure 10-15.
Figure 10-15 Editing the WSIdentityPermission
To use WLST to add the oracle.wsm.security.WSIdentityPermission permission, execute the following command:
grantPermission(codeBaseURL="file:${common.components.home}/modules/
oracle.wsm.agent.common_11.1.1/wsm-agent-core.jar",
permClass="oracle.wsm.security.WSIdentityPermission",
permTarget="resource=yourAppName",
permActions="assert")
In this command:
codeBaseURL must point to wsm-agent-core.jar.
permTarget syntax is "resource=yourAppName/compositeName". The resource name is the composite name for SOA, and the application name for a J2EE client.
permActions is always "assert".
For additional security, you can define a list of trusted distinguish names (DNs) for SAML signing certificates.
By default, Oracle WSM checks the incoming issuer name against the list of configured issuers, and checks the SAML signature against the configured certificates in the 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 a Trusted Distinguished Name List for SAML Signing Certificates".
Note:
In this release, the trusted DNs list is valid for SAML sender vouches and holder-of-key policies only; it is not valid for SAML bearer policies.Oracle Fusion Middleware 11g Release 1 (11.1.1) provides support for Kerberos tokens with the following predefined policies:
oracle/wss11_kerberos_token_client_policy
oracle/wss11_kerberos_token_service_policy
oracle/wss11_kerberos_token_with_message_protection_client_policy
oracle/wss11_kerberos_token_with_message_protection_service_policy
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/wss11_kerberos_token_client_template
oracle/wss11_kerberos_token_service_template
oracle/wss11_kerberos_token_with_message_protection_client_template
oracle/wss11_kerberos_token_with_message_protection_service_template
See Appendix C, "Predefined Assertion Templates" and Appendix B, "Predefined Policies" for more information on these assertions and policies.
Follow the steps described in this section to configure the Key Distribution Center (KDC) for use by the Web service client and Web service.
You can also use Microsoft Active Directory with KDC. See "Using Active Directory with Kerberos and Message Protection".
Initialize KDC database. For example, on UNIX you might run the following command as root, where oracle.com is your default realm:
root# /usr/kerberos/sbin/krb5_util -r oracle.com -s
Start the kerberos service processes. For example, on UNIX you might run the following commands as root.:
root# /usr/kerberos/sbin/krb5kdc & root# /usr/kerberos/sbin/kadmind &
Create two accounts in the KDC user registry. The first account is for the end user; that is, the Web service client principal. The second account is for the Web service principal.
One way to create these accounts is with the kadmin.local tool, which is typically provided with MIT KDC distributions. For example:
>sudo su - # become root >cd /usr/kerberos/sbin/kadmin.local >kadmin.local>addprinc fmwadmin -pw welcome1 >kadmin.local> addprinc SOAP/myhost.oracle.com -randkey >kadmin.local>listprincs # to see the added principals
The Web service principal name (SOAP/myhost.oracle.com) is shown in the example as being created with a random password. The Web service principals use keytables (a file that stores the service principal name and key) to log into Keberos System. Using a random password increases security.
The Web service client needs to be configured to authenticate against the right KDC.
The configuration for the KDC resides at /etc/krb5.conf for UNIX hosts, and at C:\windows\krb5.ini for Windows hosts.
A sample krb5.conf is shown in Example 10-7. Note the following:
The file tells the kerberos run time the realm of operation and the KDC endpoint to contact.
For Kerberos token policies to work, three additional properties need to be specified in the libdefaults section of this file:
default_tkt_enctypes
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-7 Sample krb5.conf File
[logging]
default = FILE:/var/log/krb5libs.log
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmind.log
[libdefaults]
default_realm = oracle.com
dns_lookup_realm = false
dns_lookup_kdc = false
default_tkt_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc 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]
oracle.com =
{kdc = someadminserver.com:88 admin_server = someadminserver.com:749
default_domain = us.oracle.com }
[domain_realm]
us.oracle.com = oracle.com
[kdc]
profile = /var/kerberos/krb5kdc/kdc.conf
[appdefaults]
pam =
{ debug = false ticket_lifetime = 36000 renew_lifetime = 36000
forwardable = true krb4_convert = false }
The Web service client that is enforcing Kerberos client-side policies needs to know the service principal name of the service it is trying to access. You set the service principal name in "Creating Principals".
You can specify a value for service.principal.name on the Configurations page, or override it on a per-client basis using the Security Configuration Details control when you attach the policy. The default (place holder) value is HOST/localhost@oracle.com.
The Web service client that is enforcing Kerberos client-side policies needs to know the service principal name of the service it is trying to access. You set the service principal name in "Creating Principals".
Use a configuration override to specify the service principal name at design time, as follows:
JAX-WS Clients: ((BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSSEC_KERBEROS_SERVICE_PRINCIPAL, SOAP/myhost.oracle.com@oracle.com);
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-7. This example also applies to the Web service KDC configuration.
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 the key table file, which is often referred to as the keytab, for the service principal account from the KDC and install on the machine where the Web service implementation is hosted.
For example. you can use a tool such as kadmin.local to extract the keytab for the service principal name, as follows:
>kadmin.local>ktadd -k /tmp/krb5.keytab SOAP/myhost.oracle.com
Export the keytab file to the machine where the Web service is hosted. The keytab is a binary file; if you ftp it, use binary mode.
Modify the krb5 login module as described in "Configuring the SAML and Kerberos Login Modules" to identify the location of the Web service KDC file.
For example, assume that the keytab file is installed at /scratch/myhome/krb5.keytab. Note the changes for the keytab and principal properties:
principal value=SOAP/myhost.oracle.com@oracle.com
useKeyTab value=true
storeKey value=true
keyTab value=/scratch/myhome/krb5.keytab
doNotPrompt value=true
The Web services run time must be able to verify the validity of the kerberos token.
If the token is valid, Oracle Platform Security Services (OPSS) must then be able to authenticate the user corresponding to the service principal against one of the configured WebLogic Server Authentication providers. (Authentication providers are described in "Configuring an Authentication Provider in WebLogic Server".)
The user must therefore exist and be valid in the identity store used by the Authentication provider.
For example, consider a service principal such as SOAP/myhost.oracle.com@oracle.com. In this example, a user with the name SOAP/myhost.oracle.com must exist in the identity store. Note that @domain should not be part of your user entry.
Perform the following steps to create a ticket cache for the Web service client:
Log in to the Kerberos system using the user principal you created for the client.
>kinit fmwadmin welcome1
This creates a ticket cache on the file system with ticket granting ticket. To see this:
>klist -e
Information similar to the following is displayed:
Credentials cache: /tmp/krb5cc_36687
Default principal: fmwadmin@oracle.com, 1 entry found.
[1] Service Principal: krbtgt/oracle.com@oracle.com
Valid starting: Sep 28, 2007 17:20
Expires: Sep 29, 2007 17:20
Encryption type: DES3 CBC mode with SHA1-KD
Make sure the encryption type reflects what is shown above.
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.
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.
This section describes the following tasks:
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.
Use ktpass to create a keytab file:
ktpass -princ test/testpol@{domain} -pass {...} -mapuser testpol -out
testpol.keytab -ptype KRB5_NT_PRINCIPAL -target {domain}
where test/testpol is the Service Principal Name and it is mapped to the user testpol. Do not set /desonly or cyrpto as des-cbc-crc.
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>.
Perform the following steps to set up the Web service:
Attach the Kerberos policy to your Web service.
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
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.
Verify the keytab file using kinit:
kinit -k -t <absolute path the the keytab file> <Service Principal Name>
Modify the krb5 login module as described in "Configuring the SAML and Kerberos Login Modules" to specify the keytab location and the Service Principal Name.
Use the absolute path to the keytab file. Also, be sure to add @realmname to the Service Principal Name. For example:
principal value=test/testpol@oracle.com
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:
This section describes what you need to know to configure this SAML message protection use case. The following topics are described:
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 Oracle WSM 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 Oracle WSM 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 10-2.
Table 10-2 Multiple-Domain Use Case Requirements
| Web Service Client | Web Service |
|---|---|
|
Needs its own private/public key pair in the client keystore. |
Needs its own private/public key pair in the service keystore. |
|
Needs the Web service public key. |
Needs the intermediary and root certificate corresponding to the client's public key in the keystore. These certificates will be used to verify the signature by generating a trusted certificate chain. |
|
Generates symmetric key at run time |
Needs the symmetric key, but this is sent in the request message. |
For the public key the client uses to encrypt the symmetric key -- that is, the public key of the Web service -- you have two approaches:
The Web service's base64-encoded public certificate is published in the WSDL for use by the Web service client, as described in "Using Service Identity Certification Extension". Therefore, in this use the Web service's public key does not have to be in the client's keystore.
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 Kerberos Login Modules" verifies the SAML tokens on behalf of the Web service. The SAML login module then extracts the username from the verified token and (indirectly) passes it to Oracle Platform Security Services (OPSS) via the NameCallback to complete the perimeter authentication.
Any configured WebLogic Server authentication provider (identity asserter) that handles the JAAS NameCallback can then be invoked, including the default Authentication provider.
The WebLogic Authentication provider then simply checks whether the user exists (identity assertion mode) and, if it does, the user is asserted and a subject is established.
Create the User
You use the WebLogic Server Administration Console to add the user to the identity store, as described in the Oracle WebLogic Server Administration Console Help.
The steps are repeated here for ease of use.
To create a user in the WebLogic Server Administration Console:
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.
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.
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 trustedcafilename -keystore default-keystore.jks
Perform the following steps to configure the Oracle Web Services Manager keystore:
In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure the keystore. Select the domain.
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.
If it is not already enabled, click the Configure Keystore Management check box.
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.
Enter the password for the keystore and confirm it.
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.
Click OK to submit the changes.
Note that all fields on this page require a restart of Fusion Middleware Control to take effect.
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 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 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.
This section describes the predefined WS-Trust policies and how to configure and use them. The following topics are described:
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:
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.
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".
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.
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.
The Web service client processes the RSTR sent by the STS and propagates the issued token to the Web service.
The Web service processes and verifies the issued token and generates a response back.
This section describes a sample use case for WS-Trust.
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.
The Web service client (the requestor) sends an authentication request, with accompanying credentials, to the STS.
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.
The requestor verifies the RSTR, extracts the token, and passes it to the Web service.
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-16 illustrates the message flows between the requestor, STS, and the Web service.
"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:
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.
The STS verifies the credentials presented by the Web service client and issues a security token for the entity identified in the onBehalfOf element.
The Web service client verifies the RSTR, extracts the token, and passes it to the Web service.
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-3. 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.
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.
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:
The Web service client sends a user name and password to the STS.
The STS verifies the password and returns a SAML assertion.
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:
The client sends a user name and password to a KDC and gets a Kerberos token.
The client sends the Kerberos token to the STS and gets a SAML assertion.
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.
The client generates a public/private key pair.
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.)
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.
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.
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.
For SAML Holder of Key (HOK), a proof key is required to protect communications between the client and the Web service. The proof key indicates proof of possession of the token associated with the requested security token.
You specify the requirements for the proof key type in the oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy policy in the <key-type> entry in the <sp:IssuedToken> policy assertion. For example,
<orasp:request-security-token-templateorasp:key-type = "Symmetric"
or
orasp:key-type = "Public"
Symmetric, asymmetric, and no proof key (not defined) are supported.
These possible values of <key-type> are contained in the WS-Trust 1.3 specifications:
http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey
http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey
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.
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.
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.
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:
There are several requirements for successfully communicating with the STS using Automatic Policy Configuration:
The oracle/sts_trust_config_service_policy policy must be attached to the Web service. If it is not, you cannot use Automatic Policy Configuration and must instead manually configure the oracle/sts_trust_config_client_policy policy for the client, as described in "Manually Configuring the STS Config Policy From the Web Service Client: Main Steps".
Automatic Policy Configuration cannot be used for SAML sender vouches confirmation because the trust is between the Web service and the client. The Web service WSDL will not have any information about the STS.
The certificate and public key alias of the STS must be in the keystore. The default alias name is sts-csf-key. See "Configuring Keystores for Message Protection" for information on how to do this.
The client's public key must be available in the STS keystore.
Perform the following steps to use Automatic Policy Configuration.
"Configure a Web Service Client for Automatic Policy Configuration"
"Configure a Web Service for Automatic Policy Configuration"
Configure a Policy for Automatic Policy Configuration
Perform the following steps to configure a policy for automatic policy configuration:
Decide which STS your Web service trusts and import that STS's public certificate into the Oracle WSM keystore.
Optionally, add the Distinguished Name of the STS to the Trusted STS list, as described in "Defining a Trusted Distinguished Name List for SAML Signing Certificates".
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.
Make a copy of the sts_trust_config_service_policy policy.
Edit the orasp:port-uri field to add the port-uri of the STS.
An STS usually exposes multiple URI points for different input and output token types; use the URI corresponding to the token that you want. For Oracle OpenSSO STS, the possible values for orasp:port-uri are as follows:
http://<host:port>/openssosts/sts/wss10x509
http://<host:port>/openssosts/sts/wss10un
http://<host:port>/openssosts/sts/wss11kerberos
https://<host:ssl_port>/openssosts/sts/tlswss10un
Configure a Web Service Client for Automatic Policy Configuration
Perform the following steps to configure a Web service client for automatic policy configuration:
Attach the issue token policy to your Web service client, depending on what type of token the Web service requires.
The following predefined issue token policies are provided:
oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy for SAML HOK.
oracle/wss_sts_issued_saml_bearer_token_over_ssl_client_policy for SAML Bearer.
Set or override the following properties of the issued token policy depending on the use case. See Table 8-3 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.
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
Attach the edited sts_trust_config_service_policy to the Web service.
Attach the issued-token service policy (corresponding to the one attached to the client). There are two predefined issue token policies:
oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy -- Use this when you want your service to accept SAML HOK asymmetric or symmetric. Do not use SSL for this policy.
As with all other wss11 message protection policies, you must set up an encryption key.
You can modify some options in the policy. For example, whether you want SAML 1.1 or 2.0, and whether you want asymmetric or symmetric keys.
oracle/wss_sts_issued_saml_bearer_token_over_ssl_service_policy -- Use this when you want SAML Bearer. However, you must set up your Web service for SSL to use this policy.
You can specify whether you want SAML 1.1 or 2.0.
Override keystore.enc.csf.key in the issued-token service policy, if required.
Make sure the client's public key is available in the Oracle WSM keystore.
You are encouraged to configure the STS config policy from the Web service, as described in "Setting Up Automatic Policy Configuration for STS". However, if you did not configure the STS config policy from the Web service, or if you are using the SAML sender vouches confirmation method, you must then configure it from the Web service client.
Perform the following steps to configure the STS config policy from the Web service client.
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.
Use Fusion Middleware Control to edit your chosen oracle/sts_trust_config_client_policy policy.
The predefined oracle/sts_trust_config_client_policy policy is shown in Example 10-8. At a minimum, you need to provide the following information:
Issuer address -- Port-uri is the actual endpoint URI of the STS.
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 issue token client policy:
If policy-reference-uri points to a username-based policy, then you later configure the sts.auth.user.csf.key parameter to authenticate to STS and create a username token. You also configure sts.auth.x509.csf.key to specify the signature and encryption key alias.
If the policy-reference-uri points to an x509-based policy, then you later configure the sts.auth.x509.csf.key parameter to specify the X509 certificate for authenticating to the STS.
port-endpoint -- This is the endpoint of the Web service, specified as target-namespace#wsdl.endpoint(service-name/port-name).
Alias of STS Certificate -- sts-keystore-recipient-alias is the alias of the STS certificate you added to the keystore. The default alias name is sts-csf-key.
Example 10-8 oracle/sts_trust_config_client_policy
<orasp:sts-trust-config xmlns:orasp="http://schemas.oracle.com/ws/2006/01/securitypolicy" xmlns:orawsp="http://schemas.oracle.com/ws/2006/01/policy" orasp:policy-reference-uri="oracle/wss10_username_token_with_message_protection_client_policy" orasp:port-endpoint="target-namespace#wsdl.endpoint(service-name/port-name)" orasp:port-uri="http://host:port/sts-service" orasp:soap-version="12" orasp:sts-keystore-recipient-alias="sts-csf-key" orasp:wsdl-uri="http://host:port/sts?wsdl" orawsp:Enforced="true" orawsp:Silent="true" orawsp:category="security/sts-config" orawsp:name="STS Trust Configuration"> <orawsp:bindings> <orawsp:Config orawsp:configType="declarative" orawsp:name="StsTrustConfig"> <orawsp:PropertySet orawsp:name="standard-security-properties"> <orawsp:Property orawsp:contentType="constant" orawsp:name="role" orawsp:type="string"> <orawsp:Value>ultimateReceiver</orawsp:Value> </orawsp:Property> </orawsp:PropertySet> </orawsp:Config> </orawsp:bindings> </orasp:sts-trust-config>
Save your changes.
If you have not already done so, select an issue token client policy from the client policies listed in Table 10-3. Your choices are:
oracle/wss_sts_issued_saml_bearer_token_over_ssl_client_policy
oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy
oracle/wss11_sts_issued_saml_with_message_protection_client_policy
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:
sts_trust_config_client_policy
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.
Use Fusion Middleware Control to edit your chosen issue token client policy.
Save your changes.
To set up SAML sender vouches with WS-Trust, configure the Web service without an issued token policy; that is, use the oracle/wss11_saml_token_with_message_protection_service_policy policy.
Configure the client with an issue token policy. Use the oracle/wss11_sts_issued_saml_with_message_protection_client_policy, which is meant for SAML sender vouches, and also an STS config policy.
The Automatic Policy Configuration feature (see "Setting Up Automatic Policy Configuration for STS") cannot be used for SAML sender vouches because the Web service WSDL will not have information about the STS.
The available WS-Trust policies are listed in Table 10-3.
Table 10-3 Available WS-Trust Policies
| Name | Description |
|---|---|
|
oracle/sts_trust_config_service_policy |
Use this policy to specify the STS configuration information that is used to invoke the STS for token exchange. You use this policy with the Web service. |
|
oracle/sts_trust_config_client_policy |
Use this policy to specify the STS configuration information that is used to invoke the STS for token exchange. You use this policy with the Web service client only when not using Automatic Policy Configuration. |
|
oracle/wss_sts_issued_saml_bearer_token_over_ssl_client_policy |
This policy inserts SAML bearer assertion issued by a trusted STS. Messages are protected using SSL. |
|
oracle/wss_sts_issued_saml_bearer_token_over_ssl_service_policy |
This policy authenticates users using credentials provided in SAML tokens with confirmation method bearer in the WS-Security SOAP header. The credentials in the SAML token are authenticated against a SAML login module. The policy verifies that the transport protocol provides SSL message protection. This policy can be applied to any SOAP-based endpoint. |
|
oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy |
This policy inserts a SAML HOK assertion issued by a trusted STS. Messages are protected using proof key material provided by STS. |
|
oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy |
This policy authenticates a SAML HOK assertion issued by a trusted STS. Messages are protected using WS-Security's Basic 128 suite of symmetric key technologies. |
|
oracle/wss11_sts_issued_saml_with_message_protection_client_policy |
This policy inserts a SAML sender vouches assertion issued by a trusted STS. Messages are protected using the client's private key. |
Table 11-2 shows the properties you can set via programmatic configuration overrides for a given policy.
Table 10-4 describes a series of sample use cases that show how to override STS properties programmatically.
Table 10-4 STS Programmatic Configuration Use Cases
| Use Case | Sample Code |
|---|---|
|
Token exchange username token – SAML with symmetric proof key |
|
|
Token exchange x509 token – SAML with symmetric proof key |
|
|
Token exchange username token – SAML with asymmetric proof key |
|
|
Token exchange x509 token – SAML with asymmetric proof key |
|
|
On Behalf Of token exchange with On Behalf Of username from Subject, requestor token username – SAML with symmetric proof key |
|
|
On Behalf Of token exchange with On Behalf Of username, requestor token username – SAML with symmetric proof key |
|
|
On Behalf Of token exchange with On Behalf Of username, with requestor token x509 – SAML with symmetric proof key |
|
|
On Behalf Of token exchange with On Behalf Of username from Subject, with requestor token username – SAML with asymmetric proof key |
|
|
On Behalf Of token exchange with On Behalf Of username, with requestor token username – SAML with asymmetric proof key |
(
|
|
On Behalf Of token exchange with On Behalf Of username, with requestor token x509 - SAML with asymmetric proof key |
|
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".
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:
The following procedure describes the steps required to configure OpenSSO STS for use with each of the example scenarios described in this section.
Log in to the OpenSSO STS instance.
Navigate to Configuration > Global > Security Token Service.
Under Security: Security Mechanism: Security Token Accepted by STS Services enable all options.
Under the Credential for User Token section, add a new credential for the token with the name and password set as required. Set this to test/test.
Under the On Behalf of Token section, select ldapService from the Authentication Chain for On Behalf of Token drop-down list.
Under the Signing section, enable the following options:
- Is Request Signature Verified
- Is Response Signed Enabled (select Body and Timestamp)
Under the Encryption section, enable the following options:
- Is Request Decrypted (select Body and Header)
- Is Response Encrypted
Select AES from the Encryption Algorithm drop-down list, and select 128 from the Encryption Strength drop-down list.
To support the WS-Security 1.1 Kerberos token with message protection requestor token, under the Kerberos Configuration section and configure the following values:
Table 10-5 OpenSSO STS Kerberos Token With Message Protection Configuration
| Configure this property . . . | To specify . . . |
|---|---|
|
Kerberos Domain Server |
Fully qualified hostname of the domain server. |
|
Kerberos Domain |
Domain name. |
|
Kerberos Service Principal |
Service principal name in the following format: |
|
Kerberos Key Tab File |
Location of the key tab file created for the STS. |
|
Is Verify Kerberos Signature |
Enable only when JDK6 is used. |
To support SSL, perform the following steps:
In the Token Issuance Attributes section, edit the SSL Endpoint based on your OpenSSO instance.
Under Signing, enable the Disable signature validation when transport is secured with SSL option.
Under Encryption, enable the Disable decryption when transport is secured with SSL option.
To support SSL on the server hosting the OpenSSO STS:
On the WebLogic Server hosting the OpenSSO STS, to configure SSL, perform the steps described in "Configuring Keystores for SSL".
On Glassfish server hosting the Open SSO STS, perform the following steps:
Generate a new key pair for the application server by issuing the following command:
keytool -genkey -keyalg <algorithm for generating the key pair> -keystore keystore.jks -validity <days> -alias <alias_name>
For example:
keytool -genkey -keyalg RSA -keystore <glassfish_install_dir>/domains/<sts_deploy_domain>/config/keystore.jks -validity 365 -alias owsm
When prompted for first and last name, enter the hostname of the machine for which the certificate is to be generated. Also enter the appropriate details for the other prompts.
Generate a Certificate Signing Request (CSR) by issuing the following command:
keytool -certreq -alias owsm -file owsm.csr -keystore keystore.jks -storepass changeit
The request that is generated and written to the owsm.csr file needs to be submitted to a Certificate Authority in order to get a valid certificate. For example, the Certificate Management Server maintained by the OpenSSO QA team at https://mahogany.red.iplanet.com.
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.
Copy the certificate content (PKCS # 7 format) starting from BEGIN CERTIFICATE to END CERTIFICATE into a file with .cert extension and import the server certificate into the <glassfish_install_dir>/domains/<sts_deploy_domain>/config/keystore.jks file by using the following keytool command:
keytool -import -v -alias owsm -file owsm.cert -keystore keystore.jks -storepass changeit
Enter YES when prompted if you trust the certificate.
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
Import this certificate with alias as "rootca" into the <glassfish_install_dir>/domains/<sts_deploy_domain>/config/cacerts.jks file, using the following command:
keytool -import -v -alias rootca -file mahogany.cert -keystore cacerts.jks -storepass changeit
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).
To configure GlassFish with the new certificate, access the Administration Console at http://hostname:admin-port/. Navigate to Configuration -> HTTP Service -> http-listener2 (default SSL enabled port) -> SSL, and change the certificate nickname from s1as (self-signed cert) to owsm.
Restart Glassfish.
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:
Configure OpenSSO STS, as described "Configuring OpenSSO STS".
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)
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.)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-3, as required for your requestor token.
The sts.auth.user.csf.key should be set to the user credentials available in the default OpenSSO STS configuration. Namely, username test, with password set to test. Though, it is not required to be set for the X509 requestor token.
Note:
For more information about overriding client configuration properties when attaching a policy, see "Attaching Policies to Web Service Clients".By default, the oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy policy is configured with token type of SAML 1.1. If you wish to configure the token type to be SAML 2.0, you will need to make a copy of the policy and edit it, as described in Creating a Web Service Policy from an Existing Policy. (This value should match the service policy.)
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:
Configure OpenSSO STS, as described "Configuring OpenSSO STS".
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"
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.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-3, 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-3. For more information, see "On Behalf Of Use Cases".
The on.behalf.of property should be set to true. The sts.auth.on.behalf.of.csf.key should be set to the user credentials available in the default Open SSO STS configuration that support the "on behalf of" use case. Namely, demo, with password set to changeit.
Note:
For more information about overriding client configuration properties when attaching a policy, see "Attaching Policies to Web Service Clients".To grant permission to the client application to request a token from OpenSSO STS "on behalf of" a user, edit the <MW_HOME>/user_projects/domains/base_domain/config/fmwconfig/system-jazn-data.xml file to include the following code:
<grant>
<grantee>
<codesource>
<url>
file:${common.components.home}/modules/oracle.wsm.agent.common_11.1.1/wsm-agent-core.jar
</url>
</codesource>
</grantee>
<permissions>
<permission>
<class>oracle.wsm.security.WSIdentityPermission</class>
<name>resource=<Client App. Name></name>
<actions>assert</actions>
</permission>
</permissions>
</grant>
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:
Configure OpenSSO STS. as described "Configuring OpenSSO STS".
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)
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".
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-3, as required for your requestor token.
The sts.auth.user.csf.key should be set to the user credentials available in the default OpenSSO STS configuration. Namely, username test, with password set to test. Though, it is not required to be set for the X509 requestor token.
Note:
For more information about overriding client configuration properties when attaching a policy, see "Attaching Policies to Web Service Clients".
|
 Copyright © 2007, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|