Skip Headers
Oracle® Application Server Web Services Security Guide
10g (10.1.3.5.0)

Part Number E13983-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

A OracleAS Web Services Security Schema

This appendix describes the Oracle Application Server Web Services security configuration elements defined by the security schema oracle-webservices-security-10_0.xsd. This file can be found in the oc4j-schemas.jar file.

OC4J_HOME\j2ee\home\lib\oc4j-schemas.jar

OC4J_HOME represents the directory where you installed Oracle Containers for J2EE (OC4J).

Security is typically used as part of a larger Web services management configuration. To enable security, you have to configure it into the Web service on the server side and into the client. The configuration is part of an XML configuration file that is passed to the Web service or client when it is assembled.

Hierarchy of a Security Configuration

A security configuration is delimited by the element <security>. In the oracle-webservices.xml server-side configuration file, the configuration can appear in the <runtime> clause for a port component and for an individual operation. Each port and operation can have its own security configuration. The following conceptual fragment illustrates where the security configuration elements appear in the hierarchy of an oracle-webservices.xml file.

<oracle-webservices>
 <webservice-description>
<port-component>
  <runtime enabled="security">
    <security>
      <key-store>
      <signature-key>
      <encryption-key>

  <operations>
    <operation> 
      <runtime> 
        <security> 
          <inbound>
            <verify-username-token>
              <property> 
            <verify-x509-token>
              <property>
            <verify-saml-token>
              <subject-confirmation-methods>
            <verify-signature> 
              <signature-methods> 
                <signature-method>
              <tbs-elements>
              <verify-timestamp>
              <property>
            <decrypt> 
              <encryption-methods> 
                <encryption-method>
              <keytransport-methods> 
                <keytransport-method>
              <tbe-elements>
              <property>

          <outbound>
            <username-token> 
              <property>
            <saml-token>
              <attribute>
              <subject-confirmation-method>
                <confirmation-method>
              <saml-authority>
              <property>
            <x509-token>
              <property>
            <signature> 
              <signature-methods>
                <signature-method>
              <add-timestamp>
              <tbs-elements>
                <tbs-element>
            <encrypt> 
              <encryption-method>
              <keytransport-method>
              <recipient-key>
              <use-cert-request>
              <tbe-elements>
                <tbe-element>

Elements and Attributes of the Security Schema

This section is an alphabetical dictionary of elements of the auditing schema, oracle-webservices-security-10_0.xsd.

<add-timestamp>

Parent element:  <signature>

Child elements:  None

Required? Optional

Inbound or Outbound Messages? Outbound

Adds a timestamp to the outbound SOAP message. This timestamp is verified by setting the <verify-timestamp> element. See "<verify-timestamp>".

Table A-1 <add-timestamp> Attributes

Name Description

created

Value: boolean

Default: true

Indicates whether a creation time is inserted into the timestamp. Default is true.

expiry

Value: long

Default: 28800 seconds

Expiration time, in seconds, until the signature expires. Default is 28800 seconds (8 hours).


<attribute>

Parent element:  <saml-token>

Child elements:  None

Required? Optional

Inbound or Outbound Messages? Outbound

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

Table A-2 <attribute> Attributes

Name Description

path

Value: string

Default: n/a (Required)

Indicates the path to a properties file that contains one or more attribute name/value pairs for asserting a user's identity.


<confirmation-method>

This element can appear as an inbound or an outbound element.

As an inbound element:

Parent element:  <subject-confirmation-methods>

Child elements:  None

Required? Required if <subject-confirmation-methods> is specified

Inbound or Outbound Messages? Inbound

This is an required subelement if the <subject-confirmation-methods> is used. Between one and three <confirmation-method> subelements can appear. The possible string values for this element 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.

As an outbound element:

Parent element:  <subject-confirmation-method>

Child elements:  None

Required? Optional

Inbound or Outbound Messages? Outbound

The supported confirmation methods are Sender-Vouches (default), Sender-Vouches-Unsigned, and Holder-Of-Key. At most, one <confirmation-method> element can be specified as a subelement of a <subject-confirmation-method> element in an outbound configuration.

<decrypt>

Parent element:  <inbound>

Child elements:  <encryption-methods>, <keytransport-methods>, <property>, <tbe-elements>

Required? Optional

Inbound or Outbound Messages? Inbound

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.

In addition to the child elements listed earlier, the <decrypt> element also supports a <property> subelement. 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"/>

    The decryption key alias and password is stored in the system-jazn-data.xml file using password indirection.

    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.

<encrypt>

Parent element:  <outbound>

Child elements:  <encryption-method>, <keytransport-method>, <recipient-key>, <tbe-elements>, <use-cert-request>

Required? Optional

Inbound or Outbound Messages? Outbound

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.

<encryption-key>

Parent element:  <security>

Child elements:  None

Required? Optional

Inbound or Outbound Messages? Both

Points to the key required for decrypting the message.

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 <recipient-key>, see "<recipient-key>".

The <signature-key> and <encryption-key> elements 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> and <encryption-key> elements, then you must restart the application to enable the new values.

Table A-3 <encryption-key> Attributes

Name Description

alias

Value: string

Default: n/a (Required)

Alias for the key.

key-pass

Value: string

Default: n/a

Password to access the key.


<encryption-method>

This element can appear as an inbound or an outbound element.

As an inbound element:

Parent element:  <encryption-methods>

Child elements:  None

Required? Required if <encryption-methods> is specified

Inbound or Outbound Messages? Inbound

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. At least one, but no more than three <encryption-method> elements can be listed. 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 values for <encryption-method> are:

  • 3DES

  • AES-128 (default)

  • AES-256

Table 2-9, "URIs and Short Names for Encryption Algorithms" lists the encryption algorithm URIs and corresponding short names recognized by Web services security.

As an outbound element:

Parent element:  <encrypt>

Child elements:  None

Required? Optional

Inbound or Outbound Messages? Outbound

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, "URIs and Short Names for Encryption Algorithms" lists the URIs and corresponding short names for the encryption algorithms recognized by Web services security.

<encryption-methods>

Parent element:  <decrypt>

Child elements:  <encryption-method>

Required? Optional

Inbound or Outbound Messages? Inbound

Collection of <encryption-method> elements. See "<encryption-method>".

<inbound>

Parent element:  <security>

Child elements:  <decrypt>, <verify-saml-token>, <verify-signature>, <verify-username-token>, <verify-x509-token>

Required? Optional

Inbound or Outbound Messages? Inbound

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.

<key-store>

Parent element:  <security>

Child elements:  None

Required? Optional

Inbound or Outbound Messages? Both

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 A-4 <key-store> Attributes

Name Description

name

Value: string

Default: n/a

Name of the keystore.

path

Value: string

Default: n/a (Required)

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

Value: string

Default: n/a

Keystore type. The default type is JKS. Other supported types are PKCS12 and ORACLE_WALLET.

store-pass

Value: string

Default: n/a

Password to access the keystore.


<keytransport-method>

This element can appear as an inbound or an outbound element.

As an inbound element:

Parent element:  <keytransport-methods>

Child elements:  None

Required? Required if <keytransport-methods> is specified

Inbound or Outbound Messages? Inbound

Each <keytransport-method> specifies the acceptable key transport algorithms. At least one, but no more than two <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, "URIs and Short Names for Key Transport Algorithms" lists the algorithm URIs and corresponding short names recognized by Web services security.

As an outbound element:

Parent element:  <encrypt>

Child elements:  None

Required? Optional

Inbound or Outbound Messages? Outbound

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, "URIs and Short Names for Key Transport Algorithms" lists the URIs and corresponding short names of the algorithms recognized by Web services security.

<keytransport-methods>

Parent element:  <decrypt>

Child elements:  <keytransport-method>

Required? Optional

Inbound or Outbound Messages? Inbound

Collection of <keytransport-method> elements. See "<keytransport-method>".

<nonce-config>

Parent element:  <security>

Child elements:  None

Required? Optional

Inbound or Outbound Messages? Both

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.

Table A-5 <nonce-config> Attributes

Name Description

clock-skew

Value: integer

Default: n/a

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.

cache-ttl (cache time to live)

Value: integer

Default: 300 seconds

Indicates how long, in seconds, the nonces remain valid in the cache. Expired nonces are removed from the cache. Default is 300 seconds.


<outbound>

Parent element:  <security>

Child elements:  <encrypt>, <saml-token>, <signature>, <username-token>, <x509-token>

Required? 

Inbound or Outbound Messages? Outbound

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.

<recipient-key>

Parent element:  <encrypt>

Child elements:  None

Required? required

Inbound or Outbound Messages? Outbound

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.

Table A-6 <recipient-key> Attributes

Name Description

alias

Value: String

Default: n/a (Required)

An alias for the key.

key-pass

Value: string

Default: n/a

An optional password attribute to access the key.


<saml-authority>

Parent element:  <saml-token>

Child elements:  <property>

Required? Optional

Inbound or Outbound Messages? Outbound

The <saml-authority> element is an optional subelement <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.

This element supports a <property> subelement which is currently unused.

Table A-7 <saml-authority> Attributes

Name Description

<auth-password>

Value: string

Default: n/a

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.

<auth-user-name>

Value: string

Default: n/a

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.

<endpoint-address>

Value: string

Default: n/a (Required)

Specifies the SAML Responder URL.

<require-signature>

Value: boolean

Default: false

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.


<saml-token>

Parent element:  <outbound>

Child elements:  <attribute>, <property>, <saml-authority>, <subject-confirmation-method>

Required? Optional

Inbound or Outbound Messages? Outbound

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. This element has a <property> subelement which is currently unused.

Table A-8 <saml-token> Attributes

Name Description

name

Value: string

Default: n/a (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

Value: name-identifier-format-enum

Default: UNSPECIFIED

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

Value: string

Default: n/a

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.

issuer-name

Value: string

Default: www.oracle.com

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.


<security>

Parent element:  Root element of a security configuration

Child elements:  <encryption-key>, <inbound>, <key-store>, <nonce-config>, <outbound>, <signature-key>

Required? Optional

Inbound or Outbound Messages? Both

Encapsulates a security configuration. The configuration can occur at the global, port or operation level.

<signature>

Parent element:  <outbound>

Child elements:  <add-timestamp>, <signature-methods>, <tbs-elements>

Required? Optional

Inbound or Outbound Messages? Outbound

Specifies the algorithm for signing outgoing messages or individual message elements.

<signature-key>

Parent element:  <security>

Child elements:  None

Required? Optional

Inbound or Outbound Messages? Both

Points to the key required by <signature> and <verify-signature>.

The <signature-key> and <encryption-key> elements are required at port level if a port level keystore is specified or when selecting keys from the 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> and <encryption-key> elements, then you must restart the application to enable the new values.

Table A-9 <signature-key> Attributes

Name Description

alias

Value: string

Default: n/a (Required)

Alias for the key.

key-pass

Value: string

Default: n/a

Password to access the key.


<signature-method>

This element can appear as an inbound or an outbound element.

As an inbound element:

Parent element:  <signature-methods>

Child elements:  None

Required? Optional

Inbound or Outbound Messages? Inbound

The <signature-method> element 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 OracleAS Web Services Security.

As an outbound element:

Parent element:  <signature-methods>

Child elements:  None

Required? Required if <signature-methods> is specified.

Inbound or Outbound Messages? Outbound

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.

<signature-methods>

This element can appear as an inbound or an outbound element.

As an inbound element:

Parent element:  <verify-signature>

Child elements:  <signature-method>

Required? Optional

Inbound or Outbound Messages? Inbound

List of <signature-method> elements. See "<signature-method>".

As an outbound element:

Parent element:  <signature>

Child elements:  <signature-method>

Required? Optional

Inbound or Outbound Messages? Outbound

Collection of <signature-method> elements. See "<signature-method>".

<subject-confirmation-method>

Parent element:  <saml-token>

Child elements:  <confirmation-method>

Required? Optional

Inbound or Outbound Messages? Outbound

Delimits a list of <confirmation-method> elements. See "<confirmation-method>".

<subject-confirmation-methods>

Parent element:  <verify-saml-token>

Child elements:  <confirmation-method>

Required? Optional

Inbound or Outbound Messages? Inbound

This is an optional element for inbound policy. When used as part of the inbound <verify-saml-token> policy, it refers to an enumeration of confirmation methods (<confirmation-method>) used for propagating the identity in the incoming SOAP message.

<tbe-element>

This element can appear as an inbound or an outbound element.

As an inbound element:

Parent element:  <tbe-elements>

Child elements:  None

Required? Required if <tbe-elements> is present

Inbound or Outbound Messages? Inbound

Indicates the elements that are encrypted in the incoming SOAP message.

Table A-10 <tbe-element> Attributes

Name Description

local-part

Value: string

Default: n/a (Required)

The actual element name.

mode

Value: encrypt-mode-enum

Default: CONTENT

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.

name-space

Value: anyUri

Default: n/a (Required)

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.


As an outbound element:

Parent element:  <tbe-elements>

Child elements:  None

Required? Required if <tbe-elements> is specified

Inbound or Outbound Messages? Outbound

Each <tbe-element> indicates an element to be encrypted.

Table A-11 <tbe-element> Attributes

Name Description

local-part

Value: string

Default: n/a (Required)

The actual name of the element.

mode

Value: enum-mode-encrypt

Default: CONTENT

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.

name-space

Value: anyUri

Default: n/a (Required)

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.


<tbe-elements>

This element can appear as an inbound or an outbound element.

As an inbound element:

Parent element:  <decrypt>

Child elements:  <tbe-element>

Required? Optional

Inbound or Outbound Messages? Inbound

Collection of <tbe-element> elements. See "<tbe-element>".

As an outbound element:

Parent element:  <encrypt>

Child elements:  <tbe-element>

Required? Required

Inbound or Outbound Messages? Outbound

Collection of <tbe-element> elements. See "<tbe-element>".

<tbs-element>

This element can appear as an inbound or an outbound element.

As an inbound element:

Parent element:  <tbs-elements>

Child elements:  None

Required? Required if <tbs-elements> is specified

Inbound or Outbound Messages? Inbound

The <tbs-element> element identifies the element in the SOAP message that is expected to be signed.

Table A-12 <tbs-element> Attributes

Name Description

local-part

Value: string

Default: n/a (Required)

The actual element name.

name-space

Value: anyUri

Default: n/a (Required)

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.


As an outbound element:

Parent element:  <tbs-elements>

Child elements:  None

Required? Required if <tbs-elements> is specified

Inbound or Outbound Messages? Outbound

Each <tbs-element> indicates the element to be signed.

Table A-13 <tbs-element> Attributes

Name Description

local-part

Value: string

Default: n/a (Required)

The actual element name.

name-space

Value: anyUri

Default: n/a (Required)

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.


<tbs-elements>

This element can appear as an inbound or an outbound element.

As an inbound element:

Parent element:  <verify-signature>

Child elements:  <tbs-element>

Required? Optional

Inbound or Outbound Messages? Inbound

List of <tbs-element> elements that are expected to be signed in the incoming request. See "<tbs-element>".

As an outbound element:

Parent element:  <signature>

Child elements:  None

Required? Optional

Inbound or Outbound Messages? Outbound

Collection of <tbs-element> elements. See "<tbs-element>".

<use-cert-request>

Parent element:  <encrypt>

Child elements:  None

Required? Required

Inbound or Outbound Messages? Outbound

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.

<username-token>

Parent element:  <outbound>

Child elements:  <property>

Required? Optional

Inbound or Outbound Messages? Outbound

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. This element has an optional <property> subelement which is currently unused.

Table A-14 <username-token> Attributes

Name Description

name

Value: string

Default: n/a

The username to be inserted into the token.

password

Value: string

Default: n/a

The actual password of the user

password-type

Value: password-type-enum

Default: plaintext

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

Value: string

Default: n/a

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

Value: boolean

Default: false

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

Value: boolean

Default: false

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.


<verify-saml-token>

Parent element:  <inbound>

Child elements: <subject-confirmation-methods>

Required? Optional

Inbound or Outbound Messages? Inbound

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.

<verify-signature>

Parent element:  <inbound>

Child elements: <property>, <signature-methods>, <tbs-elements>, <verify-timestamp>

Required? Optional

Inbound or Outbound Messages? Inbound

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.

In addition to the child elements liste, the <verify-signature> element provides a <property> subelement. 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.

<verify-timestamp>

Parent element:  <verify-signature>

Child elements:  None

Required? Optional

Inbound or Outbound Messages? Inbound

Verifies the timestamp in the incoming SOAP message. (This timestamp is configured with the <add-timestamp> element.) 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.

Table A-15 <verify-timestamp> Attributes

Name Description

created

Value: boolean

Default: true

Indicates whether the timestamp includes the creation time. Default is true.

expiry

Value: long

Default: 28800 seconds

Expiration time, in seconds, on the signature. Default is 28800 seconds (8 hours).


<verify-username-token>

Parent element:  <inbound>

Child elements:  <property>

Required? Optional

Inbound or Outbound Messages? Inbound

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.

Table A-16 <verify-username-token> Attribute

Name Description

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 also has a <property> subelement. 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.

<verify-x509-token>

Parent element:  <inbound>

Child elements:  <property>

Required? Optional

Inbound or Outbound Messages? Inbound

The <verify-x509-token> element specifies the authentication policy with respect to X.509 tokens. It is an optional subelement of the <inbound> element. It has an optional <property> subelement which is currently not used.

<x509-token>

Parent element:  <outbound>

Child elements:  <property>

Required? Optional

Inbound or Outbound Messages? Outbound

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.

The <x509-token> element supports a <property> subelement. 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"/>

Oracle Web Services Security Schema Listing

Example A-1 illustrates the contents of the oracle-webservices-security-10_0.xsd schema file.

Example A-1 Contents of the oracle-webservices-security-10_0.xsd Security Schema

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:simpleType name="password-type-enum">
    <xsd:restriction base="xsd:string">
      <xsd:whiteSpace value="collapse"/>
      <xsd:enumeration value="PLAINTEXT"/>
      <xsd:enumeration value="DIGEST"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:simpleType name="signature-method-enum">
    <xsd:restriction base="xsd:string">
      <xsd:whiteSpace value="collapse"/>
      <xsd:enumeration value="RSA-SHA1"/>
      <xsd:enumeration value="RSA-MD5"/>
      <xsd:enumeration value="DSA-SHA1"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:simpleType name="encryption-method-enum">
    <xsd:restriction base="xsd:string">
      <xsd:whiteSpace value="collapse"/>
      <xsd:enumeration value="3DES"/>
      <xsd:enumeration value="AES-128"/>
      <xsd:enumeration value="AES-256"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:simpleType name="keytransport-method-enum">
    <xsd:restriction base="xsd:string">
      <xsd:whiteSpace value="collapse"/>
      <xsd:enumeration value="RSA-OAEP-MGF1P"/>
      <xsd:enumeration value="RSA-1_5"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:simpleType name="encrypt-mode-enum">
    <xsd:restriction base="xsd:string">
      <xsd:whiteSpace value="collapse"/>
      <xsd:enumeration value="CONTENT"/>
      <xsd:enumeration value="ELEMENT"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:complexType name="nonce-config-type">
    <xsd:attribute name="clock-skew" type="xsd:integer" default="0"/>
    <xsd:attribute name="cache-ttl" type="xsd:integer" default="300"/>
  </xsd:complexType>
  <xsd:complexType name="security-config-type">
    <xsd:sequence>
      <xsd:element name="key-store" type="key-store-config-type" minOccurs="0"/>
      <xsd:element name="signature-key" type="key-config-type" minOccurs="0"/>
      <xsd:element name="encryption-key" type="key-config-type" minOccurs="0"/>
      <xsd:element name="nonce-config" type="nonce-config-type" minOccurs="0"/>
      <xsd:element name="inbound" type="inbound-config-type" minOccurs="0"/>
      <xsd:element name="outbound" type="outbound-config-type" minOccurs="0"/>
      <xsd:element name="property" type="property-config-type" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="security-operation-config-type">
    <xsd:sequence>
      <xsd:element name="inbound" type="inbound-config-type" minOccurs="0"/>
      <xsd:element name="outbound" type="outbound-config-type" minOccurs="0"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:element name="security-global" type="security-config-type"/>
  <xsd:element name="security-port" type="security-config-type"/>
  <xsd:element name="security-operation" type="security-operation-config-type"/>
  <xsd:complexType name="inbound-config-type">
    <xsd:sequence>
      <xsd:element name="verify-username-token" type="verify-username-token-config-type" minOccurs="0"/>
      <xsd:element name="verify-x509-token" type="verify-x509-token-config-type" minOccurs="0"/>
      <xsd:element name="verify-saml-token" type="verify-saml-token-config-type" minOccurs="0"/>
      <xsd:element name="verify-signature" type="verify-signature-config-type" minOccurs="0"/>
      <xsd:element name="decrypt" type="decrypt-config-type" minOccurs="0"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="outbound-config-type">
    <xsd:sequence>
      <xsd:choice minOccurs="0">
        <xsd:element name="username-token" type="username-token-config-type"/>
        <xsd:element name="x509-token" type="x509-token-config-type"/>
        <xsd:element name="saml-token" type="saml-token-config-type"/>
      </xsd:choice>
      <xsd:element name="signature" type="signature-config-type" minOccurs="0"/>
      <xsd:element name="encrypt" type="encrypt-config-type" minOccurs="0"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="signature-config-type">
    <xsd:sequence>
      <xsd:element name="signature-method" default="RSA-SHA1" minOccurs="0">
        <xsd:simpleType>
          <xsd:restriction base="xsd:string">
            <xsd:whiteSpace value="collapse"/>
            <xsd:enumeration value="RSA-SHA1"/>
            <xsd:enumeration value="RSA-MD5"/>
            <xsd:enumeration value="DSA-SHA1"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
      <xsd:element name="tbs-elements" type="sign-elements-config-type" minOccurs="0"/>
      <xsd:element name="add-timestamp" type="timestamp-config-type" minOccurs="0"/>
      <xsd:element name="property" type="property-config-type" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="encrypt-config-type">
    <xsd:sequence>
      <xsd:choice>
        <xsd:element name="recipient-key" type="key-config-type"/>
        <xsd:element name="use-request-cert" type="xsd:boolean"/>
      </xsd:choice>
      <xsd:element name="encryption-method" default="AES-128" minOccurs="0">
        <xsd:simpleType>
          <xsd:restriction base="xsd:string">
            <xsd:whiteSpace value="collapse"/>
            <xsd:enumeration value="3DES"/>
            <xsd:enumeration value="AES-128"/>
            <xsd:enumeration value="AES-256"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
      <xsd:element name="keytransport-method" default="RSA-1_5" minOccurs="0">
        <xsd:simpleType>
          <xsd:restriction base="xsd:string">
            <xsd:whiteSpace value="collapse"/>
            <xsd:enumeration value="RSA-OAEP-MGF1P"/>
            <xsd:enumeration value="RSA-1_5"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
      <xsd:element name="tbe-elements" type="encrypt-elements-config-type"/>
      <xsd:element name="property" type="property-config-type" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="verify-signature-config-type">
    <xsd:sequence>
      <xsd:element name="signature-methods" type="signature-methods-config-type" minOccurs="0"/>
      <xsd:element name="tbs-elements" type="sign-elements-config-type" minOccurs="0"/>
      <xsd:element name="verify-timestamp" type="timestamp-config-type" minOccurs="0"/>
      <xsd:element name="property" type="property-config-type" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="decrypt-config-type">
    <xsd:sequence>
      <xsd:element name="encryption-methods" type="encryption-methods-config-type" minOccurs="0"/>
      <xsd:element name="keytransport-methods" type="keytransport-methods-config-type" minOccurs="0"/>
      <xsd:element name="tbe-elements" type="encrypt-elements-config-type" minOccurs="0"/>
      <xsd:element name="property" type="property-config-type" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="property-config-type">
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="value" type="xsd:string" use="required"/>
  </xsd:complexType>
  <xsd:complexType name="key-store-config-type">
    <xsd:attribute name="store-pass" type="xsd:string" use="optional"/>
    <xsd:attribute name="path" type="xsd:string" use="required"/>
    <xsd:attribute name="type" type="xsd:string" use="optional"/>
    <xsd:attribute name="name" type="xsd:string" use="optional"/>
  </xsd:complexType>
  <xsd:complexType name="key-config-type">
    <xsd:attribute name="alias" type="xsd:string" use="required"/>
    <xsd:attribute name="key-pass" type="xsd:string" use="optional"/>
  </xsd:complexType>
  <xsd:complexType name="signature-methods-config-type">
    <xsd:sequence>
      <xsd:element name="signature-method" default="RSA-SHA1" maxOccurs="3">
        <xsd:simpleType>
          <xsd:restriction base="xsd:string">
            <xsd:whiteSpace value="collapse"/>
            <xsd:enumeration value="RSA-SHA1"/>
            <xsd:enumeration value="RSA-MD5"/>
            <xsd:enumeration value="DSA-SHA1"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="encryption-methods-config-type">
    <xsd:sequence>
      <xsd:element name="encryption-method" default="AES-128" maxOccurs="3">
        <xsd:simpleType>
          <xsd:restriction base="xsd:string">
            <xsd:whiteSpace value="collapse"/>
            <xsd:enumeration value="3DES"/>
            <xsd:enumeration value="AES-128"/>
            <xsd:enumeration value="AES-256"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="keytransport-methods-config-type">
    <xsd:sequence>
      <xsd:element name="keytransport-method" default="RSA-1_5" maxOccurs="2">
        <xsd:simpleType>
          <xsd:restriction base="xsd:string">
            <xsd:whiteSpace value="collapse"/>
            <xsd:enumeration value="RSA-OAEP-MGF1P"/>
            <xsd:enumeration value="RSA-1_5"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="username-token-config-type">
    <xsd:sequence>
      <xsd:element name="property" type="property-config-type" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="name" type="xsd:string" use="optional"/>
    <xsd:attribute name="password" type="xsd:string" use="optional"/>
    <xsd:attribute name="password-type" type="password-type-enum" use="optional" default="PLAINTEXT"/>
    <xsd:attribute name="cbhandler-name" type="xsd:string" use="optional"/>
    <xsd:attribute name="add-nonce" type="xsd:boolean" use="optional" default="false"/>
    <xsd:attribute name="add-created" type="xsd:boolean" use="optional" default="false"/>
  </xsd:complexType>
  <xsd:complexType name="verify-username-token-config-type">
    <xsd:sequence>
      <xsd:element name="property" type="property-config-type" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="password-type" type="password-type-enum" use="optional"/>
    <xsd:attribute name="require-nonce" type="xsd:boolean" use="optional" default="false"/>
    <xsd:attribute name="require-created" type="xsd:boolean" use="optional" default="false"/>
  </xsd:complexType>
  <xsd:complexType name="verify-x509-token-config-type">
    <xsd:sequence>
      <xsd:element name="property" type="property-config-type" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="x509-token-config-type">
    <xsd:sequence>
      <xsd:element name="property" type="property-config-type" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="cbhandler-name" type="xsd:string" use="optional"/>
  </xsd:complexType>
  <xsd:complexType name="timestamp-config-type">
    <xsd:attribute name="expiry" type="xsd:long" default="28800"/>
    <xsd:attribute name="created" type="xsd:boolean" default="true"/>
  </xsd:complexType>
  <xsd:complexType name="encrypt-elements-config-type">
    <xsd:sequence>
      <xsd:element name="tbe-element" maxOccurs="unbounded">
        <xsd:complexType>
          <xsd:attribute name="name-space" type="xsd:anyURI" use="required"/>
          <xsd:attribute name="local-part" type="xsd:string" use="required"/>
          <xsd:attribute name="mode" type="encrypt-mode-enum" use="optional" default="CONTENT"/>
        </xsd:complexType>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="sign-elements-config-type">
    <xsd:sequence>
      <xsd:element name="tbs-element" maxOccurs="unbounded">
        <xsd:complexType>
          <xsd:attribute name="name-space" type="xsd:anyURI" use="required"/>
          <xsd:attribute name="local-part" type="xsd:string" use="required"/>
        </xsd:complexType>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="saml-token-config-type">
    <xsd:sequence>
      <xsd:element name="subject-confirmation-method" type="subject-confirmation-method-config-type" minOccurs="0"/>
      <xsd:element name="attribute" type="attribute-config-type" minOccurs="0"/>
      <xsd:element name="property" type="property-config-type" minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="saml-authority" type="saml-authority-config-type" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="name-format" type="name-identifier-format-enum" default="UNSPECIFIED"/>
    <xsd:attribute name="name" type="xsd:string" use="optional"/>
    <xsd:attribute name="cbhandler-name" type="xsd:string" use="optional"/>
    <xsd:attribute name="issuer-name" type="xsd:string" use="optional"/>
  </xsd:complexType>
  <xsd:complexType name="verify-saml-token-config-type">
    <xsd:sequence>
      <xsd:element name="subject-confirmation-methods" type="subject-confirmation-methods-config-type" minOccurs="0"/>
      <xsd:element name="property" type="property-config-type" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="subject-confirmation-methods-config-type">
    <xsd:sequence>
      <xsd:element name="confirmation-method" default="SENDER-VOUCHES" maxOccurs="3">
        <xsd:simpleType>
          <xsd:restriction base="xsd:string">
            <xsd:whiteSpace value="collapse"/>
            <xsd:enumeration value="SENDER-VOUCHES"/>
            <xsd:enumeration value="SENDER-VOUCHES-UNSIGNED"/>
            <xsd:enumeration value="HOLDER-OF-KEY"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="subject-confirmation-method-config-type">
    <xsd:sequence>
      <xsd:element name="confirmation-method" default="SENDER-VOUCHES" minOccurs="0">
        <xsd:simpleType>
          <xsd:restriction base="xsd:string">
            <xsd:whiteSpace value="collapse"/>
            <xsd:enumeration value="SENDER-VOUCHES"/>
            <xsd:enumeration value="SENDER-VOUCHES-UNSIGNED"/>
            <xsd:enumeration value="HOLDER-OF-KEY"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="attribute-config-type">
    <xsd:attribute name="path" type="xsd:string" use="required"/>
  </xsd:complexType>
  <xsd:simpleType name="name-identifier-format-enum">
    <xsd:restriction base="xsd:string">
      <xsd:whiteSpace value="collapse"/>
      <xsd:enumeration value="UNSPECIFIED"/>
      <xsd:enumeration value="EMAIL"/>
      <xsd:enumeration value="X509-SUBJECT-NAME"/>
      <xsd:enumeration value="WINDOWS-DOMAIN-NAME"/>
    </xsd:restriction>
  </xsd:simpleType>
  <xsd:complexType name="saml-authority-config-type">
    <xsd:sequence>
      <xsd:element name="property" type="property-config-type" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="endpoint-address" type="xsd:string" use="required"/>
    <xsd:attribute name="auth-user-name" type="xsd:string" use="optional"/>
    <xsd:attribute name="auth-password" type="xsd:string" use="optional"/>
    <xsd:attribute name="require-signature" type="xsd:boolean" use="optional"/>
  </xsd:complexType>
</xsd:schema>

Security Configuration Listing

You can find a sample oracle-webservices.xml deployment descriptor populated with a security configuration in "Security Configuration Elements".