Web Services Security Guides › CA SiteMinder® Web Services Security Policy Configuration Guide › (Optional) Configure Responses to Generate SAML Session Tickets or WS-Security Headers for Outgoing Messages › How to Configure Responses to Produce WS-Security Headers

How to Configure Responses to Produce WS-Security Headers

To configure CA SiteMinder® Web Services Security to produce WS-Security headers, create a response and associate it with resources in a web service security policy. This response data is used by the SiteMinder WSS Agent to generate WS‑Security headers. The SiteMinder WSS Agent then inserts these headers into the SOAP message header and delivers them to the protected web service.

Use variable types, if needed, to pass data back to the web service. Variables are resolved by the Policy Server at run time, when it generates the response.

To configure responses to produce WS-Security Headers for outgoing messages, do the following procedures:

1. Verify certificate requirements.
2. Review supported authentication schemes for producing different WS-Security token types.
3. If required, configure CA SiteMinder® Web Services Security to produce SAML assertions.
4. Configure a response to produce WS-Security headers.

More information:

Review Supported Authentication Schemes for Producing Different WS-Security Header Types

Verify Certificate Requirements

Before you configure a response to produce WS‑Security headers, verify that the following requirements are met:

• To produce signed WS‑Security tokens, verify that your enterprise private key and certificate chain are present in the certificate data store (CDS).
• To produce WS‑Security X509v3 tokens, verify that your enterprise private key and certificate chain are present in the certificate data store (CDS).

Review Supported Authentication Schemes for Producing Different WS-Security Header Types

You can configure responses to produce any type of WS-Security token upon successful authorization of a request. However, not every authentication scheme gathers all the necessary information (username, clear text password, SOAP message) from an incoming request to create every type of token.

If a response is configured to create a token that requires anything that the configured authentication scheme does not provide, header creation fails. Verify that the authentication method that you plan to use is suitable to produce the WS-Security token that you want to produce in response.

The following table shows which WS-Security tokens can be produced for each authentication method.

Configure CA SiteMinder® Web Services Security to Generate SAML Assertions

If you are configuring CA SiteMinder® Web Services Security to add WS-Security headers containing SAML assertions tokens to outgoing messages, you must first perform some additional configuration in the Administrative UI

In all SAML token generation situations, you must create an Affiliate domain. Additionally, you must perform the following steps depending on the version of SAML tokens you need to generate:

• To create SAML 1.1 assertions, configure the SAML 1.x Assertion Generator properties file and add Affiliate objects to the Affiliate domain.
• To create SAML 2.0 assertions, add SAML 2.0 Service Provider objects to the Affiliate domain.

Note: Affiliate domains and related SAML token functionality are implemented as part of CA SiteMinder® Federation Security Services on the Policy Server. For more information, see Federation Manager Guide: Legacy Federation and Federation Manager Guide: Partnership Federation.

SAML 1.x Assertion Generator

If you are configuring CA SiteMinder® Web Services Security to add WS-Security tokens containing SAML 1.x assertions to SOAP documents for consumption by other web services, you must configure the SAML Assertion Generator to produce the SAML 1.1 assertions that will be used in those tokens.

Note: The SAML Assertion Generator is a component of CA SiteMinder Federation Security Services on the Policy Server. For more information, see the CA SiteMinder Federation Security Services Guide.

The SAML Assertion Generator uses static configuration data from two sources to determine how to construct assertions:

SAML Assertion Generator Properties File

Specifies domain-wide SAML assertion generation parameters

Affiliate Objects

Define a set of parameters for the SAML Assertion Generator

Once configured, the SAML Assertion Generator is triggered to generate an assertion when a WS-Security SAML response (which specifies the affiliate to use to generate the assertion and dynamic information about how the assertion and message should be signed) is triggered by an authorizing policy.

Configure the AMAssertionGenerator.properties File

The AMAssertionGenerator.properties file contains domain-wide configuration parameters required for generating SAML assertions.

To configure the AMAssertionGenerator.properties file for CA SiteMinder® Web Services Security

1. Navigate to the following location: policy_server_home/config/properties
2. Open the AMAssertionGenerator.properties file in a text editor.
3. Modify the following parameters:

   AssertionIssuerID

   Specifies the URL of the authentication web service that is issuing the assertion. Must match the Issuer DN in the enterprise certificate. This value is used for unsigned assertions. For example:

   AssertionIssuerID = http://www.acmewidget.com/ordering

   SecurityDomain

   Specifies the domain name of the enterprise issuing the assertion. For example:

   SecurityDomain = www.example.com

   SourceID

   Not used by CA SiteMinder® Web Services Security.

4. Save the file and exit the text editor.
5. Restart the Policy Server. (Changes made to the AmAssertionGenerator.properties file will not be picked up by the Policy Server until it is restarted.)

Configure Affiliate Domains and Affiliate Objects

You require an affiliate domain containing and affiliate object to configure the SAML Assertion Generator produce SAML 1.x assertions in WS-Security SAML tokens.

To configure affiliate domains and affiliate objects, follow the associated procedures in Federation Manager Guide: Legacy Federation. However, because CA SiteMinder® Web Services Security does not use the affiliate object to define an affiliate organization, you do not need to specify all the options.

Note: Affiliate objects configured for CA SiteMinder® Web Services Security do not define the affiliate organization for which the assertion is intended. Assertions generated for CA SiteMinder® Web Services Security can be sent to any web service protected by the WS-Security authentication scheme (or similarly capable third-party security application).

The following list summarizes the affiliate configuration parameters that CA SiteMinder® Web Services Security uses to generate WS-Security SAML tokens. The wizard may require you to enter values for other parameters, but these are not used by CA SiteMinder® Web Services Security.

General page

General section: Name

Specifies the name of the affiliate object (must be unique across all affiliate domains).

This name is referenced by WS-Security policy responses (by defining a txm_wssec_saml_affiliate attribute whose value matches the name of the affiliate object).

General section: Active

Activates the affiliate object.

This option must be set for CA SiteMinder® Web Services Security to produce SAML 1.x assertions.

Restrictions section: Time

(Optional) Specifies times when assertion can be issued.

Restrictions section: IP Address

(Optional) Specifies IP addresses that are allowed to generate SAML assertions.

User page

Add Members

Specifies the users and groups (from the user directory or directories defined in the affiliate domain) for whom assertions should be generated.

Assertions page

General section: Audience

(Optional) Specifies the URI of a document that describes the terms and conditions of the agreement between the token issuer and consumer. This value is added to the assertion and can be used for authentication purposes. (If a request’s assertion token contains an audience value, that value must match one specified in the WS-Security scheme for the request to be authenticated.)

Additionally, the web service can parse the actual audience document to obtain additional information.

General section: Validity Duration Second(s)

(Optional) Specifies the amount of time, in seconds, that the assertion will be valid.

General section: Skew Time Second(s)

(Optional) Specifies the difference, in seconds, between the system clock time of the SAML assertion producer and the system clock time of the SAML assertion consumer.

Session section: Shared Sessioning

Not used by CA SiteMinder® Web Services Security (leave option unset).

Attributes section: Add

(Optional) If specified, an attribute statement will be included in the assertion that can be used for use in authentication and authorization decisions.

Configure SAML 2.0 Service Providers

SAML Service Provider objects define parameters used by the SAML Assertion Generator to produce SAML 2.0 assertions for use in WS-Security SAML tokens.

Note: When you configure a service provider object for use by CA SiteMinder® Web Services Security, you are not defining a service provider organization for which the assertion is intended. Assertions generated for CA SiteMinder® Web Services Security can be sent to any web service protected by the WS-Security authentication scheme (or similarly capable third-party security application).

To configure SAML Service Provider objects, generally follow the associated procedures in the CA SiteMinder Federation Security Services Guide. However, because CA SiteMinder® Web Services Security does not use the affiliate object to define a service provider organization, you do not need to specify all the options. Fields whose use is different for use by CA SiteMinder® Web Services Security are described below.

Name

Specifies the name of the service provider object (must be unique across all affiliate domains). This name is referenced by WS-Security policy responses (by defining a txm_wssec_saml_affiliate attribute whose value matches the name of the affiliate object).

Enabled

Sets the Enabled check box to activate the service provider object. This option must be set for CA SiteMinder® Web Services Security to produce SAML 2.0 assertions.

Authentication URL

Not used by CA SiteMinder® Web Services Security. However, a valid value is required. CA recommends using "http:\\localhost\"

Application URL

Not used by CA SiteMinder® Web Services Security.

SSO Tab: Bindings

Choose the HTTP-Post option.

Configure a Response to Produce WS-Security Headers

To define the properties of WS-Security headers you want CA SiteMinder® Web Services Security to produce, create a WS-Security header response in an application security policy.

Note: If you are using the domain security model, create a WS-Security header response in the web service domain.

Follow these steps:

1. Create an application object or modify an existing application object that defines the security policy for a web service.
2. Click the Response tab.
3. Click Create Response.

   The Create Application Response pane opens.

4. Type the response name in the General section.
5. Add response attributes that define the properties of the WS-Security headers, by doing the following steps:
   1. Click Create Response Attribute. The Create Response Attribute pane that opens
   2. Select the WebAgent-WS-Security-Token response attribute type from the Attribute drop-down list in the Attribute Type section.

      Note:

   3. Select the attribute type (Static, User Attribute, DN Attribute, or Active Response) in the Attribute Kind section.

      The fields on the Attribute Fields group box are updated to match the specified attribute type.

   4. Specify a required name/value pair (listed in the following sections) in the Attribute Fields section. Enter values directly in the Variable Name and Variable Value fields or populate those fields with valid values from the Select a Name and Select a Value drop-down lists.
   5. Specify Cache Value or Recalculate value every ... seconds on the Attribute Caching group box.
   6. Click Submit.

      The Create Response Attribute Task is submitted for processing, and the response attribute is added to the Attribute List on the Create Response Attribute pane.

6. Create further response attributes as required.
7. Click OK.

   The Create Response Task is submitted for processing and you are returned to the Responses tab.

Note:

More information:

(Mandatory) Response Attribute Variable for Specifying the Generated WS-Security Token Type

Response Attribute Variables for Encrypting/Decrypting WS-Security Messages

Response Attribute Variables for Handling WS-Security Headers

(Mandatory) Response Attribute Variable for Specifying the Generated WS-Security Token Type

The TXM_WSSEC_TOKEN_TYPE variable name/value pair determines the WS‑Security token type to generate. A response attribute that defines TXM_WSSEC_TOKEN_TYPE is required in all WS-Security header responses.

TXM_WSSEC_TOKEN_TYPE

Specifies the type of WS‑Security token the SiteMinder WSS Agent should create and add to the WS‑Security header for message authentication:

Attribute kind: Static

Variable value: One of the following:

• password—Creates a Username and Password Digest token, providing for password digest message authentication. For this token type, the TXM_WSSEC_USER_
  PASSWORD response variable must also be configured.
• password_nodigest—Creates a Username and Password token, providing clear text password message authentication. For this token type, the TXM_WSSEC_USER_
  PASSWORD response variable must also be configured.
• X509—Creates an X509v3 token.
• SAML—Creates a SAML token, providing for SAML message authentication. For this token type, the TXM_WSSEC_SAML_AFFILIATE response variable must also be configured.

More information:

Review Supported Authentication Schemes for Producing Different WS-Security Header Types

Response Attribute Variables for Generating Username and Password and X.509 Certificate Tokens

The following table describes the response variable name/value pairs for generating username and password (digest or clear text) and X.509 certificate tokens in WS-Security headers. That is, if the TXM_WSSEC_TOKEN_TYPE response attribute variable is set to password, password_nodigest, or X509.

More information:

Username and Password Digest Token

Review Supported Authentication Schemes for Producing Different WS-Security Header Types

Response Attribute Variables for Generating SAML Tokens

The following table describes the response attribute variable name/value pairs for generating SAML tokens in WS-Security headers. That is, if the TXM_WSSEC_TOKEN_TYPE response attribute variable is set to SAML.

More information:

WS-Security SAML Assertion Token

Configure CA SiteMinder® Web Services Security to Generate SAML Assertions

Review Supported Authentication Schemes for Producing Different WS-Security Header Types

Response Attribute Variables for Encrypting/Decrypting WS-Security Messages

The following table describes response attribute variable name/value pairs that can be configured to tell the SiteMinder WSS Agent to encrypt message elements or to pass a decrypted version of a message to the recipient web service.

Note: There are two versions of each XML encryption-related name/value pair—use the former for use with messages with username/password or X.509 tokens, use the latter for use with messages with SAML tokens.

Response Attribute Variables for Handling WS-Security Headers

The following table describes response attribute variable name/value pairs that can be configured to tell the SiteMinder WSS Agent how to handle the mustUnderstand attribute in WS‑Security request , or to remove the mustUnderstand or the entire security token from messages passed to the recipient web service.

More information:

TXM_WSSEC_MUST_UNDERSTAND Response Variable Effect Detail

TXM_WSSEC_MUST_UNDERSTAND Response Variable Effect Detail

The following table describes the exact behavior of the SiteMinder WSS Agent when consuming and producing WS‑Security tokens with different values of the TXM_WSSEC_MUST_UNDERSTAND response variable name/value pair.

WS-Security Response Examples

The following examples show how you can use WS‑Security responses.

Example 1

This example shows how to create a response that generates a Username and Password Digest token and uses the enterprise private key to digitally sign the message’s SOAP envelope.

The following table shows the response attributes you must add to the response (all attributes are of type WebAgent-WS‑Security-Token):

Example 2

This example shows how to create a response that generates an X509v3 token and uses the enterprise private key to digitally sign the message’s SOAP envelope.

The following table shows the response attributes you must add to the response (all attributes are of type WebAgent-WS‑Security-Token):

Example 3

This example shows how to create a response that generates a SAML assertion token using the holder-of-key subject confirmation method, retrieving the subject’s public key from an associated user store.

The following table shows the response attributes you must add to the response (all attributes are of type WebAgent-WS‑Security-Token):

Example 4

This example shows how to create a response that encrypts an incoming document and deliver the encrypted document to the web service.

The response generates a SAML assertion token using the sender vouches subject confirmation method and encrypts the SAML assertion and message body. The token and other related information are placed in a WS‑Security header identified by the SOAP actor/role samlrole.

The SAML assertion and the message body are encrypted using the public key certificate found in the WS‑Security header with the role pubkeyrole. The rsa-1_5 algorithm should be used to encrypt the symmetric encryption key; the tripledes-cbc algorithm should be used to encrypt the assertion and body data.

The document should be signed before encryption; the document and assertion should also be signed with a sender-vouches signature.

The following table shows the response attributes you must add to the response (all attributes are of type WebAgent-WS‑Security-Token):

Example 5

This example shows how to create a response that decrypts an incoming encrypted message and passes it to the associated web service in a message with a SAML assertion token.