45.4 Managing Token Validation Templates

A validation template is used to validate an incoming token.

It is optionally used to map the incoming token to either a Requester Partner or a user record:

For OnBehalfOf use cases, a WS-Trust Validation Template must be present.
For validating an Assertion, one Issuing Authority Partner Profile must be present.

The Security Token Service Endpoint is linked to a WSS Validation Template that indicates how to validate the token in the WSS header and how to map the token and binding data to a Requester.

This section provides the following topics.

45.4.1 About Managing Token Validation Templates

A Security Token Service Endpoint is always mapped with a WS-Security Validation Template that indicates how to map the request to a requester entry or to a user

If mapping is required and no match is found, processing will fail.
If no mapping is required, a default requester partner profile will be used.
In either case, a requester partner profile is retrieved.
If a mapping is performed to a user record, a default requester partner profile will be used.
If a mapping is performed to a requester partner entry, the requester partner profile for this partner will be used.

A validation template determines the token validation rules:

Whether or not to validate and map the incoming token.
The mapping rules to be used if mapping is enabled.

A validation template is specific to a token type and specific to a protocol as described in Table 45-8.

Table 45-8 Validation Template Protocols

Protocol	Description
WS-Security	Validates only WS-Security Tokens: Possible Mapping actions: no action, map binding data to partner, map incoming token to partner, map incoming token to user and binding data to partner, map incoming token to user Token Types supported: SAML 1.1, SAML 2.0, Username X.509, Kerberos, None. When you toggle the Token Protocol from WS-Trust to WS-Security, options in the Token Type list do not change. However, the required "Default Partner Profile" list appears from which you must choose one profile for WS-Security.
WS-Trust	Validates only Tokens included in OBO (on behalf of) field of the RST (request): Possible Mapping actions: none, map incoming token to user Token Types supported: SAML 1.1, SAML 2.0, Username, X.509, Kerberos, OAM, Custom.

Protocol

Description

WS-Security

Validates only WS-Security Tokens:

Possible Mapping actions: no action, map binding data to partner, map incoming token to partner, map incoming token to user and binding data to partner, map incoming token to user
Token Types supported: SAML 1.1, SAML 2.0, Username X.509, Kerberos, None.

When you toggle the Token Protocol from WS-Trust to WS-Security, options in the Token Type list do not change. However, the required "Default Partner Profile" list appears from which you must choose one profile for WS-Security.

WS-Trust

Validates only Tokens included in OBO (on behalf of) field of the RST (request):

Possible Mapping actions: none, map incoming token to user
Token Types supported: SAML 1.1, SAML 2.0, Username, X.509, Kerberos, OAM, Custom.

A validation template mapping rules determines how the incoming data is mapped to a user or a partner, using data from the incoming token:

Username for Username Token
UserID for Kerberos Token
NameID and attributes for SAML Token
DN Components for X.509 Token
Attributes from a Custom

Mapping is performed as follows:

Simple mapping: one incoming attribute matched against one user record attributes
Complex LDAP query: LDAP query with placeholders for incoming data (e.g.: (&(sn=%lastname%)(mail=%email%))
NameID Mapping table for SAML Token

Figure 45-7 illustrates default General details on the New Validation Template page.

Figure 45-7 New Validation Template page: General Page Defaults

Description of "Figure 45-7 New Validation Template page: General Page Defaults"

Table 45-9 describes the elements on the New Validation Template, General page.

Table 45-9 New Validation Template: General Details

Element	Description
Back	Click this button to return to the previous page.
Next	Click this button to proceed to the next page.
Cancel	Click this button to dismiss the page.
Validation Template Name	The name you choose for this template. For example: `email-wstrust-valid-temp`
Description	Optional.
Token Protocol	The type of Validation Template to be created. Type can be either: WS-Trust: This template will be used to validate and map tokens included in the OnBehalfOf element of the WS-Trust request. WS-Security: This template will be used to validate and map tokens located in the Security SOAP Header of the incoming message
Token Type	A list of in-bound token types from which you choose the one to use for this template. The token type options depends on the protocol type: WS-Trust: SAML 1.1, SAML 2.0, Username, X.509, Kerberos, OAM, Custom WS-Security: SAML 1.1, SAML 2.0, Username, X,509, Kerberos, None
Default Partner Profile	Only applies to WS-Security Validation Template References the default requester partner profile to use, in case the incoming request is not mapped to a requester partner. For example, if the request is mapped to a user instead. A requester partner profiles contains settings that are used during the request processing. If the incoming request was mapped to a requester partner, then the partner profile for that requester will be retrieved and used as the requester partner profile
Timestamp Lifespan	Applies only to Username and SAML Validation Templates. It determines the validity time of a Token (for Username Token, only if it contains a Created element indicating the instant it was created). Default: 1000 (seconds)
Authentication Details	Specific to username token validation template.
Enable Credential Validation	Check this box to enable validation using credentials contained in the username token. When enabled, Security Token Service will validate the username and the password elements contained in the username token, using the specified validation source. Note: password digest as defined in the Username Token WS-Security Profile is not supported in this release. See Also: Table 45-10

Figure 45-8 illustrates the General details page when Enable Credential Validation is checked.

As a result, the Authentication Details section of the page you can view its default values. This is specific to username token validation.

Figure 45-8 New Validation Template: General Authentication Details

Description of "Figure 45-8 New Validation Template: General Authentication Details"

Table 45-10 describes Authentication related details that are available when you choose Enable Credential Validation.

Table 45-10 New Validation Template: Authentication Details

Element	Description
Validation Source	A list from which you can choose a credential validation sources There are four types of validation sources when validating the credentials contained in a username token: LDAP: a standalone LDAP server will be used to validate the credentials. The connection information will need to be entered Embedded LDAP: the LDAP server embedded in the WebLogic server will be used to validate the credentials. No information is required. Userstore: the default User Identity Store configured in the Common Configuration -> Data Sources will be used to validate the credentials. No information is required in this validation template screen Partner: the credentials will be verified against the username/password information entered in the Requester Partner entries. Note: When selected, the Token Mapping configuration section is disabled, because the token will have been mapped to a requester partner after the credentials validation operation.
LDAP URL	The URL of the LDAP server.
Admin User	The username of an account used to perform lookups in the LDAP server.
Admin Password	The password of an account used to perform lookups in the LDAP server.
Base DN	The Base search DN used when looking up user records.
Enable HA	Indicates whether or not the LDAP server is in HA mode, fronted by a load balancer.
Person Object Class	The person object class associated with the user records.
Unique Id	The attribute of the user record containing the user unique identifier data.In most cases, is identical to the Credential ID field.
Credential Id	The attribute of the user record containing the username data. This field will be used to lookup user records, based on the username.
Maximum Connections	The maximum number of concurrent opened LDAP connections Default: 50
Connection Wait Timeout	Maximum amount of time to wait when opening a new connection. Default: 5000 (seconds)
Connection Inactivity Timeout	Maximum amount of inactivity time for an LDAP connection, before closing it. Default: 5000 (seconds)
Connection Read Timeout	Maximum number of concurrent opened LDAP connections. Default: 5000 (seconds)

Token Mapping

The Token Mapping section indicates the following:

If an incoming token needs to be mapped.
If the incoming token needs to be mapped, what kind of mapping is done. For example, mapping token to user, mapping token to partner, and so on.
How the mapping is done. For example, by mapping a token attribute to a partner/user attribute, or by using an LDAP query involving several token attributes.

Mapping rules determine how the incoming data is mapped to a user or a partner. The following data of the incoming token is used:

Username for UNT
UserID for Kerberos
NameID and attributes for SAML
DN Components for X.509
Attributes from custom

Mapping is performed using the following:

Simple mapping: One incoming attribute matched against one user record attributes.
Complex LDAP query: An LDAP query with placeholders for incoming data. For example, (&(sn=%lastname%)(mail=%email%))
A NameID Mapping table for SAML

Following are several Token Mapping Examples for a new Validation Template:

Figure 45-9 shows the mapping configuration settings.

They are required for Security Token Service to map the token to a user record, by matching the NameID value to user records that have a matching attribute, based on the following NameID format:

Enable Map Token to User
Enable Simple User Mapping
Disable Attribute Based User Mapping

Figure 45-9 Token Mapping: SAML2 WS-Security Validation Template

Description of "Figure 45-9 Token Mapping: SAML2 WS-Security Validation Template"

Figure 45-10 shows the mapping configuration settings.

They are required for Security Token Service to map the token to a user record by matching the username element of the Username token to a user record that has a matching uid.

The required settings are:

Enable Map Token to User
Enable Simple User Mapping
Datastore Attribute set to uid
Disable Attribute Based User Mapping

Figure 45-10 Token Mapping, username-wstrust-validation-template

Description of "Figure 45-10 Token Mapping, username-wstrust-validation-template"

Figure 45-11 shows the mapping configuration settings.

The settings are required for Security Token Service to map the token to a requester partner entry by matching the Subject DN of the certificate to a Requester Partner that has a match on SSL Client Cert DN Identification attribute.

The required settings are:

Map Token to Partner
Disable Simple User Mapping
Disable Attribute Based User Mapping
Enable Simple Partner Mapping

Figure 45-11 Token Mapping: x509-wss-validation-template

Description of "Figure 45-11 Token Mapping: x509-wss-validation-template"

Not all elements apply to all token types and token protocols. The elements that you must define varies.

Table 45-11 describes the token mapping elements for validation templates.

Table 45-11 New Validation Template: Token Mapping

Element	Description
Map Token to	WS-Security Validation Template: Map Token to list <empty>: no token mapping operation will occur Map token to Partner: The token will be mapped to a requester partner Map Token to User and map binding data to Partner: The token will be mapped to a user, and binding data (such as SSL Client Cert DN or HTTP Basic Auth Username) will be used to map the HTTP request to a requester partner Map token to User: The token will be mapped to a user - - - - - - - - - - WS-Trust Validation Template: Map Token to User Check the box to enable (or clear the checkbox to disable).
Enable Simple User Mapping	Simple user mapping consists of mapping the incoming token to a user record by using a single token attribute and matching it against a single user record attribute. WS-Security Validation Template: Only Username, SAML Assertion, Kerberos. and X.509. WS-Trust Validation Template: Username, SAML Assertion, Kerberos, X.509, OAM and custom token. The layout is different, depending on the token type of this validation template: Username Token: Datastore attribute references the user record attribute that will be matched against the username element of the username token. SAML Assertion: User Token attribute references an attribute from the incoming token that will be matched against the Datastore attribute (defined below) of a user record. The values can be STS_SUBJECT_ID for the NameID Value, or the name of an Attribute contained in the Assertion's AttributeStatement. In the Token Mapping section of a SAML Validation template, the User Token Attribute will either be the NameID selected from the drop down or a SAML Attribute name entered in the text field. Datastore attribute references the user record attribute that will be matched against the User token attribute referenced above. In the Token Mapping section of a SAML Validation template, the Datastore Attribute is the name of the directory attribute that will be used for the LDAP matching query. Kerberos: User Token attribute references an attribute from the incoming token that will be matched against the Datastore attribute (defined below) of a user record. The User Token Attribute can be specified by selecting one of the pre-populated attribute (Kerberos Principal, Kerberos Principal Primary or Kerberos Principal No Domain) or by entering a specific value. Datastore attribute references the user record attribute that will be matched against the User token attribute referenced above. X.509: User Token attribute references an attribute from the incoming token that will be matched against the Datastore attribute (defined below) of a user record. The User Token Attribute can be specified by selecting one of the pre-populated attribute (Subject DN, Common Name, Country Name, State or Province Name, Locality Name, Organizational Name, Organizational Unit Name or Domain Component) or by entering a specific value (which can be set to STS_X509_### by replacing ### with the upper case X.500 component name, for example STS_X509_CN to reference the common name component of the certificate subject). Datastore attribute references the user record attribute that will be matched against the User token attribute referenced above. OAM: Datastore attribute references the user record attribute that will be matched against the username element of the username token. Should be the user ID attribute defined in the Default User Identity Store. Custom: User Token attribute references an attribute from the incoming token that will be matched against the Datastore attribute (defined below) of a user record. The possible values are the names of the attribute returned by the custom token validation module. Datastore attribute references the user record attribute that will be matched against the User token attribute referenced above.
Enable User Name Identifier Mapping	When enabled, define the following: WSS and WS-Trust Validation Templates will contain the same section for the Name Identifier mapping settings. A NameID user mapping operation consists of mapping the incoming SAML Assertion to a user record by mapping the NameID Value to a single user record attribute, based on the NameID format When enabled, Security Token Service evaluates the NameID format, and based on the Name Identifier mapping table which user record attribute should be matched against the Name ID value contained in the Assertion. The Name Identifier mapping table holds the user record attributes to be used for the mapping operation. It contains standard NameID formats, but it can be customized to define custom Name ID formats. To add custom NameID format, click the add button on the Name Identifier mapping table, and enter the custom URI. To set an attribute for a specific NameID format to be used for mapping operation, set the user record attribute on the line for that format.
Enable Attribute Based User Mapping	WSS Validation Template: only Username, SAML Assertion, Kerberos and X.509. WS-Trust Validation Template: only Username, SAML Assertion, Kerberos, X.509 and custom token An Attribute Based User Mapping operation consists of mapping the incoming token to a user record by using an LDAP query and token attributes. The format of the LDAP query defines the mapping rule and specifies the token attributes to be used by their names, surrounded by the percent (%) character. For example, an LDAP query that will map a token based on two token attributes (firstname and lastname) would be (&(sn=%lastname)(givenname=%firstname%)). The possible token attributes depend on the token type. Username Token STS_SUBJECT_ID is the only available token attribute containing the username element of the Username token. SAML Assertion STS_SUBJECT_ID contains the NameID Value. STS_NAMEID_FORMAT contains the NameID Format STS_NAMEID_QUALIFIER contains the NameID Qualifier STS_SAML_ASSERTION_ISSUER contains the Issuer of the Assertion Attributes present in the Assertion's AttributeStatement Kerberos STS_KERBEROS_PRINCIPAL_SHORT contains the Kerberos Principal attribute. STS_KERBEROS_PRINCIPAL_FULL contains the Kerberos Principal Primary attribute STS_KERBEROS_PRINCIPAL_NODOMAIN contains the Kerberos Principal No Domain attribute X.509 STS_SUBJECT_ID contains the Subject DN. STS_X509_CN contains the Common Name STS_X509_C contains the Country Name STS_X509_ST contains the State or Province Name STS_X509_L contains the Locality Name STS_X509_O contains the Organizational Name STS_X509_OU contains the Organizational Unit Name STS_X509_DC contains the Domain Component Custom Token The possible values are the names of the attribute returned by the custom token validation module.
Enable Simple Partner Mapping	Only for WSS Validation Template and for the following token types: Username, SAML Assertion, Kerberos, and X.509. A simple partner mapping operation consists of mapping the incoming token to a partner requester by using a single token attribute and matching it against a partner identification attributes. The layout is different, depending on the token type of this validation template Username Token Partner Datastore attribute references the partner identification attribute that will be matched against the username element of the username token. SAML Assertion Partner Token attribute references an attribute from the incoming token that will be matched against the Partner Datastore attribute (defined below) of a Requester Partner. The values can be STS_SUBJECT_ID for the NameID Value, or the name of an Attribute contained in the Assertion's AttributeStatement. Partner Datastore attribute references the partner identification attribute that will be matched against the Partner token attribute referenced above Kerberos Partner Token attribute references an attribute from the incoming token that will be matched against the Partner Datastore attribute (defined below) of a requester partner. The Partner Token Attribute can be specified by selecting one of the pre-populated attribute (Kerberos Principal, Kerberos Principal Primary or Kerberos Principal No Domain) or by entering a specific value. Partner Datastore attribute references the partner identification attribute that will be matched against the Partner token attribute referenced above X.509 Partner Token attribute references an attribute from the incoming token that will be matched against the Partner Datastore attribute (defined below) of a requester partner. The Partner Token Attribute can be specified by selecting one of the pre-populated attribute (Subject DN, Common Name, Country Name, State or Province Name, Locality Name, Organizational Name, Organizational Unit Name or Domain Component) or by entering a specific value (which can be set to STS_X509_### by replacing ### with the upper case X.500 component name, for example STS_X509_CN to reference the common name component of the certificate subject). Partner Datastore attribute references the partner identification attribute that will be matched against the Partner token attribute referenced above.
Enable Partner Name Identifier Mapping	When enabled, defines the following only for WSS Validation Template and for SAML token types: A NameID user mapping operation consists of mapping the incoming SAML Assertion to a user record by mapping the NameID Value to a single requester partner identification attribute, based on the NameID format. When enabled, Security Token Service will evaluate the NameID format, and based on the Name Identifier mapping table which partner identification attribute should be matched against the Name ID value contained in the Assertion. The Name Identifier mapping table holds the requester partner identification attributes to be used for the mapping operation. It contains standard NameID formats, but it can be customized to define custom Name ID formats. To add custom NameID format, click the Add button on the Name Identifier mapping table, and enter the custom URI. To set an attribute for a specific NameID format to be used for mapping operation, set the requester partner identification attribute on the line for that format.

45.4.2 Managing Token Validation Templates

Users with valid Administrator credentials can add, find, edit, or delete token validation templates.

This is a server side configuration. A default Token Validation Template exists. Skip any steps that you do not need. The Security Token Service Endpoint must be linked to a WS Security Validation Template that indicates:

how to validate the token in the Webservice Security header
how to map the token and binding data to a Requester

The information here can be applied when you want to validate the following:

WS-Security tokens present in the SOAP Header, of type: Username, SAML 1.1, SAML 2.0, X.509 and Kerberos.
WS-Trust tokens present in the OnBehalfOf element or in the ValidateTarget element of the WS-Trust request, of type: Username, SAML 1.1, SAML 2.0, X.509, Kerberos, OAM Session Propagation Token and custom tokens.

The following procedure includes several examples of input following specific parameters. Also, a brief translation appears within parentheses (). For instance: Name (username-token): email-wstrust-valid-temp. Values in your environment will be different.