Oracle® Application Server Web Services Security Guide 10g (10.1.3.1.0) Part Number B28976-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.
|
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:
|
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 |
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:
|
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 |
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 |
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 |
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:
|
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 |
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 |
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:
|
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:
|
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 |
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:
|
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:
|
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>