Skip Headers

Oracle® Application Server Web Services Security Guide 10g Release 3 (10.1.3) B15979-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 2 Configuring Web Service Security

This chapter describes the client- and server-side configurations for Web services security. These security configurations are stored in XML files. On the server, this configuration is stored in the `oracle-webservices.xml` deployment descriptor file. On a client, it is stored in the `<``generated_name``>_Stub.xml` deployment descriptor file.

You can create these files and configure the security elements in any of the following ways:

- JDeveloper IDE—Use the JDeveloper IDE to create and configure Web service and client security. This tool provides wizards that help you create a security configuration. It stores the results in an `oracle-webservices.xml` deployment descriptor for the server and a `<``generated_name``>_Stub.xml` deployment descriptor for the client.

- Application Server Control—Use Application Server Control to configure security for all of the operations in a particular Web services port, or configure specific security settings for individual operations in the port. For more information, see the topic Configuring Security for a Web Service in the Application Server Control on-line help.

- WebServicesAssembler—Use this command line tool to configure and assemble the security elements in the Web service and client.

- Manual configuration—To manually configure security, enter values for the security elements directly in the server and client deployment descriptor files.

The Web services security configuration for the client and server is based on inbound and outbound policies. These policies are defined in "Security Policies".

Figure 2-1 illustrates the deployment descriptors that are generated when you configure Web service security and how information is passed to the client and service. The following steps correspond to the numbers in the figure.

1. The security configuration for a Web service client. Configuring security for a client will generate the `<``generated_name``>_Stub.xml` deployment descriptor with a security configuration. The client interceptor uses the `<``generated_name``>_Stub.xml` deployment descriptor at runtime to generate the security header (if an `<outbound>` element is configured) and enforce the security policy (if an `<inbound>` element is configured).

2. The security configuration for a Web service (server side). Configuring security for the Web service application will generate an `oracle-webservices.xml` deployment descriptor with the security configuration.

3. When you deploy the Web service, the `wsmgmt.xml` file will be updated with the Web service security configured in the `oracle-webservices.xml` deployment descriptor as described in Step 2. The `wsmgmt.xml` file is an instance-level configuration file, which holds the entire security configuration for the Web services deployed in an OC4J instance. The server interceptor uses the `wsmgmt.xml` file at runtime to enforce the security policy (if an inbound element is configured) or generate the security header (if an outbound element is configured).

   Note: Oracle Application Server Web Services Security recommends that you do not directly edit the `wsmgmt.xml` file.

In the diagram, the dashed boxes indicate that for a given `<outbound>` element in the Web service client configuration, there is a corresponding `<inbound>` element in the Web service configuration. Similarly for a given `<outbound>` element in the Web service there is a corresponding `<inbound>` element in the client configuration file.

For example in the client `<outbound>` element there is a `<username-token>` element that indicates that client will be sending the username token. In the Web service `<inbound>` element there is corresponding `<verify-username-token>` element which indicates that the Web service must verify the username token.

Figure 2-1 How Policies Work Together for Client- and Server-side Web Services

Description of "Figure 2-1 How Policies Work Together for Client- and Server-side Web Services"

## Security Configuration Elements

This section provides definitions of the security configuration elements. The same set of security elements can appear at the global, port, and operation level. The values for security elements set at the operation level override settings made at the port and global levels. Port-level settings override global-level settings.

In general, OracleAS Web Services Security elements appear in the header or body of SOAP messages. The client uses the same set of security elements as the server. Example 2-1 illustrates the security elements as they are used in the server-side `oracle-webservices.xml` deployment descriptor.

Example 2-1 Security Elements in the Server-Side Configuration File

    <oracle-webservices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/oracle-webservices-10_0.xsd">
     <webservice-description name="XYZService ">
    <port-component name="XYZPort">
      <runtime enabled="security">
        <security>
          <key-store store-pass="abc" path="./mykeystore.jks"/>
          <signature-key alias="signkey" key-pass="signkeypass"/>
          <encryption-key alias="enckey" key-pass="enckeypass"/>
        </security>
      </runtime>

      <operations>
        <operation name="sayHello" input="{http://tempuri.org/}/sayHello">
          <runtime>
            <security>
              <inbound>
                <verify-username-token />
                <verify-x509-token />
                <verify-saml-token/>
                <verify-signature>
                  <signature-methods>
                    <signature-method>
                      RSA-SHA1
                    </signature-method>
                  </signature-methods>
                  <tbs-elements>
                    <element name-space="http://schemas.xmlsoap.org/soap/envelope"
                       local-part="Body"/>
                  </tbs-elements>
                  <verify-timestamp expiry="28800" created="true"/>
                </verify-signature>
                <decrypt>
                  <encryption-methods>
                    <encryption-method>
                      3DES
                    </encryption-method>
                  </encryption-methods>
                  <keytransport-methods>
                    <keytransport-method>
                      RSA-1_5
                    </keytransport-method>
                  </keytransport-methods>
                  <tbe-elements>
                    <element name-space="http://schemas.xmlsoap.org/soap/envelope"
                          local-part="Body" mode="CONTENT"/>
                  </tbe-elements>
                </decrypt>
              </inbound>

              <outbound>
                <signature>
                  <tbs-elements>
                    <tbs-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/>
                  </tbs-elements>
                </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>
        </operation>
      </operations>
    </port-component>
    </webservice-description>
    </oracle-webservices>

Example 2-2 illustrates the security elements as they are used in the client-side `<``generated_name``>_Stub.xml` deployment descriptor.

Example 2-2 Security Elements in the Client-Side Configuration File

    <oracle-webservice-clients>
    <webservice-client>
    <port-info>
    <runtime enabled="security">
     <key-store path="mykeystore.jks" store-pass="password"/>
              <signature-key alias="signkey" key-pass="signkeypass"/>
     <security>
      <outbound>
       <username-token name="SCOTT" password="TIGER"/>
    <signature>
                <tbs-elements>
                 <tbs-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/>
                </tbs-elements>
                <add-timestamp created="true" expiry="28800"/>
               </signature>
               <encrypt>
                <recipient-key alias="reckey"/>
                <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"/>
    </operations>
    </port-info>
    </webservice-client>
    </oracle-webservice-clients>

### Keystore Elements

The `<key-store>` element is required and can occur at both global and port levels on the server, and at port level on the client. A global keystore setting applies to all applications deployed within the instance; it can be overridden by a specific port-level keystore. If you make any changes to the value of the `<key-store>` element, then you must restart the application to enable the new values.

Table 2-1 Keystore Settings

Element Name | Description
--- | ---
<key-store> | Identifies the path to the keystore. This element can appear at global or port level. This element has these attributes: `path`—File system path to the keystore. This can be an absolute or relative path. On server, the relative path is relative to the application root directory: `J2EE_HOME/``applications/``application_name`. On the client, the path can be either absolute or relative to `J2EE_HOME` when the client application is deployed on OracleAS Web Services. `type`—Keystore type. The default type is `JKS`. Other supported types are `PKCS12` and `ORACLE_WALLET`. `store-pass`—Password to access the keystore.

### Signature and Encryption Key Elements

The `<signature-key>` and `<encryption-key>` are required at port level if a port level keystore is specified or when selecting keys from global keystore. If these keys are not configured at the port level, then the global-level values are used.

If you make any changes to the values of the `<signature-key>` or `<encryption-key>` elements, then you must restart the application to enable the new values.

Table 2-2 General Security Settings

Element Name | Description
--- | ---
<signature-key> | Points to the key required by `<signature>` and `<verify-signature>`. This element has these attributes: `alias`—Alias for the key. `key-pass`—Password to access the key.
<encryption-key> | Points to the key required for decrypting the message. This element has these attributes: `alias`—Alias for the key. `key-pass`—Password to access the key. The `<encryption-key>` element is configured as part of the `alias` attribute of the `<recipient-key>` subelement of the `<encrypt>` element. For more information on the `alias` attribute and `<recipient-key>`, see Table 2-18, "Subelements of the <encrypt> Element".

### Nonce Configuration Elements

A nonce is a random value that can be included in the username token to prevent replay attacks. The nonce is cached by the server. OracleAS Web Services Security lets you configure a nonce value that can be inserted into the username token. For more information on configuring the nonce, see "Configure the Nonce Cache with a Digest Password".

Table 2-3 Nonce Configuration Settings

Element Name | Description
--- | ---
<nonce-config> | The `nonce-config` element allows you to configure the cache. `clock-skew`—The amount of clock skew, in seconds, that is allowed between the client and server if the creation time is included in the username token. The default is 300 seconds. `cache-ttl` (cache time to live)—Indicates how long the nonces remain valid in the cache. Expired nonces are removed from the cache. Default is 300 seconds.

### Security Elements for Inbound Messages

The following sections describe the security elements that can be set for inbound messages.

- Username Token Elements for Inbound Messages

- X.509 Token Elements for Inbound Messages

- SAML Token Elements for Inbound Messages

- Signature Verification Elements for Inbound Messages

- Decryption Elements for Inbound Messages

The inbound message section in the `oracle-webservices.xml` and `<``generated_name``>_Stub.xml` deployment descriptors are delimited with `<inbound>` elements. The `<inbound>` element encapsulates the security configuration policy with respect to incoming messages. The `<inbound>` element can occur as a subelement of `<security>` at the global, port, and operation level.

Inbound security defines the context-specific security policy for the incoming messages. In the case of a client, it corresponds to the security policy associated with receiving a response. In the case of a service, it corresponds to the security policy associated with receiving a request.

The `<verify-username-token>`, `<verify-x509-token>`, and `<verify-saml-token>` elements are the authentication elements for inbound messages. Authentication elements are optional and can be configured for the server side. The Web service application can choose to allow a username token, an X.509 token, and a SAML token, in any combination.

A Web service client is not required to send an authentication token. If an authentication token is required, only one can be sent. The user will be authenticated based on the token(s) sent in the SOAP request.

Table 2-4 summarizes the security tokens that can be inserted into an inbound message configuration.

Table 2-4 Authentication Elements for Inbound Messages

Element Name | Description
--- | ---
<verify-username-token> | Specifies the security policy for username tokens. See "Username Token Elements for Inbound Messages" for more information on this security token.
<verify-x509-token> | Specifies the authentication policy with respect to X.509 tokens. See "X.509 Token Elements for Inbound Messages" for more information on this security token.
<verify-saml-token> | Specifies whether the incoming SOAP message carrying a SAML assertion should be verified. See "SAML Token Elements for Inbound Messages" for more information on this security token.

#### Username Token Elements for Inbound Messages

The `<verify-username-token>` element specifies the security policy for username tokens. This is an optional subelement of the `<inbound>` element and can occur only once within the element. This subelement has these attributes:

- `password-type`—Type of password authentication: `plaintext` or `digest`. Default is `plaintext`.

- `require-nonce`—Specifies whether a nonce must be included in the username token. This attribute is required for digest authentication. Default is `false`.

- `require-created`—Specifies whether the creation time must be included in the username token. This attribute can be used with either plain text or digest password authentication. However, it is required for digest authentication. Default is `false`.

#### X.509 Token Elements for Inbound Messages

The `<verify-x509-token>` element specifies the authentication policy with respect to X.509 tokens. It is an optional subelement of the `<inbound>` element.

#### SAML Token Elements for Inbound Messages

The `<verify-saml-token>` element is an optional subelement of the `<inbound>` element. It specifies whether the incoming SOAP message carrying a SAML assertion should be verified.

Table 2-5 lists the subelements of the `<verify-saml-token>` element. All of the subelements are optional.

Table 2-5 Subelements of the <verify saml-token> Element

Element Name | Description
--- | ---
<subject-confirmation-method> | This is an optional element for inbound policy. When used as part of the inbound `<verify-saml-token>` policy, it refers to the confirmation method used for propagating the identity in the incoming SOAP message.
<confirmation-method> | This is an optional element for the `<subject-confirmation-method>`. The possible values for `<confirmation-method>` are: `Sender-Vouches`—(default) The incoming SAML token must supply a sender-vouches confirmation method and the reference to the token must be signed. `Sender-Vouches-Unsigne`d—The incoming SAML token must supply a sender-vouches confirmation method and the token must not be signed. `Holder-Of-Key`—The incoming SAML token must supply a holder-of-key confirmation method. The assertion must have the public key of the user.

#### Signature Verification Elements for Inbound Messages

The `<verify-signature>` element is an optional subelement of the `<inbound>` element. It specifies the integrity or signature requirements of the receiver. These requirements include the name of the signature verification algorithm and the message parts to be verified. The `<verify-signature>` element occurs only once within the `<inbound>` element. Table 2-6 lists the subelements of the `<verify-signature>` element. All of the subelements are optional.

Table 2-6 Subelements of the <verify-signature> Element

Element Name | Description
--- | ---
<signature-methods> | Collection of `<signature-method>` elements. The `<signature-method>` is used to specify the acceptable signing algorithms. Algorithm names are specified using their short names instead of URIs. The default value is `RSA-SHA1`. Table 2-17, "Signature Algorithms and Short Names" lists the algorithm URIs and corresponding short names that are recognized by Web service security.
<tbs-elements> | List of elements that are expected to be signed in the incoming request. This element has these attributes: `local-part`—The actual element name. `name-space`—The actual name space of the element in the SOAP message. This attribute can be omitted if there is only one element with this name in the namespace.
<verify-timestamp> | Verifies the timestamp in the incoming SOAP message. (This timestamp is configured with the `<add-timestamp>` element described in Table 2-16). The `created` attribute is used to indicate whether a timestamp was created for the message. Incoming SOAP messages with a timestamp that has expired are rejected by the server. `expiry`—Expiration time, in seconds, on the signature. Default is 28800 seconds. `created`—Indicates whether the timestamp includes the creation time. Default is `true`.
<property> | Properties that can be set on the `<verify-signature>` element. The `<property>` subelement has this format: `<property name="``property_name``" value="``property_value``"/>` OracleAS Web Services Security defines the following property on `<verify-signature>`. `clock-skew`—Configures the clock difference between the client and the server. The client that is sending the SOAP message (signing and adding a timestamp) and the Web service application (receiving the SOAP message and verifying the signature and the timestamp) may be running on two separate machines. If the clocks on the machines are not in sync, then `clock-skew` is configured to sync-up the time between them. The default value of `clock-skew` is `0` and the units are measured in milliseconds. The following example sets the clock skew to three seconds. `<property name="clock-skew``" value="``3000``"/>` This property can be set in either the `oracle-webservices.xml` or `<``generated_name``>_Stub.xml` deployment descriptor. There is no tool support for adding this property; you must manually edit the files.

#### Decryption Elements for Inbound Messages

The `<decrypt>` element is an optional subelement of the `<inbound>` element. It specifies the confidentiality requirements of the receiver. The `<decrypt>` element occurs only once within an `<inbound>` element.

Table 2-7 describes the elements that are available to set decryption details for inbound messages. All of the subelements are optional.

Table 2-7 Subelements of the <decrypt> Element

Element Name | Description
--- | ---
<encryption-methods> | Encryption methods as part of decrypt element refer to the encryption methods accepted by the Web service application. A Web service application can accept multiple encryption methods. If the incoming SOAP message is encrypted the server interceptor checks the confidentiality policy and rejects the request if the encryption algorithms do not match. The valid options are: `3DES` `AES-128` (default) `AES-256` Table 2-8 lists the encryption algorithm URIs and corresponding short names recognized by Web services security.
<keytransport-methods> | Collection of `<keytransport-method>` elements. Each `<keytransport-method>` specifies the acceptable key transport algorithms. Multiple `<keytransport-method>` elements can be specified for inbound messages. Algorithm names are specified using their short names instead of URIs. Acceptable values are: `RSA-1_5` (default) `RSA-OAEP-MGF1P` Table 2-9 lists the algorithm URIs and corresponding short names recognized by Web services security.
<tbe-elements> | Indicates the elements that are encrypted in the incoming SOAP message. `name-space`—The actual name space of the element in the SOAP message. This attribute can be omitted if there is only one element with this name in the namespace. `local-part`—The actual element name. `mode`—An additional attribute that is used to specify whether the `ELEMENT` or the `CONTENT` is expected to be encrypted. If mode is `ELEMENT` then the entire element is expected to be encrypted, if mode is `CONTENT` then the content of the element is expected to be encrypted. Default is `CONTENT`.
<property> | Properties that can be set on the `<decrypt>` element. The `<property>` subelement has this format: `<property name="``property_name``" value="``property_value``"/>` OracleAS Web Services Security defines the following property on `<decrypt>`. `oracle.security.wss.decryptusingski` When set to `true`, the subject key identifier in the encrypted key tag is resolved to a private key in the keystore. By default, this property is set to `false`. For example: `<property name="``oracle.security.wss.decryptusingski``" value="``true``"/>` Note: This property can be set in either the `oracle-webservices.xml` or `<``generated_name``>_Stub.xml` deployment descriptor. There is no tool support for adding this property; you must manually edit the files. The decryption key alias and password is stored in the `system-jazn-data.xml` file using password indirection. See "Replacing Cleartext Passwords by Using Password Indirection" for more information on the password indirection mechanism.

Table 2-8 lists the URIs of the encryption algorithms recognized by Web service security and their short names.

Table 2-8 URIs and Short Names for Encryption Algorithms

URI of the Algorithm | Short Name
--- | ---
http://www.w3.org/2001/04/xmlenc#3des-cbc | 3DES
http://www.w3.org/2001/04/xmlenc#aes128-cbc | AES-128 (default)
http://www.w3.org/2001/04/xmlenc#aes256-cbc | AES-256

Table 2-9 lists the URIs of the key transport algorithms recognized by Web service security and their short names.

Table 2-9 URIs and Short Names for Key Transport Algorithms

URI of the Algorithm | Short Name
--- | ---
http://www.w3.org/2001/04/xmlenc#rsa-1_5 | RSA-1_5 (default)
http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p | RSA-OAEP-MGF1P

### Security Elements for Outbound Messages

The following sections describe the security elements that can be set for outbound messages.

- Username Token Elements for Outbound Messages

- X.509 Token Elements for Outbound Messages

- SAML Token Elements for Outbound Messages

- Elements for Retrieving SAML Tokens from an External SAML Authority

- Signature Elements for Outbound Messages

- Encryption Elements for Outbound Messages

The outbound message section in the `oracle-webservices.xml` and `<``generated_name``>_Stub.xml` deployment descriptors are delimited with `<outbound>` elements. Outbound security defines the context-specific security policy for the outgoing messages. In the case of a client, it corresponds to the security policy associated with sending a request. In the case of a service, it corresponds to the security policy associated with sending a response.

Example 2-2 summarizes the security tokens that can be inserted into an outbound message configuration.

Table 2-10 Outbound Security Tokens

Element Name | Description
--- | ---
<username-token> | Specifies a username token that must be inserted into the security header block. See "Username Token Elements for Outbound Messages" for more information on this security token.
<x509-token> | If this element is present, an X.509 certificate is inserted into the security header block. See "X.509 Token Elements for Outbound Messages".
<saml-token> | The client interceptor uses the contents of this element to create the SAML assertion for the user identity. See "SAML Token Elements for Outbound Messages" for more information on this security token.
<signature> | Specifies the algorithm for signing outgoing messages or individual message elements. See "Signature Elements for Outbound Messages" for more information on this security token.
<encryption> | Specifies the encryption algorithm, key transport algorithm, and recipient key for encrypting outgoing messages or message elements. See "Encryption Elements for Outbound Messages" for more information on this security token.

#### Username Token Elements for Outbound Messages

The `<username-token>` element is an optional element of the outbound policy. This element specifies the username token that must be inserted into the security header block. Only one instance of the element is permitted.

A client can pass a username and password by using a callback handler. The callback handler is a user-defined class that handles `javax.security.auth.Namecallback` and `Passwordcallback`. The name of the class can be specified in the `<username-token>` element's `cbhandler-name` attribute.

If this element is not present, the client runtime can build the username token using the `Stub.USERNAME_PROPERTY` and `Stub.PASSWORD_PROPERTY` supported by JAX-RPC. The Web service client can either use the `Stub` properties or use a static configuration by specifying the user name and password in a deployment descriptor. For more information on using the `Stub` properties, see "Pass the User Name and Password with Stub Properties".

Table 2-11 describes the `<username-token>` attributes. All of the attributes are optional.

Table 2-11 Attributes of the <username-token> Element

Attribute Name | Description
--- | ---
name | The username to be inserted into the token.
password | The actual password of the user.
password-type | Type of password: `plaintext` or `digest`. Default is `plaintext`. Note that if you set `password-type` to `digest`, then `add-nonce` and `add-created` will be set to `true` by default.
cbhandler-name | The name of the callback handler that inserts the username token into the SOAP message. The callback handler is a user-defined callback handler class that handles `NameCallback` and `PasswordCallback`. The value of the `cbhandler-name` attribute is the name of the user-defined implementation class.
add-nonce | Specifies whether a nonce should be added to the request. For digest authentication, this attribute is required and must be set to `true`. This attribute is optional for plain text password authentication. The default value is `false`.
add-created | Specifies whether a creation time should be added to the request. For digest password authentication, this attribute is required and must be set to `true`. This attribute is optional for plain text password authentication. The default value is `false`.

#### X.509 Token Elements for Outbound Messages

The `<x509-token>` element is an optional element of the `<outbound>` configuration. This element indicates that an X.509 signing certificate will be inserted into the request. A direct reference to the X.509 certificate (signer's certificate) is added. You must have the signature key configured for this configuration to work.

Instead of passing a certificate (using direct reference), you could also pass the subject key identifier of the certificate. "Using the Subject Key Identifier for Signing" provides more information on how to pass the subject key identifier.

Table 2-12 describes the subelement of the `<x509-token>` element.

Table 2-12 Subelement of the <x509-token> Element

Element Name | Description
--- | ---
<property> | Properties that can be set on the `<x509-token>` element. The `<property>` subelement has this format: `<property name="``property_name``" value="``property_value``"/>` OracleAS Web Services Security defines the following property on `<x509-token>`. `oracle.security.wss.signX509token`—This property is applicable only when the `<x509-token>` is used with signature `<signature>`. If set to `true` (default), the Binary Security Token (BST) that contains the X.509 token will be signed by default. If set to `false`, the Binary Security Token will not be signed. For example: `<property name="``oracle.security.wss.signX509token``" value="``false``"/>`

#### SAML Token Elements for Outbound Messages

The `<saml-token>` element is an optional element of the `<outbound>` policy. The client interceptor refers to the `<saml-token>` element in the outbound policy for creating the actual SAML assertion for the user identity. "How to Configure a SAML Token for the Client-Side" provides information on how to provide dynamic and static configuration of SAML tokens. Table 2-13 describes the attributes of the `<saml-token>` element. All of the attributes are optional.

Table 2-13 Attributes of the <saml-token> Element

Attribute | Description
--- | ---
name | You can choose a name for the assertion subject by providing a value for the `name` attribute of the `<saml-token>` element. The `name` attribute has the following format: [realm-name`/`]name The name represents the name of the assertion. The assertion name can 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 contains the actual name of the user identity that is being propagated. For example, `name="jdoe"`. The value of the `name` attribute is inserted in the `<name-identifier>` element of the SAML assertion. The default name identifier format is `UNSPECIFIED`.
name-format | Specifies the format of the assertion subject name. This element can have any of the following values: `UNSPECIFIED` (default)— can be any value. `EMAIL`—an email address, such as `abc@myCompany.com`. `X509-SUBJECT-NAME`—an X.509 subject name (an X.509 subject name translates to `DN`, a distinguished name). For example: `CN="abc", OU="Security", O="Oracle", C="US"`. `WINDOWS-DOMAIN-NAME`—the name of a Windows domain. For example: `abc`.
cbhandler-name | Identifies the name of the user-defined class that will handle the `SAMLTokenCallback` call back handler. This class is used to pass SAML assertions to the interceptor. The callback handler must be able to handle SAML token callback. "Writing a SAML Token Callback Handler" provides more information on how to write this handler.
issuer-name | Used to get the SAML assertion issuer name. The default value is `www.oracle.com`. It is strongly recommended that you change this to the name of your own assertion issuer.

Table 2-14 describes the subelements of the `<saml-token>` element. All of the subelements are optional.

Table 2-14 Subelements of the <saml-token> Element

Element Name | Description
--- | ---
<confirmation-method> | The supported confirmation methods are `Sender-Vouches` (default), `Sender-Vouches-Unsigned`, and `Holder-Of-Key`. "Configuring Confirmation Methods" provides more information on confirmation methods and on how to configure this element.
<attribute> | The `<attribute>` element has a mandatory `path` attribute that points to a properties file. The attribute statement is created from the attributes listed in this file. This properties file contains one or more attribute name/value pairs for asserting a user's identity. The attribute name can be prefixed with an optional namespace. For example: [attribute-name-space`/`]attribute-name=value The following is an example of a value that can appear in an `<attribute>` subelement. `email=abc@myCompany.com` For more information on using the `<attribute>` element, see "Configuring Authentication and Attributes Statements".
<saml-authority> | Allows you to retrieve a SAML token from an external SAML authority. For more information, see "Elements for Retrieving SAML Tokens from an External SAML Authority".

#### Elements for Retrieving SAML Tokens from an External SAML Authority

The `<saml-authority>` element is an optional subelement `<saml-token>`. A configuration of the `<saml-authority>` element and its subelements allow you to retrieve a SAML token from an external SAML authority by issuing a SAMLP request. "Retrieving a SAML Token from an External SAML Authority" provides more information on configuring this element. Table 2-15 describes the subelements of `<saml-authority>`.

Table 2-15 Subelements of the <saml-authority> Element

Name | Description
--- | ---
<endpoint-address> | (Required) Specifies the SAML Responder URL.
<auth-user-name> | Specifies the username that is used to provide authentication to the SAML authority. This attribute is required for the `Holder-Of-Key` confirmation method, optional otherwise. For the `Holder-Of-Key` subject confirmation method, the SAML assertion token is requested for the user identified by `auth-user-name`. For the `Sender-Vouches` subject confirmation method, the SAML assertion token is requested for the user identified by the `name` attribute of `<saml-token>` element.
<auth-password> | (Optional) Specifies the password that is used to provide authentication to the SAML authority. The `auth-user-name` and `auth-password` elements are required if `password-based-mechanism` is used for authentication.
<require-signature> | (Optional) If this boolean attribute is `true`, then the SAMLP request is signed with the client's signature key. In addition, the client-side keystore and signature keys should be configured. The default value for this element is `false`. See "Keystore Elements" and "Signature and Encryption Key Elements" for more information on configuring the keystore and the signature key.

#### Signature Elements for Outbound Messages

Table 2-16 describes the subelements of the `<signature>` element. The subelements describe the options that are available for signing outbound messages.

Table 2-16 Subelements of the <signature> Element

Element Name | Description
--- | ---
<signature-methods> | Collection of `<signature-method>` elements. The `<signature-method>` element specifies the acceptable signature algorithm. Algorithm names are specified using their short names instead of URIs. The default value is `RSA-SHA1`. Table 2-17, "Signature Algorithms and Short Names" lists the algorithm URIs and corresponding short names that are recognized by OracleAS Web Services Security.
<tbs-elements> | List of elements to be signed. This element has these attributes: `name-space`—The actual name space of the element in the SOAP message. This attribute can be omitted if there is only one element with this name in the namespace. This attribute can be omitted if all of the elements in the SOAP message share the same name space. `local-part`—The actual element name.
<add-timestamp> | Adds a timestamp to the outbound SOAP message. (This timestamp is verified by setting the `<verify-timestamp>` element described in Table 2-6). `expiry`—Expiration time, in seconds, until the signature expires. Default is 28800 seconds. `created`—Indicates whether a creation time is inserted into the timestamp. Default is `true`.

Table 2-17 lists the signature algorithms recognized by Web service security and their associated short names.

Table 2-17 Signature Algorithms and Short Names

Signature Algorithm | Short Name
--- | ---
http://www.w3.org/2000/09/xmldsig#rsa-sha1 | RSA-SHA1 (default)
http://www.w3.org/2001/04/xmldsig-more#rsa-md5 | RSA-MD5
http://www.w3.org/2000/09/xmldsig#dsa-sha1 | DSA-SHA1

#### Encryption Elements for Outbound Messages

The `<encrypt>` element is an optional subelement of the `<outbound>` element. It specifies confidentiality requirements of the sender. The `<encrypt>` element can occur only once within an `<outbound>` element.

Table 2-18 describes the encryption elements that are available for outbound messages.

Table 2-18 Subelements of the <encrypt> Element

Element Name | Description
--- | ---
<encryption-method> | Specifies the encryption method to be used for encrypting the elements of the outbound SOAP message. Only one encryption method can be listed under the `<encrypt>` element. The following methods are valid. `3DES` `AES-128` (default) `AES-256` Table 2-8 lists the URIs and corresponding short names for the encryption algorithms recognized by Web services security.
<keytransport-method> | A `<keytransport-method>` identifies the key transport algorithm. Only one keytransport method can be specified for outbound messages. Algorithm names are specified using their short names instead of URIs. The possible values for this element are: `RSA-1_5` (default) `RSA-OAEP-MGF1P` Table 2-9 lists the URIs and corresponding short names of the algorithms recognized by Web services security.
<tbe-elements> | Elements to be encrypted. This element has these attributes: `name-space`—The actual name space of the element in the SOAP message. This attribute can be omitted if there is only one element with this name in the namespace. `local-part`—The actual name of the element. `mode`—An additional attribute that is used to specify whether the `ELEMENT` or the `CONTENT` is encrypted. If the value of `mode` is `ELEMENT` then the entire element is encrypted, if the value of `mode` is `CONTENT` then the content of the element is encrypted. Default is `CONTENT`.
<recipient-key> | The key alias of the recipient, which is used to encrypt the data encryption key. The data encryption key is the generated symmetric key that is used to encrypt the actual data. The data encryption key itself is also encrypted using the recipient's public key. The recipient key may or may not have a key usage extension. If the recipient key does have a key usage extension, then it must be of the type `KEY_ENCIPHERMENT`. If it does not, the encryption request is rejected. This element has these attributes: `alias`—An alias for the key. `key-pass`—An optional password attribute to access the key.
<use-request-cert> | The Web service client has sent a signed SOAP message and the Web service application has successfully verified the signature. 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. The `use-request-cert` element is configured 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.