Using the WS-Security Supporting Tokens Policy

Learn about the WS-Security Supporting Tokens Policy.

For information about using policies in the context of the Community Manager developer portal, see Business Policies.

Table of Contents

About the WS-Security Supporting Tokens Policy

Supporting tokens are additional tokens that can be specified to augment claims provided by the token associated with the message signature provided by the Security Binding.

Creating a WS-Security Supporting Tokens policy

The first step in creating a policy is to define the basic policy information.

To add an operational policy

  1. Go to Workbench > Browse > Organization, and select Policies > Operational Policies. The Policies Summary is displayed.
  2. Click Add Policy.
  3. Choose the policy type and click Next.
  4. Specify a name (required) and description (optional) and click Finish. At the Completion Summary, click Close. The Add Policy Wizard creates a draft policy instance that you can then configure on the Policy Details page.

For more information, see Add Policy.

Configuring a WS-Security Supporting Tokens policy

To configure a WS-Security Supporting Tokens policy

  1. Go to Workbench > Browse > Organization and select the Policies > Operational Policies folder. The Policies Summary is displayed.
  2. Find the policy on the list and double-click to go to the Details page for the policy.
  3. In the second panel, click Modify to access the Specify Supporting Tokens Options page.
  4. Specify the specification version you'll be using, and whether you'll be using signing, endorsing, or encrypting. For details about the options available, see Add Supporting Token below. On this page you can also:
    • Add a token: See Add Supporting Token. As you add a token and configure it, you're returned to this page so that you can add another.
    • Add a token choice: allows you to define a group of token types required by different clients that are accessing a web service. A token choice can include one or multiple tokens.
    • Modify an existing token: See Modify Supporting Token.
    • Delete a token: See Delete Supporting Token.
  5. When you've added/configured all token types, click Finish.

Add Supporting Token

Provides options for defining supporting tokens that may be referenced by a security binding.

To add a supporting token:

  1. Navigate to the Specify Supporting Tokens Options page (see To configure a WS-Security Supporting Tokens policy above).
  2. Click Add Token. The Add Supporting Token page appears.
  3. Enter values:
    • Token Type: Choose a token type. Choices: X.509, Binary Security, SAML, Kerberos, Username, Issued Token, Secure Conversation, or Spnego.
    • Token Inclusion: Allows you to specify an IncludeToken attribute in the message. Choices: Not Specified, Always, Always to Recipient, Once, or Never (Indicates that an external reference mechanism is used to refer to the key represented by the token).
    • Subject Category: The subject category for the token. Choices: Consumer, End-User, or User Defined. For user-defined, specify the value.
  4. Click Next.
  5. The next page is determined by the choice of token type. Specify values for the token type:
  6. Click Next to return to the Specify Supporting Tokens page.

Modify Supporting Token

Provides options for modifying an existing supporting token that may be referenced by a security binding.

To modify a supporting token:

  1. Navigate to the Specify Supporting Tokens Options page (see To configure a WS-Security Supporting Tokens policy above).
  2. Highlight the token you want to modify and click Modify Token.
  3. At the Modify Supporting Token page, you can change any of the existing values:
    • Token Type: Choose a token type. Choices: X.509, Binary Security, SAML, Kerberos, Username, Issued Token, Secure Conversation, or Spnego.
    • Token Inclusion: Allows you to specify an IncludeToken attribute in the message. Choices: Not Specified, Always, Always to Recipient, Once, or Never (Indicates that an external reference mechanism is used to refer to the key represented by the token).
    • Subject Category: The subject category for the token. Choices: Consumer, End-User, or User Defined. For user-defined, specify the value.
  4. Click Next.
  5. The next page is determined by the choice of token type. Specify values for the token type:
  6. Click Next to return to the Specify Supporting Tokens page.

Delete Supporting Token

Provides options for deleting supporting tokens that may be referenced by a security binding.

Note: If you delete the last token in a Token Choice, the Token Choice is also deleted.

To delete a supporting token:

  1. Navigate to the Specify Supporting Tokens Options page (see To configure a WS-Security Supporting Tokens policy above).
  2. Highlight the token you want to delete and click Delete Token.
  3. At the confirmation message, click Yes.
  4. At the Delete Supporting Token Confirmation page, click Next. The token is deleted and you are returned to the Specify Supporting Tokens page.

Configuring X.509 Token options

Configuration (adding or modifying) of an X.509 supporting token includes the options listed below.

Version
A drop-down list box that allows you to select the Version of the X.509 token types that can be configured.
Issuer
The URI of the authority in a network that issues and manages security credentials and public keys for message encryption (for example, Certificate Authority).
Token References
Optional. A Token Reference is used to ensure a consistent processing model across all the token types supported by WSS: SOAP Message Security. The <wsse:SecurityTokenReference> element is used to specify all references to X.509 token types in signature or encryption elements that comply with this profile and can reference one of the listed X.509 token types. Each option is selected by clicking a checkbox.
Key Identifier
This option uses the <wss:KeyIdentifier> element to specify a reference to an X.509 certificate by means of a reference to its X.509 SubjectKeyIdentifier attribute. If a Key Identifier is specified without a ValueType it will be interpreted in an application-specific manner.
Issuer Serial
This option uses the <ds:X509IssuerSerial> element to specify a reference to an X.509 security token by means of the certificate issuer name and serial number.
Embedded Token
This option uses the <wsse:Embedded> element specified within a <wsse:SecurityTokenReference> to create a reference to an embedded token.
Thumbprint
This option is a Key Identifier ValueType is used to specify a reference to an X.509 certificate by means of a reference to its X.509 Thumbprint attribute.
Derived Keys
Allows you to specify a Derived Key—a key management scheme in which for every transaction, a unique key is used which is derived from a fixed key. Note that WS-Security Policy Version 1.1 and 1.2 support different Derived Key options.

After completing your entries, click Next. The system saves your token changes and cycles back to the Specify Token options screen. The Token definition displays in the Token Choice list.

Configuring Binary Security Token options

The Specify Binary Token Options page provides options for configuring a Binary Token Assertion Type. This token type encoding is defined by configuring the @ValueType and @EncodingType attributes of the <wsse:BinarySecurityToken> element. The ValueType attribute allows a URI that defines the value type and space of the encoded binary data. The EncodingType attribute tells how the security token is encoded. The default value is Base64Binary and is currently the only value supported by WSS SOAP Message Security.

Configuring SAML Token options

SAML (Security Assertion Markup Language) is an Extensible Markup Language (XML) standard that allows a user to log on once for affiliated but separate websites. In accordance with WSS SOAP Message Security, SAML assertions can be used as security tokens from the <wsse:Security> header and with an XML signature to bind the subjects and statements of the assertions (claims) to a SOAP message.

Configuration (adding or modifying) of a SAML supporting token includes the options listed below, for configuring a SAML Token Assertion Type.

Version
The SAML version being used. Options:
  • SAML 1.0 Token Profile 1.0
  • SAML 1.0 Token Profile 1.1
  • SAML 1.1 Token Profile 1.0
  • SAML 1.1 Token Profile 1.1
  • SAML 2.0 Token Profile 1.1
Issuer
The URI of the authority in a network that issues and manages security credentials and public keys for message encryption (for example, Certificate Authority).
Derived Keys
Specify the key management scheme in which, for every transaction, a unique key is used which is derived from a fixed key. Note that WS-Security Policy Version 1.1 and 1.2 support different Derived Key options.

Configuring Kerberos Token options

Kerberos is an authentication service that allows users and services to demonstrate their identity to each other using a shared secret which is known by the user and service, and is used as an encryption key. Random keys (tickets) can then be attached to SOAP messages in accordance with the WSS SOAP Message Security which uses and references the Kerberos tokens.

Configuration (adding or modifying) of a Kerberos supporting token includes the options listed below.

Version
The Kerberos version being used. Options:
  • Kerberos Version 5 AP-REQ
  • GSS Kerberos Version 5 AP-REQ
Issuer
The URI of the authority in a network that issues and manages security credentials and public keys for message encryption (for example, Certificate Authority).
Required Key Identifier Reference
Allows the <wss:SecurityTokenReference> to reference the <wsse:KeyIdentifier> element.
Derived Keys
Allows you to specify a Derived Key—a key management scheme in which for every transaction, a unique key is used which is derived from a fixed key.

Configuring Username Token options

The Username token type provides a WSS SOAP Message Security method that can utilize a username via the <wss:UsernameToken> element. An optional password can also be specified within the <wss:UsernameToken> element by specifying a <wsse:Password> element.

Configuration (adding or modifying) of a Username supporting token includes the options listed below.

Version
The username token version being used. Options:
  • UsernameToken Profile 1.0
  • UsernameToken Profile 1.1
  • Not Specified
Derived Keys
Allows you to specify a Derived Key—a key management scheme in which for every transaction, a unique key is used which is derived from a fixed key. Note that WS-Security Policy Version 1.1 and 1.2 support different Derived Key options.

Configuring Issued Token options

The Issued Token assertion type is issued by a Certificate Authority (CA), using the mechanisms defined in WS-Trust. It is used primarily in third party scenarios. For example, the initiator may need to request a SAML token from a given token issuer to secure messages sent to the recipient.

Configuration (adding or modifying) of an Issued supporting token includes the options listed below.

Issuer
Specify either the name or the address (URL) of the Certificate Authority.
Derived Keys
Indicate whether derived keys are required, or there are none.
Require External Reference
Determines whether an external reference is required when referencing this token. The reference will be supplied by the issuer of the token.
Require Internal Reference
Determines whether an internal reference is required when referencing this token. The reference will be supplied by the issuer of the token.

Configuring Secure Conversation Token options

Secure Conversation is a feature designed to improve the performance of an application that needs to interchange more than one message with a service. When enabled, the token negotiation and authentication happens once compared to other tokens where that negotiation is done for each request to the service. In the first negotiation, the client sends a RequestSecurityToken message to the service in order to ask for a session token. After that, the service creates a new token called Security Context Token (SCT), which contains a reference to the original token and a symmetric key to perform cryptographic operations like encrypt or sign messages.

Configuration (adding or modifying) of a Secure Conversation supporting token includes the options listed below.

Issuer
Specify either the name or the address (URL) of the Certificate Authority.
Derived Keys
Indicate whether derived keys are required, or there are none.
Require External URI Reference
Determines whether the URI used by a Security Context Token (SCT) will be externally referenced.
Use Security Context Token
Determines whether references to Security Context Tokens (SCT) in messages must use an external URI.

Configuring Spnego Token options

Configuration (adding or modifying) of an Spnego supporting token includes the options listed below.

Issuer
Specify either the name or the address (URL) of the Certificate Authority.
Derived Keys
Indicate whether derived keys are: Explicit, Implied, Both, or None.

Activating a policy

When you create and configure a policy, the policy is in Draft state. When the policy configuration is complete, activate the policy: click Activate Policy and then confirm. See Activate a Policy.

A policy in Draft state is not available for general use. Once you activate the policy, it is in Active state and is available for use.

Attaching a policy

To use the policy, go to the Policies folder in the respective organization and attach the policy to a web service, binding, or binding operation.