Using the WS-Security Symmetric Binding Policy

Learn about the WS-Security Symmetric Binding Policy.

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

Table of Contents

About WS-Security Symmetric Binding policy

The WS-Security Symmetric Binding Policy provides support for the Symmetric Binding Assertion. When a symmetric binding is used only one party needs to generate the security tokens. A symmetric key is established using that security token and additional signing and encrypting is performed using this token.

For example, symmetric binding can be used when only the server possesses an X509 Token. In this scenario, the initiator first creates a temporary key and then creates an encrypted key and encrypting the temporary key using the recipient's public key. This temporary key is then used for both signing and encrypting messages back and forth. This mechanism allows a service to sign and encrypt messages even with an anonymous client. If a service wants to authenticate its clients, this can be accomplished using supporting tokens.

Symmetric binding defines three token properties: Protection Token, Signature Token, and Encryption Token. If the same token is used for signature and encryption, the Protection Token can be used. Otherwise, you can use separate Signature Token and Encryption Token properties.

Creating a WS-Security Symmetric Binding policy

The first step in creating a policy is to define the basic policy information. Then, you can configure the policy details.

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 Symmetric Binding policy

To configure a WS-Security Symmetric Binding 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 Modify WS-Security Symmetric Binding Policy wizard.
  4. In page 1, Specify Symmetric Binding Options, enter values for the binding options. For details about fields and values, see Specify Symmetric Binding Options below.
  5. In page 2, Specify Protection Token, 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.
  6. Click Next.
  7. The next page is determined by your choice of token type. Enter values as needed:
  8. In page 4, Configure Security Algorithm, specify required elements and namespace prefixes. For details, see Tab 4: Configure Security Algorithm below.
  9. In page 5, Specify WS-Security 1.0 Options, specify security options. For details, see Tab 5: Specify WS-Security 1.0 Options below.
  10. In page 6, Specify WS-Security 1.1 Options, specify security options. For details, see Tab 6: Specify WS-Security 1.1 Options below.
  11. In page 7, Specify WS-Trust 1.0 Options, specify trust options. For details, see Tab 7: Specify WS-Trust 1.0 Options below.
  12. In page 8, Specify Security Audit Options, specify audit options. For details, see Tab 8: Specify Security Audit Options below.
  13. Click Finish.

Tab 1: Specify Symmetric Binding Options

Policy Configuration: Specify Symmetric Binding Options

The Specify Symmetric Binding Options page includes the options listed below.

WS-Security Policy Versions
Specify the WS-Security Policy version. Versions 1.1 and 1.2 are currently supported.
Security Header Layout
Allows you to select from a set of optional properties that are common to security bindings. These properties define rules for controlling the ordering layout when items are added to the Security Header. For properties that are enabled, assertions will set the value of a property. When the value appears in a policy, the property is set to the value indicated by the assertion.
Include Timestamp
Checkbox indicating whether a timestamp must be provided.
Encrypt Before Signing
Checkbox indicating whether encryption must be performed before signing.
Encrypt Signature
Checkbox indicating whether the signature must be encrypted.
Protect Tokens
Checkbox indicating whether the primary tokens of the message must be protected.
Only Sign Entire Headers and Body
Checkbox indicating whether the signature must cover the headers and body in their entirety instead of only portions.
Token Properties
You can choose either Use a Protection Token option (configured on the Specify Protection Token page) or Specify tokens for Encryption and Signature (configured on the Specify Encryption Token and Specify Signature Token pages).

Tab 2: Specify Protection Token

The Specify Protection Token page includes the options listed below.

Token Type
Token type. Choices: X.509, Binary Security, SAML, Kerberos, Username, Issued Token, Secure Conversation, or Spnego. The next page of the wizard is custom to the selected token type.
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.

Tab 3-1: Specify X.509 Token Options

The Specify X.509 Token Options page 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> element 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 to go to the Configure Security Algorithm page. See Tab 4: Configure Security Algorithm.

Tab 3-2: Specify 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.

After completing your entries, click Next to go to the Configure Security Algorithm page. See Tab 4: Configure Security Algorithm.

Tab 3-3: Specify SAML Token Options

The Specify SAML Token Options page includes the options listed below.

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.

After completing your entries, click Next to go to the Configure Security Algorithm page. See Tab 4: Configure Security Algorithm.

Tab 3-4: Specify Kerberos Token Options

The Specify Kerberos Token Options page 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.

After completing your entries, click Next to go to the Configure Security Algorithm page. See Tab 4: Configure Security Algorithm.

Tab 3-5: Specify Username Token Options

The Specify Username Token Options page 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.

After completing your entries, click Next to go to the Configure Security Algorithm page. See Tab 4: Configure Security Algorithm.

Tab 3-6: Specify Issued Token Options

The Specify Issued Token Options page 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.

After completing your entries, click Next to go to the Configure Security Algorithm page. See Tab 4: Configure Security Algorithm.

Specify Secure Conversation Token Options

The Specify Secure Conversation Token Options page 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.

After completing your entries, click Next to go to the Configure Security Algorithm page. See Tab 4: Configure Security Algorithm.

Tab 3-8: Specify Spnego Token Options

The Specify Spnego Token Options page 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.

After completing your entries, click Next to go to the Configure Security Algorithm page. See Tab 4: Configure Security Algorithm.

Tab 4: Configure Security Algorithm

Policy Configuration: Specify Security Algorithm

The Configure Security Algorithm page includes the options listed below.

Algorithm Suite
Choose the algorithm suite that the policy will use for performing cryptographic operations with symmetric or asymmetric key based security tokens. Choices:
  • Basic128
  • Basic 192
  • Basic 256
  • TripleDes
  • Basic256Rsa15
  • Basic192Rsa15
  • Basic128Rsa15
  • TripleDesRsa15
  • Basic256Sha256
  • Basic192Sha256
  • Basic128Sha256
  • TripleDesSHA256
  • Basic256Sha256Rsa15
  • Basic192Sha256Rsa15
  • Basic128Sha256Rsa15
  • TripleDesSHA256Rsa15

For more detailed information about the algorithm suites, see Supported WS-Security Algorithm Suites.

Canonicalization
Allows you to select the canonical form used to test whether information content of an XML document has changed.
The default, Exclusive, determines which namespaces are actually being used and just copies those. You can set this field to Inclusive, which copies all declarations, even if they are defined outside of the scope of the signature.
XPath Version
Indicates the XPath version to be used: 1.0 (XPath10), 2.0 (XPathFilter20), or Not Specified (the default).
SOAP Normalization
Checking the box indicates that SOAP normalization is turned on.
STR Transform
Checking the box indicates that the STR Transform property is set to STRT10.

Tab 5: Specify WS-Security 1.0 Options

Policy Configuration: Specify WS-Security 1.0 Options

The Specify WS-Security 1.0 Options page includes the options listed below.

Do not specify options
Indicates that no WS-Security 1.1 options are specified. This is the default.
Specify options
Indicates that the specified options will apply to the policy.
Must Support Key Identifier Reference
Allows you to specify that Key Identifier References must be supported.
Must Support Issuer Serial Reference
Allows you to specify that Issuer Serial References must be supported.
Must Support External URI Reference
Allows you to specify that External URI References must be supported.
Must Support Embedded Token Reference
Allows you to specify that Embedded Token References must be supported.

Tab 6: Specify WS-Security 1.1 Options

Policy Configuration: Specify WS-Security 1.1 Options

The Specify WS-Security 1.1 Options page includes the options listed below.

Do not specify options
Indicates that no WS-Security 1.1 options are specified. This is the default.
Specify options
Indicates that the specified options will apply to the policy.
Must Support Key Identifier Reference
Allows you to specify that Key Identifier References must be supported.
Must Support Issuer Serial Reference
Allows you to specify that Issuer Serial References must be supported.
Must Support External URI Reference
Allows you to specify that External URI References must be supported.
Must Support Embedded Token Reference
Allows you to specify that Embedded Token References must be supported.
Must Support Thumbprint Reference
Allows you to specify that Thumbprint References must be supported.
Require Signature Confirmation
Allows you to specify that the Signature Confirmation property is set to true.
Must Support Encrypted Key Reference
Allows you to specify that the Encrypted Key References property is set to true.

Tab 7: Specify WS-Trust 1.0 Options

Policy Configuration: Specify WS-Trust 1.0 Options

The Specify WS-Trust 1.0 Options page allows you to configure a set of properties supported by WS-Trust 1.0 when the Trust10 assertion is part of the Endpoint Policy Subject. It includes the options listed below.

Do not specify options
Indicates that no WS-Trust 1.0 options will be specified in the policy.
Specify options
Indicates that the specified options will apply to the policy.
Must Support Client Challenge
Allows you to specify that client challenges must be supported.
Must Support Server Challenge
allows you to specify if server challenges must be supported.
Require Client Entropy
Allows you to specify that client entropy is required.
Require Server Entropy
Allows you to specify that server entropy is required.
Must Support Issued Tokens
Allows you to specify that issued tokens must be supported.

Tab 8: Specify Security Audit Options

Policy Configuration: Specify Security Audit Options

Choose from the available options controlling the audit data that's captured:

Generate Audit Data
Captures all message data, whether success or failure, for all message exchanges.
On Error Only
If you choose to generate audit data, you can specify that audit data is captured only when an error occurs on a message exchange.

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.