| Oracle® Application Server Web Services Security Guide 10g (10.1.3.5.0) Part Number E13983-01 |
|
|
View PDF |
| Oracle® Application Server Web Services Security Guide 10g (10.1.3.5.0) Part Number E13983-01 |
|
|
View PDF |
This chapter describes how to configure message-level security for SOAP messages. This includes configuring keystores, security tokens, signature, and encryption. The terminology used in this chapter, is described in "Web Service Security Concepts".
This chapter contains the following sections.
This section describes how to create and configure a keystore that can be used with Web service security. It also describes how you can enhance the protection of your keystore, signature key, and encryption key passwords by employing password indirection.
Note:
This section assumes that you are familiar with public key infrastructure concepts such as trust stores, certificates, and public and private keys. If you are not, the following books and Web sites provide an overview of these topics.Oracle Application Server Certificate Authority Administrator's Guide
http://download-east.oracle.com/docs/cd/B14099_15/idmanage.htm
Oracle Security Developer Tools (OSDT) Reference
http://download-east.oracle.com/docs/cd/B14099_15/idmanage.htm
Java Security Overview
http://java.sun.com/developer/technicalArticles/Security/whitepaper/index.html
J2SE Security and the Java Platform
A keystore is a file that provides information about available public and private keys. 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
to decrypt data, you must have the private key which corresponds to the public key
These trusted certificates and public and private keys are stored in the keystore. Oracle Application Server Web Services Security supports a variety of keystores, including Oracle Wallet, PKCS12, and Sun Microsystem's Java Key Store (JKS) format. The following sections describe where you can obtain trusted certificates and how to create and use these keystores.
You can obtain a certificate from a Certificate Authority (CA), such as Verisign or Entrust, and include them in the keystore. To get the certificate, you must create a Certificate Request and submit it to the CA. The CA will authenticate the certificate requestor and create a digital certificate based on the request. You must then include the certificate in the wallet.
The Java Key Store (JKS) is the proprietary keystore format defined by Sun Microsystems. To create and manage the keys and certificates in the JKS, use the keytool utility that is distributed with the Java JDK. You can use the keytool utility to perform the following tasks:
create public and private key pairs, designate public keys belonging to other parties as trusted, and manage your keystore.
issue certificate requests to the appropriate Certification Authority (CA), and import the certificates which they return.
administer your own public and private key pairs and associated certificates. This enables you to use your own keys and certificates to authenticate yourself to other users and services. This process is known as "self-authentication". You can also use your own keys and certificates for data integrity and authentication services, using digital signatures.
cache the public keys of your communicating peers. The keys are cached in the form of certificates.
The following section provides an outline of how to create and manage the JKS with the keytool utility. It describes how to create a keystore and to load private keys and trusted CA certificates. You can find more detailed information on the commands and arguments for the keytool utility at this Web site.
http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/keytool.html
Create a new private key and self-signed certificate.
Use the genKey command to create a private key. It will create a new private key if one does not exist. The following command generates an RSA key, with RSA-SHA1 as the signature algorithm, with the alias test in the test.jks keystore.
keytool -genkey -alias test -keyalg "RSA" -sigalg "SHA1withRSA" -dname "CN=test, C=US" -keypass test123 -keystore test.jks -storepass test123
By default, if you omit the algorithm to generate the key pair (keyalg), then the genKey command generates a DSA key. If you omit the signature algorithm (sigalg) argument, then the signature algorithm is derived based on the value of keyalg.
Make sure to use the correct values for the keyalg and sigalg arguments, based on your signature configuration. If the underlying algorithm to generate the key pair (keyalg) is DSA, then the default signature algorithm (sigalg) SHA1withDSA is used. If the underlying keyalg is RSA, then the default sigalg RSAwithMD5 is used.
Display the keystore.
The following command displays the contents of the keystore. It will prompt you for the keystore password.
keytool -list -v -keystore test.jks
Import a trusted CA certificate in the keystore.
Use the -import command to import the certificate. The following command imports a trusted CA certificate into the test.jks keystore. It will create a new keystore if one does not exist.
keytool -import -alias aliasfortrustedcacert -trustcacerts -file trustedcafilename -keystore test.jks -storepass test123
Generate a certificate request.
Use the -certreq command to generate the request. The following command generates a certificate request for the test alias. The CA will return a certificate or a certificate chain.
keytool -certreq -alias test -sigalg "RSAwithSHA1" -file certreq_file -keypass test123 -storetype jks -keystore test.jks -storepass test123
Replace the self-signed certificate with the trusted CA certificate.
You must replace the existing self-signed certificate with the certificate from the CA. To do this, use the -import command. The following command replaces the trusted CA certificate in the test.jks keystore.
keytool -import -alias test -file trustedcafilename -keystore test.jks -storepass test123
The Oracle Wallet acts as a keystore for storing and managing public and private keys, and X.509 certificates. To create a wallet, Oracle provides the orapki utility in the ORACLE_HOME/bin directory.
This section provides an outline of how to create and manage the Oracle Wallet with the orapki utility. You can find more information on the Oracle Wallet at this Web site.
http://www.oracle.com/technology/products/oid/oidhtml/sec_idm_training/html_masters/basics06.htm
You can find more information on using the orapki utility for creating and managing the Oracle Wallet in the Oracle Database Advanced Security Administrator's Guide.
"How to Create an Oracle Wallet with Self-Signed Certificates" describes how to create an Oracle Wallet, add a self-signed certificate, and export it.
"How to Create an Oracle Wallet and User Certificates" describes how to work with certificate requests and replies. Steps 1 to 3 describe how to create and export a certificate request.
The following steps illustrate creating an Oracle Wallet with a self-signed certificate, viewing the wallet, and exporting the certificate.
Create a root Oracle Wallet.
orapki wallet create -wallet wallet_dir wallet_dir
This command creates the root Oracle Wallet in the wallet_dir directory. By default, the wallet will be named ewallet.p12.
Add a root certificate to the Oracle Wallet.
orapki wallet add -wallet wallet_dir -dn 'CN=root_test,C=US' -keysize 2048 -self_signed -validity 3650
This command adds a self-signed (root) certificate to the wallet. It creates a self-signed certificate with a validity of 3650 days. The distinguished name of the subject is CN=root_test,C=US. The key size for the certificate is 2048 bits.
Export the self-signed certificate from the Oracle Wallet.
orapki wallet export -wallet wallet_dir -dn 'CN=root_test,C=US' -cert b64certificate.txt
This command exports the self-signed certificate to the b64certificate.txt file. Note that the distinguished name used is the same as in the previous step.
View the contents of the root Oracle Wallet.
orapki wallet display -wallet wallet_dir
The display command enables you to view the contents of the Oracle Wallet.
The following steps illustrate creating an Oracle Wallet, adding and exporting a certificate request, and then importing the received certificate.
Create an Oracle Wallet with auto login enabled.
orapki wallet create -wallet server -auto_login
This command creates an Oracle Wallet at /private/user/server with auto login enabled.
Add a certificate request to the Oracle Wallet.
orapki wallet add -wallet server -dn 'CN=server_test,C=US' -keysize 2048
This command adds a certificate request to the wallet that was created. The distinguished name of the subject is CN=server_test,C=US. The specified key size is 2048 bits.
Export a certificate request from the Oracle Wallet.
orapki wallet export -wallet server -dn 'CN=server_test, C=US' -request creq.txt
This command exports the certificate request to the specified file, creq.txt. Note that the order of the distinguished name is reversed (when the certificate request was created).
Create a signed certificate from the certificate request for testing purposes.
orapki cert create -wallet wallet_dir -request creq.txt -cert cert.txt -validity 3650
This command creates a certificate, cert.txt with a validity of 3650 days. The certificate is created from the certificate request generated in the preceding step.
View a certificate.
orapki cert display -cert cert.txt -complete
This command displays the certificate generated in the preceding step. The -complete option enables you to display additional certificate information, including the serial number and public key.
Add a trusted certificate to the Oracle wallet.
orapki wallet add -wallet server -trusted_cert -cert b64certificate.txt
This command adds a trusted certificate, b64certificate.txt to the wallet. You must add all trusted certificates in the certificate chain of a user certificate before adding a user certificate.
Add a user certificate to the Oracle wallet.
orapki wallet add -wallet server -user_cert -cert cert.txt
This command adds the user certificate, cert.txt to the wallet.
View the contents of the Oracle wallet.
orapki wallet display -wallet server
The display command enables you to view the contents of the Oracle Wallet.
Keystore, signature, and encryption keys can be configured at global or port level. Oracle Web Service security implementation can be configured to use JKS or PKCS12 or Oracle Wallet.
A global keystore and key setting apply to all Web service applications that are deployed in a particular OC4J instance. "Keystore Elements" provides more information about the global keystore. To configure an instance level keystore and keys use Application Server Control tool. For more information, see the topic Viewing or Modifying the Instance Keystore and Identity Certificates in the Application Server Control on-line help.
You can use a keystore and keys for an Oracle Web service application which are separate from those belonging to the instance. An application-specific keystore and key setting takes precedence over instance-specific settings.
To configure an application-specific keystore and keys, add the <key-store>, <signature-key>, and <encryption-key> elements under the <security> element in the oracle-webservices.xml file for the server and <generated_name>_Stub.xml for the client.
Example 3-1 illustrates a keystore configuration for a Web service application. The name of the keystore is mykeystore.jks and the password to access it is abc.
Many OC4J components, such as the keystore, signature key, and encryption key, require passwords for authentication. Embedding these passwords into deployment descriptors, such as oracle-webservice.xml, poses a security risk, especially if the permissions on the files allow them to be read by any user. To avoid this problem, you can employ password indirection. Password indirection replaces cleartext passwords with information necessary to look up the password in another location.
Use Application Server Control administration console Instance/Application Keystore settings screen to indirect the passwords for keystores and keys. This action automatically adds a user entry with an indirect username and password to the instance-specific ORACLE_HOME/j2ee/instance/config/system-jazn-data.xml.
See Also:
See the Oracle Containers for J2EE Security Guide for more information on creating and using indirect passwords.
In the current release, you must use Application Server Control to obfuscate the keystore, signature key, and encryption key passwords. During obfuscation, an indirect user account is created in the system-jazn-data.xml file.
If you undeploy the application, these indirect user accounts are not removed. You must manually delete the them by using Application Server Control.
The following list describes how you can identify the names of indirect user accounts for global-level and port-level keystores and keys.
For a port-level keystore, the name of the indirect user account is created with the following format:
applicationName.portName.keystore.actual-keystore-name
For example:
my-security-sample.myport.keystore.myks.jks
For a global-level keystore, the name of the indirect user account is created with the following format:
default.keystore.actual-keystore-name
For example:
default.keystore.myks.jks
For port-level keys, the name of the indirect user account is created with the following format:
applicationName.portName.key.actual-key-alias
For example:
my-security-sample.myport.key.mysignkey
For global-level keys, the name of the indirect user account is created with the following format:
default.key.actual-key-alias
For example:
default.key.mysignkey
With Web Services Security, you can employ a username, X.509, or SAML token as your security element. They can integrate with many of the security providers defined under Oracle Containers for J2EE. See "Web Service Security Integration" for more information on how Web service security integrates with the OracleAS Web Services Security framework.
Table 3-1 lists the security providers that are supported for the username, X.509, and SAML tokens.
Table 3-1 Security Tokens and Providers Supported by Web Services Security
| Token Name | File-Based Security Provider (XML) | Oracle Identity Management (versions 10.1.2.0.x and 10.1.4) | External LDAP Security Provider | Custom Security Provider | Oracle Access Manager (versions 7.0.4 and 10.1.4) |
|---|---|---|---|---|---|
|
Username token, Plaintext password |
YES |
YES |
YES |
YES |
YES |
|
Username token, Digest password |
YES |
NO |
NO |
NO |
NO |
|
X.509 token |
YES |
YES |
YES |
NO |
YES |
|
SAML token |
YES |
YES |
YES, but must configure manually |
NO |
YES |
This section describes how to configure the username token for the server and for the client. It also describes how to integrate the token with OC4J security providers.
For the server, you configure the user name token in the oracle-webservices.xml deployment descriptor. Configuring the username token for the server consists of the following steps:
Configure the Nonce Cache with a Digest Password (Optional)
This step is required for digest password only.
To configure a user name token for the server side, use the <verify-username-token> element. This element can occur only once as a subelement of the <inbound> element. Attributes of the <verify-username-token> element let you configure details about the password, and whether a nonce or a creation time should be included in the token.
Details about the password are specified in the password-type attribute. The password can be designated as either plaintext or digest. Plaintext indicates that the token will expect a password that is in unencrypted, human-readable form. Digest indicates that the password is sent in digest form—not in clear text. That is, a cryptographic checksum value has been calculated for the password that is sent with the token. The purpose of the value is to ensure that the password has not been tampered with. The recipient of the password, in this case the server, recomputes the cryptographic checksum and compares it with the cryptographic checksum passed with the password; if they match, it is probable that the password was not tampered with during transmission.
If you choose to send a digest password, then you must choose whether a nonce or a creation time should be included in the username token. The require-nonce attribute specifies whether a nonce must be included in the username token. A nonce is a random value that can be included in the username token to prevent replay attacks. The server caches this value in order to compare it with the nonce included with succeeding requests. Using a nonce ensures that the application generates a different password digest at every invocation; two nonce digests will differ even if they have identical password and time created values.
The require-created attribute specifies whether the token's creation time must be included in the username token. This can also be used to prevent replay attacks.
See Also:
"Preventing Replay Attacks with Nonces" provides more information on how nonces can be used to help prevent replay attacks.
The <verify-username-token> and its attributes are listed in Table 2-4.
Example 3-2 illustrates a sample username token configuration.
You can configure the Web service so that it will authenticate a username token without requiring a password. By not requiring a password, interoperability with other vendors is enhanced.
To allow the service to authenticate the token without a password, OracleAS Web Services provides the boolean username.token.allow.nopassword property as a <property> subelement of the <verify-username-token> element.
For example, you can enter the following configuration in the oracle-webservices.xml file to allow the service to authenticate a username token without requiring a password.
...
<inbound>
<verify-username-token>
<property name="username.token.allow.nopassword" value="true"/> </verify-username-token> </inbound>
...
If a client sends a username token without a password to a service with this configuration, it will be accepted. The following is an example of a client configuration for a username token that does not declare a password.
.. <outbound> <username-token name="oc4jadmin" add-nonce="true" add-created="true"/> </outbound> ...
See Also:
For more information on the username.token.allow.nopassword property, see Table 2-5, "Subelements of the <verify-username-token> Element".
The nonce cache can be statically configured in the javacache.xml file (ORACLE_HOME/j2ee/home/config/javacache.xml). The OracleAS Web Services runtime uses this file to configure the Java Object Cache at runtime. You can configure the nonce cache by editing the values for the <max-size> and <max-objects> elements in this file.
The <max-size> element specifies the maximum size of the memory, in megabytes, available to the Java Object Cache. The <max-objects> element specifies the maximum number of in-memory objects that are allowed in the cache. The count does not include group objects, or objects that have been spooled to disk and are not currently in memory.
See Also:
"Preventing Replay Attacks with Nonces" provides more information on how nonces can be used to help prevent replay attacks.
For more information on the javacache.xml file, see "Java Object Cache" in the Oracle Containers for J2EE Services Guide.
Example 3-3 illustrates a sample nonce cache configuration in the javacache.xml file. The nonce cache is configured to hold a maximum of 2000 objects and grow up to 512 kilobytes in size.
Example 3-3 Sample Nonce Cache Configuration (javacache.xml)
<?xml version = '1.0' encoding = 'UTF-8'?>
<cache-configuration xmlns="http://www.oracle.com/oracle/ias/cache/configuration"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<max-objects>
20000
</max-objects>
<max-size>
512
</max-size>
</cache-configuration>
You can use the following tools to configure the username token for the server.
You can configure the username token in the Inbound Policies Authentication Page. For more information, see the context-sensitive help for this page in the Application Server Control online help.
Authentication is set on the Authentication page of the Secure Web Services wizard or the Web Services Editor. For more information, see the topic Setting Authentication for Web Services in the Oracle JDeveloper on-line help.
You can use this tool to assemble a security configuration into your Web service. To do this, follow these general steps:
Include a configuration for the username token in the oracle-webservices.xml deployment descriptor.
Use the ddFileName argument to specify this file as input to the appropriate Web service assembly command.
For more information on the ddFileName argument and assembling Web services, see "Using WebServicesAssembler" in the Oracle Application Server Web Services Developer's Guide.
For the client, you configure the username token in the <generated_name>_Stub.xml deployment descriptor. Configuring the username token for the client consists of the following steps:
Pass the Username and Password with a Callback Handler (Optional)
Pass the User Name and Password with Stub Properties (Optional)
The <username-token> element specifies the username token that must be inserted into the security header block. Providing appropriate values for the name and password attributes allow the message to access the service.
Adding a nonce with the add-nonce attribute and a request creation time with the add-created attribute to the token can provide additional security. If you choose a digest password, then these attributes must be present and set to true. These attributes are optional for plain text password.
Example 3-4 illustrates a sample username token configuration for the server.
A callback handler is a javax.security.auth.callback.CallbackHandler instance that allows a login module to interact with a user to obtain login information. Callback handlers are defined in the Java Authentication and Authorization Service (JAAS) package which enables applications to authenticate and enforce access controls upon users.
There are three types of callback handlers, each represented by a class in the javax.security.auth.callback package:
NameCallback—a callback handler to handle a user name
PasswordCallback—a callback handler to handle a password
TextInputCallback—a callback handler to handle any text field in a login form other than a user name or password field
See Also:
The Oracle Containers for J2EE Security Guide provides more information on callback handlers.
To dynamically pass the username and password to the service, the client can use a callback handler. You will typically write your own callback handler class that implements one or more of the classes in the callback package. Then, use the <username-token> element's cbhandler-name attribute to specify the name of the handler class.
the Example 3-5 illustrates a fragment of the user-defined UsernameTokenCallbackHandler callback handler implementation. This callback handler handles javax.security.auth.callback.Namecallback and Passwordcallback to pass the username and password.
Example 3-5 Callback Handler for a Username Token
... package oracle.ws.wssecurity.usernametoken; ... import javax.security.auth.callback.Callback; import javax.security.auth.callback.CallbackHandler; import javax.security.auth.callback.PasswordCallback; import javax.security.auth.callback.NameCallback; import javax.security.auth.callback.TextOutputCallback; ... public class UsernameTokenCallbackHandler implements CallbackHandler { Callback c = null; public void handle(Callback[] callbacks) { try { if (callbacks == null) { return; } for (int i = 0; i < callbacks.length; i++) { c = callbacks[i]; if (c instanceof NameCallback) { NameCallback nc = (NameCallback)c; nc.setName("name"); } else if (callbacks[i] instanceof PasswordCallback) { PasswordCallback pc = (PasswordCallback)callbacks[i]; pc.setPassword("password".toCharArray()); } } } catch (Exception e) { e.printStackTrace(); } } }
Example 3-6 illustrates the cbhandler-name attribute in the <username-token> element configured to use the oracle.ws.wssecurity.usernametoken.UsernameTokenCallbackHandler callback handler defined in the previous example.
If you do not include the <username-token> attributes name and password in your configuration, then the client runtime can dynamically build the username token using the Stub.USERNAME_PROPERTY and Stub.PASSWORD_PROPERTY properties supported by JAX-RPC. For more information on Stub properties, see "Username Token Elements for Outbound Messages".
Example 3-7 illustrates client code that uses Stub.USERNAME_PROPERTY and Stub.PASSWORD_PROPERTY to call the Web service with the username oc4jadmin and password welcome.
Example 3-7 Using Stub Properties to Access a Web Service
...
public void UserNameWithSystemProperties() throws Exception {
// Call the service with Stub property username/password
((Stub) stub)._setProperty(Stub.USERNAME_PROPERTY, "oc4jadmin");
((Stub) stub)._setProperty(Stub.PASSWORD_PROPERTY, "welcome");
String response = stub.helloUser(MESSAGE);
System.out.println("Response: ["+response+"]");
...
You can use the following tools to configure the username token for the client.
Authentication is set on the Authentication page of the Secure Web Services wizard or the Web Services Editor. For more information, see the topic Setting Authentication for Web Services in the Oracle JDeveloper on-line help.
You can use this tool to assemble a security configuration into your Web service client proxy. To do this, follow these general steps:
Include a configuration for the username token in the <generated_name>_Stub.xml deployment descriptor.
Use the ddFileName argument to specify this file as input to the WebServicesAssembler genProxy command.
For more information on the ddFileName argument and assembling Web service clients, see "Assembling a J2SE Web Service Client" in the Oracle Application Server Web Services Developer's Guide.
Table 3-1 provides a summary of the security providers that can be used with the username token. All of the security Providers that are available for the username token can be configured by using Application Server Control.
You should configure OC4J with security providers before you configure Web service security. Table 3-2 indicates where you can find additional information on configuring the security providers that are available for the username token.
Table 3-2 Security Providers that can be Used with the Username Token
| For this Security Provider type | See this resource for more information |
|---|---|
|
File-based Security Provider |
For information on how to configure a file based provider for the username security token, see the Oracle Containers for J2EE Security Guide. |
|
Oracle Identity Management |
For information on how to configure Oracle Identity Management, including Oracle Internet Directory (OID), for the username security token, see the Oracle Containers for J2EE Security Guide. Single sign-on is not available for the username token. |
|
External LDAP Providers |
For information on how to configure external LDAP providers for the username security token, see the Oracle Containers for J2EE Security Guide. |
|
Custom Security Providers |
For information on how to configure custom providers for the username security token, see the Oracle Containers for J2EE Security Guide. |
|
Oracle Access Manager |
For information on how to configure Oracle Access Manager as a security provider for the username security token, see "Using Oracle Access Manager as a Security Provider for Username Token Authentication". For more information on Oracle Access Manager, see the Oracle Containers for J2EE Security Guide. |
If you have Oracle Access Manager as part of your deployment, then you can use it as a security provider to integrate with the service's access system. The Oracle Access Manager security provider uses the CoreIDLoginModule login module, supplied by Oracle. The CoreIDLoginModule is defined in the ORACLE_HOME/j2ee/instance/config/system-jazn-data.xml file.
The login module is configured for each application.
On the client, the username token uses the username and password for authentication. Consequently, the Web service must define validation for the username and password using the Oracle Access Manager login module. Once you define the authentication scheme for username and password verification, you must define these variable values in the login module by using the coreid.name.attribute and coreid.password.attribute properties.
To authenticate the name, set the value of the coreid.name.attribute property to the variable name defined for verifying the user name in the credential_mapping plug-in. This property is set as an option under the <login-module> element.
To authenticate the password, set the value of the coreid.password.attribute property to the variable name defined for verifying the password in the validate_password plug-in.
See Also:
For more information on the CoreIDLoginModule and the coreid.password.attribute and coreid.name.attribute properties, see the Oracle Containers for J2EE Security Guide.
Example 3-8 illustrates setting the coreid.name.attribute property to authenticate the user name for the username token. The username_variable value is a variable name used to authenticate the user name in the credential_mapping plug-in.
Example 3-8 Setting the User Name Variable for Oracle Access Manager in the Username Login Module
...
<login-module>
...
<option>
<name>coreid.name.attribute</name>
<value>username_variable</value>
</option>
...
</login-module>
...
Example 3-9 illustrates setting the coreid.password.attribute property to authenticate the password for the username token. The username_password value is a variable name used to authenticate the password in the validate_password plug-in.
Example 3-9 Setting the Password Variable for Oracle Access Manager in the Username Login Module
...
<login-module>
...
<option>
<name>coreid.password.attribute</name>
<value>username_password</value>
</option>
...
</login-module>
...
Example 3-10 illustrates a sample CoreIDLoginModule configuration for a username token in the system-jazn-data.xml file. The value of the <name> element, application_name, represents the name of the Web service application.
Example 3-10 CoreIDLoginModule for Username Token Authentication
<application> <name>application_name</name> <login-modules> <login-module> <class> oracle.security.jazn.login.module.coreid.CoreIDLoginModule </class> <control-flag>required</control-flag> <options> <option> <name>addAllRoles</name> <value>true</value> </option> <option> <name>coreid.resource.type</name> <value>res_type</value> </option> <option> <name>coreid.resource.operation</name> <value>res_operation</value> </option> <option> <name>coreid.resource.name</name> <value>/res_name</value> </option> <option> <name>coreid.name.attribute</name> <value>username_variable</value> </option> <option> <name>coreid.password.attribute</name> <value>username_password</value> </option> </options> </login-module> </login-modules> </application>
If you are using the username token for authentication, then you can employ a nonce to help prevent message replay attacks. A message replay attack occurs when an intermediate listener (a "man in the middle") captures an authenticated and validated message. The intermediate party can replay the captured message over and over again unless there is some means for client and service to uniquely identify a message.
A nonce is a unique random number that is included in the message that helps to uniquely identify the message to the client and server. For example, an application can use a nonce when creating a password digest, as follows:
password_digest = SHA1 (nonce + created + password)
Using a nonce ensures that the application generates a different password digest at every invocation; two nonced digests will differ even if they have identical password and time created values.
A nonce can be added to the username token whether the password type is digest or plain text. To add a nonce, include the add-nonce="true" and add-created="true" attributes to the <username-token> element.
For plain text password type, the add-nonce and add-created attributes are optional.
If you specify the password type as DIGEST, then the add-nonce and add-created attributes are required and will be set to true by default. In the following example, there is no need to specify the add-nonce and add-created attributes; they are implicitly set to true.
<username-token name="jdoe" password="password" password-type="DIGEST"/>
This section describes how to configure the X.509 token for the server and the client. It also describes how to integrate the token with OC4J security providers.
Note:
OracleAS Web Services Security handles X.509 (#X509V3) simple certificate processing only. It does not support certificate path (#X509PK1PathV1) or Set of Certificates and CRLs (#PKCS7).For the server, you configure the X.509 token in the oracle-webservices.xml deployment descriptor. Configuring the X.509 token for the server consists of the following steps:
Map the X.509 Certificates to Valid Users (Optional)
To configure an X.509 token for the server, use the <verify-x509-token> element. The <verify-x509-token> element is a subelement of the <inbound> element. Example 3-11 illustrates a sample X.509 token configuration for the server.
Create a keystore to store the private keys, public keys, and certificates required by the X.509 token. You can use either a Java Key Store (JKS) or Oracle Wallet. For the steps involved in configuring either of these keystores, see "Using Keystores".
The mapping attribute (mapping.attribute) maps an X.509 certificate to a valid user in an XML or LDAP repository. The LDAP repository can be either an Oracle Internet Directory (OID) or an external repository such as Active Directory or iPlanet. The default mapping attribute uses DN or the distinguished name of the X.509 certificate to map the certificate to a user in the LDAP realm.
For an XML provider (jazn-data.xml) the CN or common-name is used by default. The realm will be based on the security provider configuration.
You can customize the mapping by setting mapping.attribute in the bootstrap jazn.xml file (ORACLE_HOME/j2ee/instance_name/config/jazn.xml).
Example 3-12 illustrates using the mapping.attribute attribute to map a user in the LDAP repository to an X.509 certificate based on an email address. The example assumes that the default DN will be used to map the certificate and that the DN has the following definition:
DN = "CN=jdoe, OU=security, O=Oracle, email=jdoe@oracle.com"
The certificate will be mapped to the user with the e-mail address jdoe@oracle.com.
Example 3-12 Mapping a User to an X.509 Certificate
<jazn provider="LDAP" location=".... "> <property name="mapping.attribute" value="email"/> </jazn>
If multiple users are found to match the mapping attribute, then the request is rejected. The value of the mapping.attribute attribute cannot be changed by using Application Server Control.
Table 3-3 describes the default values for the mapping attribute based on the security provider type.
You can use the following tools to configure the X.509 token on the server.
You can configure the X.509 token in the Inbound Policies Authentication Page. For more information, see the context-sensitive help for this page in the Application Server Control online help.
Authentication is set on the Authentication page of the Secure Web Services wizard or the Web Services Editor. For more information, see the topic Setting Authentication for Web Services in the Oracle JDeveloper on-line help.
You can use this tool to assemble a security configuration into your Web service. To do this, follow these general steps:
Include a configuration for the X.509 token in the oracle-webservices.xml deployment descriptor.
Use the ddFileName argument to specify this file as input to the appropriate Web service assembly command.
See Also:
For more information on the ddFileName argument and assembling Web Services, see "Using WebServicesAssembler" in the Oracle Application Server Web Services Developer's Guide.
For the client, you configure the X.509 token in the <generated_name>_Stub.xml deployment descriptor. Configuring the X.509 token for the client consists of the following steps:
Authenticate an X.509 Token with a Subject Key Identifier (Optional)
Sign the X.509 Token (Optional)
To configure the client for the X.509 token use the <x509-token> element. Example 3-13 illustrates a sample configuration.
Create a keystore to store the signature key required by the X.509 token on the client. You can use either a Java Key Store (JKS) or Oracle Wallet to provide this. For the steps involved in obtaining a signature key and for configuring either of these keystores, see "Using Keystores".
For X.509 token authentication, if the receiver has prior knowledge of the X.509 certificate used for authentication, then the subject key identifier can be sent instead of the entire certificate. The subject key identifier is an extension of the certificate which is used to calculate the public key. If your certificate does not have the subject key identifier, then the request will be rejected.
To authenticate with a subject key identifier, make the following changes to the <generated_name>_Stub.xml file.
Set the <property> subelement of the <signature> element to the subject key identifier property oracle.security.wss.signwithski.
Set the value attribute of the <property> subelement to true. By default, this property is set to false.
Example 3-14 illustrates how to use the subject key identifier property oracle.security.wss.signwithski to authenticate an X.509 token.
Example 3-14 X.509 Token with a Subject Key Identifier
<x509-token/> <signature> <property name="oracle.security.wss.signwithski" value="true"/> </signature>
Note:
Configure the signature key in the security configuration to point to the signer's private key. The signer's certificate must have theSubjectKeyIdentifierExtension. Also the receiver's keystore must contain the signer's certificate to resolve the subject key identifier.An unsigned X.509 token is not secure and can be replaced with any other token. You can secure the X.509 token by signing it in outbound messages. To do this, OracleAS Web Services Security defines the boolean oracle.security.wss.signX509token property on the <x509-token>.
This property is applied only when the <x509-token> is used with signature <signature>. If set to true (default), the X.509 token will be signed. If set to false, the X.509 token will not be signed.
For more information on this property, see "X.509 Token Elements for Outbound Messages".
Example 3-15 illustrates how the oracle.security.wss.signX509token property is used in conjunction with the <x509-token> and <signature> elements.
You can use the following tools to configure an X.509 token on the client.
Authentication is set on the Authentication page of the Secure Web Services wizard or the Web Services Editor. For more information, see the topic Setting Authentication for Web Services in the Oracle JDeveloper on-line help.
You can use this tool to assemble a security configuration into your Web service client proxy. To do this, include a configuration for the X.509 token in the <generated_name>_Stub.xml deployment descriptor. Use the ddFileName argument to specify this file as input to the WebServicesAssembler genProxy command. For more information on the ddFileName argument and assembling Web service clients, see "Using WebServicesAssembler" in the Oracle Application Server Web Services Developer's Guide.
Table 3-1 provides a summary of the security providers that can be used with the X.509 security token. All of the security Providers that are available for the X.509 token can be configured by using Application Server Control.
You should configure OC4J with security providers before you configure Web service security. Table 3-4 indicates where you can find additional information on configuring the security providers that are available for the X.509 token.
Table 3-4 Security Providers that can be Used with the X.509 Token
| For this Security Provider type | See this resource for more information |
|---|---|
|
File-Based Security Provider |
For information on how to configure a file-based provider for the X.509 security token, see the Oracle Containers for J2EE Security Guide. |
|
Oracle Identity Management |
For information on how to configure Oracle Identity Management, including Oracle Internet Directory (OID) and Single Sign-on, for the X.509 security token, see the Oracle Containers for J2EE Security Guide. |
|
External LDAP Providers |
For information on how to configure external LDAP providers for the X.509 security token, see the Oracle Containers for J2EE Security Guide. |
|
Oracle Access Manager |
For information on how to configure Oracle Access Manager as a security provider for the X.509 security token, see "Using Oracle Access Manager as a Security Provider for X.509 Token Authentication". For more information on Oracle Access Manager, see the Oracle Containers for J2EE Security Guide. |
If you have Oracle Access Manager access system as part of your deployment, then you can use it as a security provider to integrate with the service's access system. The Oracle Access Manager security provider uses the CoreIDLoginModule login module. The login module is configured for each application. The CoreIDLoginModule is defined in the ORACLE_HOME/j2ee/instance_name/config/system-jazn-data.xml file.
To use Oracle Access Manager with X.509 authentication, configure the Oracle Access Manager login module to use the mapping attribute for the authentication plug-in. Set the coreid.name.attribute property to the value of the CN variable defined for verifying the mapping attribute of in the credential_mapping plug-in. This property is set as an option under the <login-module> element.
See Also:
For more information on the coreid.name.attribute property and the CoreIDLoginModule, see the Oracle Containers for J2EE Security Guide.
Example 3-16 illustrates setting the coreid.name.attribute property in the CoreIDLoginModule to authenticate the mapping for the X.509 token. The cn_variable value is a variable name used to authenticate the mapping.
Example 3-16 Setting the CN Variable for the Oracle Access Manager Login Module for X.509 Authentication
...
<login-module>
...
<option>
<name>coreid.name.attribute</name>
<value>cn_variable</value>
</option>
...
</login-module>
...
Example 3-17 illustrates a CoreIDLoginModule for X.509 token authentication in the system-jazn-data.xml file. The value of the <name> element, application_name, represents the name of the Web service application.
Example 3-17 CoreIDLoginModule for X.509 Token Authentication
<application> <name>application_name</name> <login-modules> <login-module> <class> oracle.security.jazn.login.module.coreid.CoreIDLoginModule </class> <control-flag>required</control-flag> <options> <option> <name>addAllRoles</name> <value>true</value> </option> <option> <name>coreid.resource.type</name> <value>res_type</value> </option> <option> <name>coreid.resource.operation</name> <value>res_operation</value> </option> <option> <name>coreid.resource.name</name> <value>/res_name</value> </option> <option> <name>coreid.name.attribute</name> <value>cn_variable</value> </option> </options> </login-module> </login-modules> </application>
This section describes how to configure the SAML token for the server and the client. It also describes how to integrate the token with OC4J security providers. For information on the SAML token use case, see "SAML Token Profile".
There are three possible usecases for configuring the SAML token on the server, based on which confirmation method you want to employ. These confirmation methods are sender vouches (unsigned), sender vouches (signed), and holder of key.
sender-vouches (unsigned)—the incoming SAML token must supply a sender-vouches confirmation method and the token must not be signed.
sender-vouches (signed)—the incoming SAML token must supply a sender-vouches confirmation method and the reference to the token that must be signed.
holder of key—the incoming SAML token must supply a holder of key confirmation method. The assertion must contain the public key of the user.
The following sections list the steps to configure the SAML token for each of these usecases.
Sender-vouches (unsigned)
Map the SAML Assertion Subject (Optional)
Set Options for the SAMLLoginModule
The issuer name is set to www.oracle.com by default. It is strongly recommended that you change this value to the name of your own assertion issuer.
Sender-vouches (signed)
Set Options for the SAMLLoginModule
The issuer name is set to www.oracle.com by default. It is strongly recommended that you change this value to the name of your own assertion issuer.
Map the SAML Assertion Subject (Optional)
Holder of key
Set Options for the SAMLLoginModule
For the holder-of-key confirmation method, the issuer name, trust point alias, and all of the keystore options in the SAMLLoginModule must be set.
To configure a SAML token for the server, use the <verify-saml-token> element. The <verify-saml-token> element is a subelement of the <inbound> element.
The <verify-saml-token> element can have an optional <subject-confirmation-method> subelement. When used as part of an inbound <verify-saml-token> policy, this subelement refers to the confirmation method used to propagate the identity in the incoming SOAP message.
The actual confirmation method is specified by the <confirmation-method> element. This is a subelement of the <subject-confirmation-method> element. Possible values for <confirmation-method> are SENDER-VOUCHES, SENDER-VOUCHES-UNSIGNED, and HOLDER-OF-KEY.
Example 3-18 provides a sample configuration which uses the <verify-saml-token> element to verify a SAML token. This configuration will accept a SAML token that contains the user's public key. The token itself can be either signed, unsigned, or holder of key.
Example 3-18 Verifying a SAML Token
<verify-saml-token>
<confirmation-methods>
<confirmation-method>SENDER-VOUCHES</confirmation-method>
<confirmation-method>SENDER-VOUCHES-UNSIGNED</confirmation-method>
<confirmation-method>HOLDER-OF-KEY</confirmation-method>
</verify-saml-token>
Table 2-4 and Table 2-6 provide more information on the <verify-saml-token> element and its subelements.
Create a keystore to store the private keys, public keys and certificates required by the SAML token. For a holder of key confirmation method, the keystore must contain the user's trusted certificate for verifying the signature. Additionally, all of the assertion issuer options in the SAMLLoginModule must be configured with Application Server Control. See "Set Options for the SAMLLoginModule" for more information on the SAMLLoginModule options.
For the sender-vouches (signed) confirmation method, the keystore must contain the public key and the trusted certificates. The issuer name option in the SAML login module must also be configured with Application Server Control.
The sender-vouches (unsigned) confirmation method does not require a keystore to be configured.
You can use either a Java Key Store (JKS) or Oracle Wallet as the keystore. For the steps involved in configuring either of these keystores, see "Using Keystores".
By default, SAMLLoginModule is configured with Oracle's assertion issuer. If the name identifier format is omitted or unspecified, then you must configure the mapping.attribute attribute in the jazn.xml (ORACLE_HOME/j2ee/instance_name/config/jazn.xml) file. The value of this attribute cannot be changed by using Application Server Control; you must edit the file manually.
If the SAML token has a name identifier format, then one of the mapping attributes described in Table 3-5 is used. A mapping attribute property is not required. "Configuring SAML Assertion Subject Name and Format" provides a description of the subject name formats.
Table 3-5 Subject Name Identifier Format and Corresponding Mapping Values
| Subject Name Identifier Format | Mapping Attribute in OID | Mapping Attribute in Active Directory | Mapping Attribute in iplanet |
|---|---|---|---|
|
EMAIL_ADDRESS |
|
|
|
|
X509_SUBJECT_NAME |
DN |
DN |
DN |
|
WINDOWS_DOMAIN_NAME |
|
|
not applicable |
|
UNSPECIFIED / OMITTED |
|
|
|
Table 3-6 describes the default values for the mapping.attribute attribute based on the security provider type.
Table 3-6 Values for mapping.attribute Based on Security Provider Types
| Default Property Value | Security Provider Type |
|---|---|
|
CN |
File-based Security provider. |
|
DN |
Oracle Identity Management security provider, external LDAP Provider, and Oracle Access Manager. |
Example 3-19 illustrates using the mapping.attribute property to map a SAML assertion subject to a valid user in an XML repository.
For SAML authentication to succeed, you must configure a trusted SAML assertion issuer as part of the SAMLLoginModule options. The SAMLLoginModule is a system login module that authenticates an incoming SAML token.
The SAMLLogingModule provides options for setting the trusted SAML issuer name, trust point alias, keystore path, keystore type, and password for the trusted SAML issuer. By default, the SAML login module is not configured with a keystore.
You can set the trusted SAML issuer name, keystore, and trust point alias options in the Trusted SAML authority screen in Application Server Control.
Note:
For the holder of key subject confirmation method, the issuer signs the SAML assertion. If you are configuring this method, then you must set the issuer name, trust point alias, and all of the keystore options.Table 3-7 provides descriptions of the SAMLLogingModule options. These options must be configured for each assertion issuer. The variable N in the option name represents the number of the assertion issuer.
Table 3-7 SAMLLoginModule Options
| SAMLLoginModule Options | Descriptions | Required by this Confirmation Method |
|---|---|---|
|
Occurs: 1...N Specifies the keystore password. |
Holder-of-Key |
|
|
Occurs: 1...N Specifies the keystore path where the assertion issuer certificate is stored. |
Holder-of-Key |
|
|
Occurs: 1...N Specifies the assertion issuer keystore type. Default keystore type is |
Holder-of-Key |
|
|
Occurs: 1...N Specifies the issuer name. For the OC4J Standalone |
Holder-of-Key, Sender Vouches |
|
|
Occurs: 1...N Specifies the trust point key alias of the assertion issuer. This setting is used to verify the assertion issuer certificate in Holder-Of-Key subject confirmation cases. |
Holder-of-Key |
For the Web service client, the SAML token can be configured for the sender-vouches (unsigned), sender-vouches (signed), or holder of key confirmation methods. The configuration can be either static, by hard coding the <saml-token> element values in the <generated_name>_Stub.xml file, or set dynamically.
Sender Vouches (unsigned)
Configure the <saml-token> Element.
This configuration can be either static or dynamic. A static configuration involves providing values for SAML elements in the <generated_name>_Stub.xml file. For a dynamic configuration, you can use Stub properties, callback handlers, identity propagation, or SAMLP. For more information on each of these configurations, see the following sections:
Sender vouches (signed)
Configure the <saml-token> Element
The configuration can be either static or dynamic. A static configuration involves providing values for SAML elements in the <generated_name>_Stub.xml file. For a dynamic configuration, you can use Stub properties, callback handlers, identity propagation, or SAMLP. For more information on each of these configurations, see the following sections:
Configure the Keystore with a signature key and certificates.
Holder of key
Configure the <saml-token> Element.
A client-side SAML token configuration for holder of key cannot be static. It must be performed dynamically, either by using a callback handler or SAMLP.
Configure the Keystore with keys and certificates.
A client-side configuration for SAML must provide the following values.
SAML assertion subject name
Assertion subject name format
Name of the assertion issuer
Authentication and attribute statements
You can provide these values either statically or dynamically. For a static configuration, you provide values for SAML elements. For a dynamic configuration, you write a SAML token callback handler.
This section describes how to provide the required values for a static SAML configuration. The client configuration for security appears in the <generated_name>_Stub.xml file.
You can choose a name for the assertion subject by providing a value for the name attribute of <saml-token> element. The name can optionally be prefixed with the assertion's realm name. If the realm name is already present, then it is set as the name qualifier. The name attribute has the following format:
name = [realm-name/]name
The format of the assertion subject's name is specified by setting the name-format attribute. Table 2-14, "Attributes of the <saml-token> Element" describes the possible values for this attribute.
You can configure the assertion issuer name by setting the issuer-name attribute. If no value is specified for this attribute, then the default assertion issuer, www.oracle.com, is used. It is strongly recommended that you change this value to the name of your own issuer. Table 2-14, "Attributes of the <saml-token> Element" provides more information on this element.
Authentication statements are generated by default. If you want to generate attribute statements, add an attributes.properties file containing the attributes of the subject.
Use the path attribute of the attributes element to indicate the location of the attributes.properties file.
<attributes path=<location-of-attributes.properties file >>
The attributes element can be prefixed with an optional name space value.
[attribute-name-space/]name=value
For example:
jazn.com/name=john doe
This section describes the types of confirmation methods supported by OracleAS Web Services Security.
The default confirmation method is sender-vouches (implicit signature).
To configure a sender-vouches (signed) confirmation method, configure the <saml-token> and <signature> elements. Example 3-20 illustrates the configuration for generating a sender-vouches (signed) assertion token. The <signature> element follows the <saml-token> element. The <signature-method> element identifies the signature algorithm. If no algorithm is specified, then the default, RSA-SHA1, is used.
See Table 2-17, "Subelements of the <signature> Element" for a description of the <signature-method> element. Table 2-18, "Signature Algorithms and Short Names" provides a description of the element's possible values.
Example 3-20 Configuration for a Sender-Vouches (Signed) Confirmation Method
<saml-token name="jdoe">
<subject-confirmation-method>
<confirmation-method>SENDER-VOUCHES</confirmation-method>
</subject-confirmation-method>
</saml-token>
<signature>
<signature-method>DSA-SHA1</signature-method>
</signature>
Example 3-21 illustrates the configuration for generating a sender-vouches (unsigned) assertion token. The <confirmation-method> element identifies the type of confirmation used for the unsigned assertion. See Table 2-15, "Subelements of the <saml-token> Element" for a description of the possible values for the <confirmation-method> element.
Example 3-22 illustrates the configuration for sending a holder-of-key assertion using a callback handler. The cbhandler-name attribute identifies the user-defined class that will handle the SAMLTokenCallback callback handler. In this example, mypackage.SAMLTokenCallbackHandler is the user-defined class.
Table 2-15 provides more information on the cbhandler-name attribute. "Writing a SAML Token Callback Handler" provides more information on creating callback handlers for SAML tokens.
If you do not include a <saml-token> element in your configuration, then the client runtime can dynamically build the token using the Stub.USERNAME_PROPERTY supported by JAX-RPC. For more information on using this property, see Table 2-15, "Subelements of the <saml-token> Element".
In the following example, Stub is javax.xml.rpc.Stub and _port is the stub generated by WebServicesAssembler.
((Stub) _port)._setProperty(Stub.USERNAME_PROPERTY, name);
Note:
If you provide a name value in a static configuration file and dynamically set the username withUSERNAME_PROPERTY, then the USERNAME_PROPERTY value will override the value in the static configuration.Identity propagation allows an application to propagate an ID to the Web service. The ID information resides in the assertion subject. You can obtain the assertion subject from the current thread of execution by setting the property oracle.security.wss.propagate.identity to true. This property can be set only at the port level. For example:
<property name="oracle.security.wss.propagate.identity" value ="true"/>
If the property is set to true and an identity already exists, then the identity is propagated to the Web service. If an identity is not associated with the current thread of execution, then the request is rejected. If this property is set to false (default), then the identity is not propagated.
You can write a SAML token callback handler to deliver the assertion to the client interceptor. The callback handler implementation must be able to handle a SAMLTokenCallback object. The SAMLTokenCallback object is bi-directional; this means that the name of the subject for whom the assertion is requested can be retrieved by using the callback getName() method.
Example 3-23 illustrates a sample SAML token callback handler implementation. The getName() method obtains the name of the subject. The getAssertion(subject) method gets the assertion based on the value of subject. These lines are highlighted in bold.
Example 3-23 Sample Implementation of a SAML Token Callback Handler
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import oracle.webservices.security.callback.SAMLTokenCallback;
public class SAMLTokenCallbackHandlerHK implements CallbackHandler {
Callback c = null;
public void handle(Callback[] callbacks) {
try {
if (callbacks == null) {
return;
}
for (int i = 0; i < callbacks.length; i++) {
c = callbacks[i];
if (c instanceof SAMLTokenCallback) {
SAMLTokenCallback sc = (SAMLTokenCallback) c;
String subject = sc.getName();
Document doc = getAssertion(subject);
sc.setXMLToken(
doc.getDocumentElement());
}
}
} catch (Exception e) {
e.printStackTrace();
}
}
public Document getAssertion(String subject) {
//User implementation for getting the
assertion subject
}
}
This section describes how to configure the client to retrieve a SAML token from an external SAML authority. OracleAS Web Services clients can retrieve the token by issuing a SAMLP request. To retrieve the token, you must configure the <saml-authority> element, which is an optional subelement of the <saml-token> element. Table 2-16, "Attributes of the <saml-authority> Element" provides more information on this element.
Example 3-24 illustrates a client configuration that accepts a SAML token from an external SAML authority. The username jdoe and the password password provide authentication to the SAML authority. The <require-signature="true"> indicates that the SAMLP request is signed with the client's signature key. This implies that the client-side keystore must be configured with the appropriate signature keys.
Create a keystore (or use an existing keystore) to store the private keys, public keys and certificates required by the SAML token. For a holder of key or sender-vouches (signed) confirmation method, the keystore must contain the private keys. The sender-vouches (unsigned) does not require a keystore to be configured.
You can use either a Java Key Store (JKS) or Oracle Wallet as the keystore.
See Also:
See "Using Keystores" for the steps involved in configuring the Java Key Store and Oracle Wallet.
You can combine static and dynamic techniques to provide a SAML configuration to the client. For example, you can declare a SAML subject name statically, and then pass it to the callback handler.
See Also:
"Configuring SAML Assertion Subject Name and Format" for information on setting the SAML subject name.
"Writing a SAML Token Callback Handler" for information on writing a SAML callback handler.
Table 3-1 provides a summary of the security providers that can be used with the SAML security token.
You should configure OC4J with security providers before you configure Web service security. Example 3-24 indicates where you can find additional information on configuring the security providers that are available for the SAML token.
Table 3-8 Security Providers that can be Used with the SAML Token
| For this Security Provider Type | See this resource for more Information |
|---|---|
|
File-Based Security Provider |
For information on how to configure a file based provider for the SAML security token, see the Oracle Containers for J2EE Security Guide. |
|
Oracle Identity Management |
For information on how to configure Oracle Identity Management, including Oracle Internet Directory (OID) and Single Sign-on, for the SAML security token, see the Oracle Containers for J2EE Security Guide. See "Configuring Single Sign-on Using SAML" for additional information on how to configure single sign-on for this token. |
|
External LDAP Providers |
SAML tokens can be used with external LDAP providers, but they must be configured manually. These manual steps are described in the following sections: |
|
Oracle Access Manager |
For information on how to configure Oracle Access Manager as a security provider for the token, see "Using Oracle Access Manager as a Security Provider for SAML Token Authentication" For more information on Oracle Access Manager, see the Oracle Containers for J2EE Security Guide. |
If you have Oracle Access Manager as part of your deployment, then you can use it as a security provider to integrate with the service's access system. The Oracle Access Manager security provider uses the CoreIDLoginModule login module supplied by Oracle. The CoreIDLoginModule is defined in the ORACLE_HOME/j2ee/instance_name/config/system-jazn-data.xml file.
Edit the system-jazn-data.xml file so that the Oracle Access Manager login module appears before the SAML login module:
SAMLLoginModule
CoreIDLoginModule
If you enter the modules in reverse order, then the configuration will be invalid. The <control-flag> element must be set to required for both SAMLLoginModule and CoreIDLoginModule. The login modules are configured for each application.
To use Oracle Access Manager with SAML authentication, configure the Oracle Access Manager login module to use the mapping attribute for the authentication plug-in. Set the coreid.name.attribute property to the value of the SAML subject defined for verifying the mapping attribute of in the credential_mapping plug-in. This property is set as an option under the <login-module> element.
See Also:
For more information on this property and the CoreIDLoginModule, see the Oracle Containers for J2EE Security Guide.
Example 3-25 illustrates setting the coreid.name.attribute property to authenticate the SAML subject. The subject_variable value is a variable name used to authenticate the SAML subject in the credential_mapping plug-in.
Example 3-25 Setting the SAML Subject Variable for the Oracle Access Manager Login Module for SAML Authentication
...
<login-module>
...
<option>
<name>coreid.name.attribute</name>
<value>subject_variable</value>
</option>
...
</login-module>
...
Example 3-26 illustrates the SAMLLoginModule and CoreIDLoginModule in the system-jazn-data.xml file. Note that the SAMLLoginModule is listed before the CoreIDLoginModule. The value of the <name> element, application_name, represents the name of the Web service application.
Example 3-26 Using the Oracle Access Manager and SAML Login Modules for SAML Subject Authentication
<application> <name>application_name</name> <login-modules> <login-module> <class> oracle.security.jazn.login.module.saml.SAMLLoginModule </class> <control-flag>required</control-flag> <options> <option> <name>addAllRoles</name> <value>true</value> </option> <option> <name>issuer.name.1</name> <value>www.oracle.com</value> </option> </options> </login-module> <login-module> <class> oracle.security.jazn.login.module.coreid.CoreIDLoginModule </class> <control-flag>required</control-flag> <options> <option> <name>addAllRoles</name> <value>true</value> </option> <option> <name>coreid.resource.type</name> <value>res_type</value> </option> <option> <name>coreid.resource.operation</name> <value>res_operation</value> </option> <option> <name>coreid.resource.name</name> <value>/res_name</value> </option> <option> <name>coreid.name.attribute</name> <value>subject_variable</value> </option> </options> </login-module> </login-modules> </application>
To authenticate an incoming SAML token against an external LDAP Provider, such as Active Directory or iPlanet, SAMLLoginModule and LDAPLoginModule must be configured with the ORACLE_HOME/j2ee/instance_name/config/system-jazn-data.xml file. The modules must be entered into the file in the following order.
SAMLLoginModule
LDAPLoginModule
If you enter the modules in reverse order, then the configuration will be invalid. The <control-flag> element must be set to required for both SAMLLoginModule and LDAPLoginModule. The login modules are configured for each application.
See Also:
For more information on LDAPLoginModule configuration, see the Oracle Containers for J2EE Security Guide.
Example 3-27 illustrates a sample configuration. The SAMLLoginModule, LDAPLoginModule, and <contol-flag> items appear in bold.
Example 3-27 Sample Configuration to Authenticate SAML Tokens for an External LDAP Provider
<application>
<name>MyApplication</name>
<login-modules>
<login-module>
<class>oracle.security.jazn.login.module.saml.SAMLLoginModule</class>
<control-flag>required</control-flag>
<options>
……
</options>
</login-module>
<login-module>
<class>oracle.security.jazn.login.module.LDAPLoginModule </class>
<control-flag>required</control-flag>
<options>
…..
</options>
</login-module>
</login-modules>
</application>
This section describes how to establish Oracle Single Sign-On between a Web application and a Web service deployed on two different containers. It is assumed that both the Web application and the Web service are configured to use SAML.
This scenario assumes that the Web application is deployed on an OC4J container that is associated with Oracle Single Sign-On. When a request arrives at the Web application, it is redirected to Oracle Identity Management where it is authenticated with Oracle Single Sign-On.
The Web application invokes a Web service that uses SAML as its authentication mechanism. The Oracle Single Sign-On identity from the Web application is propagated to the Web service as a SAML assertion. When the Web service application receives the SAML assertion, it verifies the assertion and authenticates the user.
Figure 3-1 illustrates the runtime flow of control between the client, the Web application, and the Web service.
Figure 3-1 Runtime Flow of Single Sign-on Using SAML
The following steps describe the runtime flow between the Web components illustrated in the figure.
The client logs in to the Web application; the Web application uses Oracle Single Sign-On for authentication.
The Web application calls the Web service stub.
The Web service stub invokes the Web service. The stub passes a SAML assertion with the Oracle Single Sign-On identity to the Web service.
The Web service application verifies the assertion and uses Oracle Internet Directory to map the Oracle Single Sign-On identity.
The following steps describe how to configure Oracle Single Sign-On between your Web application and a Web service.
Step 1: Install Oracle Identity Management 10.1.2 and Associate OC4J With It
Step 3b: Integrate the Web application with the Web service client
Step 1: Install Oracle Identity Management 10.1.2 and Associate OC4J With It
Install 10.1.2 Identity Management.
Associate Oracle Identity Management 10.1.2 with OC4J by using Application Server Control.
See Also:
For the instructions on how to configure Oracle Identity Management, see the Oracle Containers for J2EE Security Guide.
Step 2: Configure the Web application to use Single Sign-on
Configure your Web application to use Oracle Single Sign-On by using Application Server Control. For more information on using Application Server Control to configure Oracle Single Sign-on, see the Application Server Control on-line help
See Also:
For the instructions on how to configure Single Sign-On, see the Oracle Containers for J2EE Security Guide.
Step 3a: Assemble and secure the Web service client
Generate the Web service client by using Oracle JDeveloper. In the Security options, choose the SAML sender-vouches confirmation method.
Set the oracle.security.wss.propagate.identity property at the port level to true.
<property name="oracle.security.wss.propagate.identity" value ="true"/>
If this property is set to true, then the Web application authenticated identity is propagated as the SAML subject.
Package your Web service proxy/client keystore with your Web application and deploy them to your Web application in the OC4J container (10.1.3.1 OC4J Container 1 in Figure 3-1).
Step 3b: Integrate the Web application with the Web service client
Get an instance of the Web service stub in the Web application.
Set the Stub.ENDPOINT_ADDRESS_PROPERTY to the actual Web service endpoint address.
Step 4: Assemble and secure the Web service (server side)
Assemble the Web service by using Oracle JDeveloper.
Deploy the Web service application. Bundle the keystore and signature key and deploy it with the application.
Configure your Web service to use SAML sender-vouches confirmation method by using Application Server Control.
Configure the OC4J container containing the Web service (10.1.3.1 OC4J Container 2 in Figure 3-1) to use Oracle Identity Management by using Application Server Control.
Message-level encryption can be configured for a Web service at either the global or port level. The <encryption-key> element points to the key required for decrypting the message. If this element is configured at the global level, then it will point to an encryption key in the global-level keystore. If it is configured at the port level, then it will point to an encryption key in the port-level keystore. If the element is not configured at the port level, then global level values are used.
The <encryption-key> element can possess an alias and a password. Oracle JDeveloper and the command line keystore tools (Oracle Wallet and Java Key Store) give you the option of assigning an alias and password when you create the key.
The following sections provide more information on the encryption and decryption of SOAP messages.
The <encrypt> subelement of the <outbound> element specifies the confidentiality requirements of the sender. The <encrypt> element contains subelements to specify encryption methods and algorithms. You can specify the encryption algorithm that will be used to encrypt the message with the <encryption-method> element. The <keytransport-method> element identifies an algorithm that can be used to encrypt encryption keys for intended recipients. The <use-request-cert> lets the Web service application encrypt the response message with the signature certificate that the client sent in the original request message
The <recipient-key> element provides the alias and password for the recipient's public key. This key must reside in the keystore. The recipient's public key is used to encrypt the data encryption key.
You can use <tbe-elements> to specify the elements in the SOAP message to be encrypted. This element enables you to encrypt the entire message element or only the contents of an element.
See Also:
"Encrypting the Body of a SOAP Message" and "Encrypting Elements of a SOAP Message" provide more information about how to use the <tbe-elements> element for outbound messages.
"Encryption Elements for Outbound Messages" provides more information on all of the subelements of <encrypt>.
For inbound messages, the <decrypt> subelement of the <inbound> element specifies how received messages will be decrypted. You can specify acceptable encryption algorithms for incoming messages with the <encryption-method> element. The <keytransport-method> element identifies acceptable encryption algorithms for encryption keys.
For incoming messages, the <tbe-elements> element indicates which elements are encrypted. "Decrypting Elements of a SOAP Message" provides more information about how to use the <tbe-elements> element for inbound messages. The recipient's private key used for decryption must be present in the keystore.
The decryption key alias must be configured in the <encryption-key> element of the <keystore> element.
See Also:
"Configuring a Keystore" provides more information on configuring a keystore.
"Decryption Elements for Inbound Messages" provides more information on the configuration elements used for decryption.
The SOAP message body can be encrypted with Application Sever Control or with Oracle JDeveloper. An entry is created for the message body in the <tbe-element> element with Body as the value of the local-part attribute and CONTENT as the value of the mode attribute. Table 2-19, "Subelements of the <encrypt> Element" provides more information on these elements and attributes.
Note:
If you are encrypting the SOAPBody element, the mode attribute must be set to CONTENT.Example 3-28 illustrates a sample entry under the <tbe-element> element that will encrypt the SOAP message body.
The SOAP message body can be decrypted with Application Sever Control or with Oracle JDeveloper. An entry is created for the message body in the <tbe-element> element with Body as the value of the local-part attribute and CONTENT as the value of the mode attribute. Table 2-8, "Subelements of the <decrypt> Element" provides more information on the these elements and attributes.
Note:
If you are decrypting the SOAPBody element, the mode attribute must be set to CONTENT.Example 3-29 illustrates a sample entry under the <tbe-elements> element that will decrypt the SOAP message body.
Any part of the SOAP message can be encrypted by adding a <tbe-element> element with the name-space and local-part attributes. If only one element exists in the SOAP message with that specific name, then you can omit the name space.
By default, only the content of the element is encrypted. To encrypt the entire element, set the mode attribute to ELEMENT.
Example 3-30 illustrates the code for encrypting a user name token.
To decrypt a specific element, specify the <tbe-element> with name-space and local-part attributes. By default, only the content of the element is decrypted. To decrypt the entire element, set the mode attribute to ELEMENT.
If the element is not encrypted in the incoming request, then the request will be rejected.
Example 3-31 illustrates the code to decrypt a UsernameToken element.
When the Web service application sends a response back to the same client, it can choose to encrypt the response with the signature certificate that the client sent in the first message exchange. Note that this assumes that during the first message exchange the Web service client sent a signed SOAP message and the Web service application successfully verified the signature.
To allow the application to encrypt the response with the client's signature certificate, configure the <use-request-cert> element as part of a Web service application's outbound encryption policy. Note that if the server interceptor is unable to find the signature certificate (that is, the client has not sent a signed SOAP message or the signature verification failed) then the Web service application will reject the encryption request.
The default behavior of a service defined under OracleAS Web Services is to accept only one encryption key for the decryption of messages. The boolean property oracle.security.wss.decryptusingski, which is set on the <decrypt> element, allows a Web service to decrypt a message that could have been encrypted with any one of a number of keys.
If the decryptusingski property is set to true, then the subject key identifier in the <encryption-key> element in the received message is resolved to a private key in the keystore. If this property is set to false, then the Web service will accept only one encryption key to decrypt messages. By default, this property is set to false.
The following steps describe how to set up the private key in the keystore and the user account to access the key.
Add the private key used for decryption to the keystore configured in the <keystore> element of the security configuration.
Create a user account in ORACLE_HOME/j2ee/instance_name/config/system-jazn-data.xml using Application Server Control. The username must be of the type:
application-name.portname.key.<decryption-key-alias>
For example, to create a decryption key for the SecureService application with port SecurePort and alias deckey, the user name would be the following:
SecureService.SecurePort.key.deckey
The password would be the decryption key password.
See Also:
See Table 2-8, "Subelements of the <decrypt> Element" for more information on the oracle.security.wss.decryptusingski property.
Example 3-32 illustrates the use of the oracle.security.wss.decryptusingski property.
Message-level signature can be configured for a Web service at either the global or port level. The <signature-key> element points to the key required for signing the message. If this element is configured at the global level, then it will point to a signature key in the global-level keystore. If it is configured at the port level, then it will point to a signature key in the port-level keystore. If the element is not configured at the port level, then global level values are used. To verify a signature, the trusted root certificate must reside in the keystore. If you are using self-signed certificates, then you can specify an alias in the <signature-key> element.
The <signature-key> element can possess an alias and a password. Oracle JDeveloper and the command line keystore tools (Oracle Wallet and Java Key Store) give you the option of assigning an alias and password when you create the key.
The following sections provide more information on signing and verifying the signatures on SOAP messages.
The <signature> subelement of the <outbound> element specifies the options that are available for signing outbound messages. You can specify the algorithms that will be used to sign the message with the <signature-method> element.
You can use <tbs-elements> to specify the elements in the SOAP message to be signed. This element enables you to sign the entire message element or only the contents of an element.
The <add-timestamp> element enables you to an additional level of security by adding a timestamp to the signature. This timestamp is verified by the <verify-timestamp> element for incoming messages.
See Also:
"Signing the Body of a SOAP Message" and "Signing Elements of a SOAP Message" provide more information about how to use the <tbs-elements> element for outbound messages.
"Preventing Replay Attacks with Timestamps" provides more information on how timestamps can be used to help prevent replay attacks.
For inbound messages, the <verify-signature> subelement of the <inbound> element specifies how the signatures on received messages will be verified. You can specify acceptable signature algorithms for incoming messages with the <signature-method> element.
The <verify-timestamp> element defines an expiration time on the signature and whether a creation time has been included. This timestamp element is configured with the <add-timestamp> element defined for signing outgoing messages.
For incoming messages, the <tbs-elements> element indicates which elements of the message are signed.
An additional property, clock-skew, can also be defined for incoming messages. The clock skew value. This property enables you to specify an allowable clock difference between the client and the server.
See Also:
"Verifying a Signature on a Specific Element" provides more information about how to use the <tbs-elements> element for inbound messages.
"Signature Verification Elements for Inbound Messages" provides more information on verification elements and their attributes.
A digital signature can be applied to the SOAP message body by using Application Sever Control or Oracle JDeveloper. For more information, see the topics Implementing WS-Security for Web Services in the Oracle JDeveloper on-line help or Configuring Security for a Web Service in the Application Server Control on-line help.
Any part of a SOAP message can be signed by adding a <tbs-element> element with the name-space and local-part attributes to identify the element. If only one element exists in the SOAP message with the specified name, then you can omit the name-space attribute.
Example 3-33 illustrates the code for signing a UsernameToken element in a SOAP message.
Example 3-33 Signing a SOAP Message Element
<signature> <tbs-elements> <tbs-element name-space=http://docs.oasis-open.org/wss/2004/01/oasis-2004-01-wss-wssecurity-sec-ext-1.0.xsd local-part="UsernameToken"/> </tbs-elements> </signature>
You can sign and encrypt the SOAP Body element with Oracle JDeveloper or Application Server Control. For all other elements, you must edit the oracle-webservices.xml and <generated_name>_Stub.xml files manually.
To verify a signature on a specific element, specify the <tbs-element> element with name-space and local-part attributes. If the element is not signed in the incoming request, then the request will be rejected.
Example 3-34 illustrates the code for verifying a signed user name token.
If the receiver of the signed message has prior knowledge of the signer's public key certificate, then instead of sending the entire certificate in the message, you can send the certificate's subject key identifier. The subject key identifier is an extension of the certificate which is used to calculate the public key. If your certificate does not have the subject key identifier, then the request will be rejected.
To sign with subject key identifier, set the property element in the signature to oracle.security.wss.signwithski, and set the value attribute to true. By default, this property is set to false.
Example 3-35 illustrates how to set the subject key identifier oracle.security.wss.signwithski property in the <property> subelement.
Example 3-35 Signing a Message Body with a Subject Key Identifier
<signature>
<tbs-elements>
<tbs-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/>
</tbs-elements>
<property name="oracle.security.wss.signwithski" value="true"/>
</signature>
Note:
Configure the signature key in the security configuration to point to the signer's private key. The signer's certificate must have theSubjectKeyIdentifierExtension. Also, the receiver's keystore must contain the signer's certificate to resolve the subject key identifier.Applications can use timestamps to prevent replay attacks. A timestamp can be used to protect messages by identifying an expiration time after which the message is no longer valid. Validation is performed by the receiving Web service.
To account for any time differences between the client and the server, you can configure the clock-skew property in the <verify-signature> element. For more information on this property, see Table 2-7, "Subelements of the <verify-signature> Element".
The <add-timestamp> subelement of the <signature> element enables you to add a timestamp to outgoing SOAP messages. To enhance message security, the expiry attribute enables you to set an expiration time on the signature; the created attribute inserts the signature creation time.
Example 3-36 illustrates a configuration for adding a timestamp to outbound messages. According to the configuration, the outbound message includes a creation time in the timestamp, and the signature should be considered valid for 3000 seconds (50 minutes) after it is sent.
The <verify-timestamp> subelement of the <verify-signature> element enables you to verify the timestamp placed on inbound SOAP messages. The <verify-timestamp> subelement has two attributes, expiry and created. The expiry time sets the expiration time on the freshness of the message. If the message arrives after the expiration time, the message is rejected. If the created attribute is set to true, then the timestamp on the SOAP message is checked to see if it includes a creation time. If the creation time is not included then the message is rejected.
Example 3-37 illustrates configuration of the verify timestamp. According to the configuration, an inbound message is expected to contain a creation time in its timestamp and the signature should be accepted if message arrives within 28800 seconds (8 hours) of when it is sent.
OracleAS Web Services Security provides a way to synch-up any time differences between the client and a Web service application when they are running on different machines. This is a useful function when SOAP messages with timestamps are being passed.
For example, the client which runs on one machine signs a SOAP message, adds a timestamp, and sends it to the Web Service application. The application, which runs on a separate machine, receives the message and verifies the signature and the timestamp. If the clocks on the two machines are not in sync, there will be a mismatch between the timestamps and the message will be rejected.
Web Services Security provides a clock-skew property on the <verify-signature> element which will sync-up time differences between the two machines. The default value of clock-skew is 0 and the units are measured in milliseconds.
Example 3-38 illustrates setting the clock skew between the client and Web service application to three seconds.
Example 3-38 Setting Clock Skew Between the Client and Web Service Application
...
<verify-signature>
<signature-methods>
<signature-method>
RSA-SHA1
</signature-method>
</signature-methods>
<property name="clock-skew" value="3000"/>
<verify-timestamp expiry="28800" created="true"/>
...
</verify-signature>
...
You can combine security tokens, encryption, and signature in a server and client configuration in any combination. The configurations for the client and server must be compatible. As an example, this section illustrates how you can configure the client side and server side deployment descriptors to use a SAML token for authentication with encryption and signature.
Example 3-39 illustrates a configuration for the client side deployment descriptor, <generated_name>.Stub.xml. The configuration uses the SAML token for authentication, and the message body and SAML assertion are signed for integrity protection. The message body is encrypted to provide message confidentiality. This can be configured using Oracle JDeveloper.
By default, the SAML subject confirmation method is sender-vouches (signed). A SAML assertion is generated for the user identity jdoe with sender-vouches confirmation. The assertion is signed using the signature key with the alias signkey.
The message body is signed using signkey and a timestamp is added for message freshness with the expiration time set to 3000 seconds. The default signature algorithm RSA-SHA1 is used for signing. The message body is also encrypted with the recipient's key that has the alias enckey. The default encryption algorithm is AES-128 and the default key transport algorithm is RSA-1_5. The signature and the recipient's key are stored in mykeystore.jks.
Example 3-39 Client-Side Deployment Descriptor Configured for SAML Token, Encryption, and Signature
<oracle-webservice-clients>
<webservice-client>
<port-info>
<runtime enabled="security">
<security>
<key-store path="./mykeystore.jks" store-pass="password"/>
<signature-key alias="signkey" key-pass="password"/>
<outbound>
<saml-token name="jdoe"/>
<signature>
<tbs-elements>
<tbs-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/>
</tbs-elements>
<add-timestamp created="true" expiry="3000"/>
</signature>
<encrypt>
<recipient-key alias="enckey"/>
<tbe-elements>
<tbe-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/>
</tbe-elements>
</encrypt>
</outbound>
</security>
</runtime>
<operations>
<operation name="sayHello">
</operation>
</operations>
</port-info>
</webservice-client>
</oracle-webservice-clients>
The server decrypts the message, verifies the signature on the message body and the assertion, and then authenticates the user using the SAML token.
Example 3-40 illustrates the complimentary configuration for the server side deployment descriptor, oracle-webservices.xml. This configuration can also be created by using Oracle JDeveloper.
The message body is decrypted using the private key with alias deckey. The signature is verified (both body and assertion signature) using the public key attached in the SOAP message. The trusted CA certificates are verified using the keystore mykeystore.jks. The user is authenticated and a subject is created for the user jdoe. The sender's public key certificate and trusted certificates, as well as the recipient's public key certificate for decryption are stored in mykeystore.jks.
Note:
The subject confirmation method in the<verify-saml-token> element can be omitted. If it is present, it must match either the subject confirmation in the <saml-token> element or the default value.Example 3-40 Server-Side Deployment Descriptor Configured for SAML Token, Encryption, and Signature
<oracle-webservices>
<webservice-description name="SecureService">
<port-component name="SecurePort">
<runtime enabled="security">
<security>
<key-store path="./mykeystore.jks" store-pass="password"/>
<signature-key alias="signkey" key-pass="password"/>
<encryption-key alias="deckey" key-pass="password"/>
</security>
</runtime>
<operations>
<operation name="sayHello">
<runtime>
<security>
<inbound>
<verify-saml-token>
<subject-confirmation-methods>
<confirmation-method>SENDER-VOUCHES</confirmation-method>
</subject-confirmation-methods>
</verify-saml-token>
<verify-signature>
<tbs-elements>
<tbs-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/>
</tbs-elements>
</verify-signature>
<decrypt>
<tbe-elements>
<tbe-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/>
</tbe-elements>
</decrypt>
</inbound>
</security>
</runtime>
</operation>
</operations>
</port-component>
</webservice-description>
</oracle-webservices>
|
 Copyright © 2006, 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|