How to Configure Responses to Produce SAML Session Tickets

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 SAML Session Tickets

How to Configure Responses to Produce SAML Session Tickets

To configure CA SiteMinder® Web Services Security to produce SAML Session Tickets, create a response and associate it with resources in a web service authorization policy. This response data is used by the SiteMinder WSS Agent to generate SAML Session Tickets. The SiteMinder WSS Agent then delivers the SAML Session Ticket 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.

Diagram illustrating how to configure responses to produce SAML Session Tickets

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

More information:

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

Verify Certificate Requirements

If the public keys used in assertions are going to be stored in the user directory, define an attribute in your directory to store these public keys, and make sure it is available to the Policy Server.

Note: This is not required if the public key is included in the client’s submitted XML document or obtained from a certificate over the SSL link.

Configure a Response to Produce a SAML Session Ticket

To define the properties of the SAML Session Ticket you want CA SiteMinder® Web Services Security to produce, create a SAML Session Ticket response in an application security policy.

Note: If you are using the domain security model, create a SAML Session Ticket response in the web service domain.

Follow these steps:

Create an application object or modify an existing application object that defines the security policy for a web service.
Click the Response tab.
Click Create Response.
The Create Application Response pane opens.
Type the response name in the General section.
Add response attributes that define the properties of the SAML Session Ticket, by doing the following steps:
1. Click Create Response Attribute. The Create Response Attribute pane that opens
2. Select the WebAgent-SAML-Session-Ticket response attribute type from the Attribute drop-down list in the Attribute Type section.
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.
Create further response attributes as required.
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

SAML Session Ticket Response Attribute Variables

The following table lists the response attribute variable name/value pairs specific to the WebAgent-SAML-Session-Ticket-Variable attribute. You can use these variables to build assertions.

Note: You can configure other response variables with the SAML Session Ticket attribute; however, they are ignored by CA SiteMinder® Web Services Security for the assertion and are handled as standard response attributes by CA SiteMinder®.

Variable Name	Variable Value	Attribute Kind	Meaning
TXM_SAML_Location (required)	Envelope_Header (default) HTTP_Header Cookie_Header	Static	Instructs the SiteMinder WSS Agent to insert the assertion into the SOAP envelope message header, an HTTP header, or a cookie header. If Envelope_Header is the value, the client must provide an XML message for the assertion. If HTTP_Header is the value, an HTTP header named tmsamlsessionticket is added to the HTTP headers delivered to the web service If Cookie_Header is the value, the assertion is inserted into a cookie named tmsamlsession and returned to the caller in an HTTP Set-Cookie header. The cookie can also be read by the web service application at the URI protected by CA SiteMinder® Web Services Security. Note: Do not attempt to place more than one signature in a cookie—a 4 KB limit on the size of cookies that can be returned by the SiteMinder WSS Agent results in no cookie being generated if it would be greater than 4KB.
TXM_Force_Logon (optional)	Yes or No	Static	Forces the client to authenticate using the authentication scheme for the target realm. This variable is useful if a client tries to get an assertion when logging on with only a cookie. The client is allowed access to the web service, but does not receive an assertion because the client has only a cookie. To inform the user that they have to logoff and then get rechallenged to obtain the assertion, the web service can be set up to redirect the client to a log-off URI. The user can then come back to the web service and be challenged again to obtain the assertion. Note: To find out how to set up a log-off URI, see the Web Agent Configuration Guide.
TXM_Issuer (optional)	URI	Static	Indicates the issuer of the assertion. Value is placed in the issuer URI field in the generated assertion. If the assertion is sent to a third party, the third party can use this variable to validate the assertion by sending it back to the specified URI.
TXM_Namequalifier (optional)	Domain name	Static	Indicates the domain name of the subject of the assertion.
TXM_Sign (optional)	Yes or No	Static	Tells the SiteMinder WSS Agent to sign the SOAP document payload with the private key dynamically generated by the Policy Server. NOTE: If you use this variable, do not use the TXM_Public_Key variable.
TXM_Sign_Assertion (optional)	Yes or No	Static	Tells the SiteMinder WSS Agent to sign the assertion that is part of the SOAP document. This ensures that no one can alter the assertion.
TXM_Public_Key (optional)	XMLDSIG Client_Cert User_Store	Static	Tells the SiteMinder WSS Agent where to get the public key that it binds to the session ticket. XMLDSIG—Tells SiteMinder WSS Agent to get the key from the document with the digital certificate. (Web service must be protected by the XML Digital Signature authentication scheme.) Client_Cert—Indicates the client certificate sent over the SSL connection User_Store—Tells SiteMinder WSS Agent to get the key from the user store. Note: Do not use this variable with TXM_Sign.
TXM_User_Cert LDAP user directories only (optional)	usercertificate This value is the most common for LDAP user directories. If you have used a custom naming scheme for your LDAP directory, the value will be different.	User Attribute	Specifies the LDAP query string that the SiteMinder WSS Agent uses to retrieve the public key from the user store. This variable is required when TXM_Public_Key is set to User_Store.

Note: Do not use the SAML assertion, XML Body, XML Agent, and XML Envelope Header variables that you can choose from the Variables policy object in a policy domain. These variables are for use exclusively in policy expressions, not with the SAML Session Ticket response.

Enter these variables by typing the name and value in the appropriate fields in the Response Attribute dialog.

SAML Session Ticket Response Examples

You can use assertion variables to help the SiteMinder WSS Agent build the assertion.

Example 1

If the web service is protected by the XML-DSIG authentication scheme, create an attribute that extracts the client’s public key from the certificate and adds it to the SAML assertion. To instruct the SiteMinder WSS Agent to get the public key from the digital certificate, enter the variable TXM_Public_Key with the value XMLDSIG.

The following table shows the properties of the primary response attribute:

Field	Value
Attribute	WebAgent-SAML-Session-Ticket-Variable
Attribute Kind	Static
Variable Name	TXM_Public_Key
Variable Value	XMLDSIG

If the public key is coming from the user directory, two response attributes are required. The properties of the first required response attribute would be as follows:

Field	Value
Attribute	WebAgent-SAML-Session-Ticket-Variable
Attribute Kind	User Attribute
Variable Name	TXM_User_Cert
Variable Value	usercertificate

The properties of the second required response attribute would be as follows:

Field	Value
Attribute	WebAgent-SAML-Session-Ticket-Variable
Attribute Kind	Static
Variable Name	TXM_Public_Key
Variable Value	User_Store

Example 2

To ensure that the assertion is placed in the SOAP envelope message header, the properties of the required response attribute would be as follows:

Field	Value
Attribute	WebAgent-SAML-Session-Ticket-Variable
Attribute Kind	Static
Variable Name	TXM_SAML_Location
Variable Value	Envelope_Header