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:

• Oracle JDeveloper IDE—Use the Oracle 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. The content of the oracle-webservices.xml and <generated_name>_Stub.xml files are not changed. The changes are made to the wsmgmt.xml file which contains the Web service security and management policies currently in force. Application Server Control can change the configuration only for Web services, not for their clients.

  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, a <username-token> subelement in the client <outbound> element indicates that the client will be sending a 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 configuration elements can appear at the global, port, and operation level. The values for security configuration 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 configuration elements as the server. Example 2-1 illustrates the security configuration elements as they are used in the server-side oracle-webservices.xml deployment descriptor.

Example 2-1 Security Configuration 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 configuration elements as they are used in the client-side <generated_name>_Stub.xml deployment descriptor.

Example 2-2 Security Configuration 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 the 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 a 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-19, "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 enables 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, in seconds, 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 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 must be set to true for digest authentication. Default is false.

The <verify-username-token> element can also have an optional <property> subelement. Table 2-5 describes the property element and its value.

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

Element Name

Description

<property>

Properties that can be set on the <verify-username-token> element. The <property> subelement has this format: <property name="property_name" value="property_value"/> OracleAS Web Services Security defines the following property on <verify-username-token>. username.token.allow.nopassword—The value of this boolean property determines whether the Web service will authenticate a username token without requiring a password. This property is useful when the user is already authenticated and trusted, and only its existence in the identity store needs to be verified. The following example allows the Web service to accept a username token without an accompanying password. <property name="username.token.allow.nopassword" value="true"/> This property can be set in the oracle-webservices.xml deployment descriptor. There is no tool support for adding this property; you must manually edit the file. See "Configure the Service to Not Require a Password" for examples of how to use this property.

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-6 lists the subelements of the <verify-saml-token> element. All of the subelements are optional.

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

Element Name	Description
<subject-confirmation-methods>	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-Unsigned—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-7 describes the subelements of the <verify-signature> element. All of the subelements are optional.

Table 2-7 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-18, "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-17). 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 (8 hours). 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-8 describes the elements that are available to set decryption details for inbound messages. All of the subelements are optional.

Table 2-8 Subelements of the <decrypt> Element

Element Name	Description
<encryption-methods>	Collection of <encryption-method> elements. Encryption methods as part of the <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-9 lists the encryption algorithm URIs and corresponding short names recognized by Web services security. Table 2-19 provides more information on the <encryption-method> element.
<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-10 lists the algorithm URIs and corresponding short names recognized by Web services security.
<tbe-elements>	Collection of <tbe-element> 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-9 lists the URIs of the encryption algorithms recognized by Web service security and their short names.

Table 2-9 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-10 lists the URIs of the key transport algorithms recognized by Web service security and their short names.

Table 2-10 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-11 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-12 describes the <username-token> attributes. All of the attributes are optional.

Table 2-12 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-13 describes the subelement of the <x509-token> element.

Table 2-13 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. 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-14 describes the attributes of the <saml-token> element. All of the attributes are optional.

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

Attribute	Description
name	(required) 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 format for the name identifier is UNSPECIFIED (see name-format).
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 [e-mail]. 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-15 describes the subelements of the <saml-token> element. All of the subelements are optional.

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

Element Name	Description
<subject-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=[e-mail] For more information on using the <attribute> element, see "Configuring Authentication and Attributes Statements".
<saml-authority>	Enables 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 of <saml-token>. A configuration of the <saml-authority> element and its attributes 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-16 describes the attributes of <saml-authority>.

Table 2-16 Attributes 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-17 describes the subelements of the <signature> element. The subelements describe the options that are available for signing outbound messages.

Table 2-17 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-18, "Signature Algorithms and Short Names" lists the algorithm URIs and corresponding short names that are recognized by OracleAS Web Services Security.
<tbs-elements>	Collection of <tbs-element> elements. Each <tbs-element> indicates the element 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-7). expiry—Expiration time, in seconds, until the signature expires. Default is 28800 seconds (8 hours). created—Indicates whether a creation time is inserted into the timestamp. Default is true.

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

Table 2-18 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-19 describes the encryption elements that are available for outbound messages.

Table 2-19 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-9 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-10 lists the URIs and corresponding short names of the algorithms recognized by Web services security.
<tbe-elements>	Collection of <tbe-element> elements. Each <tbe-element> indicates an element 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.