SAML web single sign-on (SSO) TAI custom properties

SAML web single sign-on (SSO) trust association interceptor (TAI) custom properties

The following tables list the custom properties for the Security Assertion Markup Language (SAML) trust association interceptor (TAI). We can define these properties in the custom properties panel for the SAML TAI using the console.
To assign unique property names that identify each possible single sign-on (SSO) service provider (SP) partner, an sso_<id> is embedded in the property name and used to group the properties associated with each SSO partner. The sso_<id>s are numbered sequentially for each SSO service provider partner.
The SAML TAI custom properties can be grouped into three categories:

Global properties Applicable to all SSO partners configured for the SAML TAI.
IdP properties Applicable to identity providers configured for the SAML TAI. To assign unique property names that identify each identity provider partner, an idp_<id> is embedded in the property name and used to group the properties associated with each SSO IdP partner.
Service provider properties Applicable to a service provider. Grouped together for each SSO service provider partner under a unique sso_<id>.

All custom properties names are case sensitive.

Global SAML TAI custom properties

Property name Values Description
targetUrl Any URL value. Default target URL after successful validation of the SAMLResponse when there is no RelayState received from the IdP. Overridden by sso_<id>.sp.targetUrl.
useRelayStateForTarget
true (Default)
false Indicate if the RelayState should be used as the target URL. Overridden by sso_<id>.sp. useRelayStateForTarget.
allowedClockSkew Any positive number. Default is three minutes. Allowed clock skew in minutes when validating the SAML token. Overridden by sso_<id>.sp. allowedClockSkew.
enforceTaiCookie
true (Default)
false Indicate if the SAML TAI should check if an LTPA cookie is mapped to a subject created for the SSO partner. Overridden by sso_<id>.sp.enforceTaiCookie.
replayAttackTimeWindow Any integer value. Default is 30. Time, in minutes, within which the second request is rejected if two identical SAML tokens are received by the TAI. See also sso_<id>.sp. preventReplayAttack.

IdP SAML TAI custom properties

Property Name Values Description
sso_<id>.idp_<id>.SingleSignOnUrl Any URL value. URL of the SSO service of the IdP.
sso_<id>.idp_<id>.allowedIssuerDN No default Name of the Issuer who is allowed to sign the SAML token sent by the IdP. If the SAML token is not signed by this issuer, the token is rejected.
sso_<id>.idp_<id>.allowedIssuerName No default. Value of the <saml:Issuer> Issuer element in the SAML token. The SAML token received from the IdP is rejected if the Issuer in the token does not match this value.

Service provider SAML TAI custom properties

Property Name Values Description
sso_<id>.sp.acsUrl No default. We can specify one of the following values:

URL of the assertion consumer service (ACS):
https://host:<sslport>/samlsps/<any URI pattern String>

URL of the business application
This is the only required property for each sso_<id>. It specifies the URL of the ACS or business application.
sso_<id>.sp.cookiegroup No value. Tag to be added to an ltpa cookie for the configured SAML SSO partner. When a web request is received with an ltpa cookie, the ltpa cookie is valid only if the tag matches this value.
sso_<id>.sp.EntityID Default is value of sso_<id>.sp.aclUrl. Used to verify AudienceRestriction in the SAML assertion.
sso_<id>.sp.targetUrl No default. URL of the target application. Used when RelayState is not present in the client request.
sso_<id>.sp.useRelayStateForTarget true (Default) - Use the value of RelayState in the client request as the URL of the target application.
false - Use the value of sso_<id>.sp.targetUrl as the URL of the target application. Whether the RelayState value received in the client request should be used as the URL of the target application or not. If false, the sso_<id>.sp.targetUrl property is used as the URL of the target application.
sso_<id>.sp.login.error.page Required.and does not have a default value. Error page, IdP login page, or custom mapping class to which an unauthenticated client request is redirected to.
sso_<id>.sp.acsErrorPage Defaults to the value for sso_<id>.sp.login.error.page. Error page to use if the SAML token fails validation or authentication.
sso_<id>.sp.allowedClockSkew No default. This property specifies, in minutes, the time added to the token expiration time of the SAML token sent by the IdP.
sso_<id>.sp.trustStore No default. Truststore for validating the SAML signature. It specifies the name of a managed keystore.
sso_<id>.sp.trustAnySigner false (Default) - the signer certificate is verified for trust validation
true - any signer certificate is trusted without trust validation Whether the signer certificate of the SAML token is verified for trust validation. If true, any signer certificate is trusted.
sso_<id>.sp.keyStore No default. Keystore containing the private key for decrypting the encrypted SAML assertion.
sso_<id>.sp.keyName No default. Key name for decrypting the SAML assertion.
sso_<id>.sp.keyPassword No default. Key password for decrypting the SAML assertion.
sso_<id>.sp.keyAlias No default. Key alias for decrypting the SAML assertion.
sso_<id>.sp.wantAssertionsSigned true (Default) - the service provider requires the IdP to sign the SAML assertion
false - the SAML assertion is not required to be signed by the IdP If false, the SAML assertion is not required to be signed and the signature is not validated.
sso_<id>.sp.preserveRequestState true (Default) - the client state is saved and restored when it is redirected to the IdP login
false - the client state is not saved When the service provider redirects the client request to the IdP login, this property specifies whether the client state needs to be saved and restored after the client request is completed.
sso_<id>.sp.enforceTaiCookie true (Default)
false This property is used to indicate if the SAML TAI should check if an LTPA cookie is mapped to a subject created for the SSO partner.
sso_<id>.sp.realmName This can be any string value. Default is SAML Issuer name. Any SAML attribute. Used in conjunction with realmNameRange. The value of this attribute is used as the subject realm. If this realm does not exist in the list of realms specified by realmNameRange, the realm is rejected.
sso_<id>.sp.realmNameRange This property has no default value. List of allowed realm names and is used in conjunction with realmName. See the description of sso_<id>.sp.realmName.
sso_<id>.sp.principalName This can be any string value. Default Subject NameID. Any SAML attribute. The value of this attribute is used as the subject principal.
sso_<id>.sp.uniqueId This can be any string value. Default is Subject NameID. Any SAML attribute. The value of this attribute is used as the subject uniqueId.
sso_<id>.sp.groupName No default. Any SAML attribute. The value of this attribute is used as groups in the subject.
sso_<id>.sp.defaultRealm IssuerName (Default) - Use the SAML token Issuer as the default realm
NameQualifier - Use the SAML token NameQualifier as the default realm Specifies whether the Issuer or the NameQualifier from the SAML assertion is used as the default realm.
sso_<id>.sp.useRealm No default. Realm name and is used to override the default realm. This property also overrides the realmName property.
sso_<id>.sp.idMap idAssertion (Default) - the user specified in the SAML assertion is not checked in the local registry
localRealm - the SAML token user is verified in the local user registry
localRealmThenAssertion - if the user is found in the local registry, IDAssertion is used How the SAML token is mapped to the subject.
sso_<id>.sp.groupMap localRealm - Map the SAML token groups to groups and parent groups found in the local user registry
addGroupsFromLocalRealm - Map the SAML token groups to groups and parent groups in local user registry. The group membership for this user will contains the groups from SAML assertion and the groups found in local user registry. This property is used with IDAssertion and specifies how the SAML token is mapped to the groups.
sso_<id>.sp.userMapImpl No default Name of a custom user mapping module class. Used to map a user ID in the SAML token to another user ID that exists in the local user registry.
sso_<id>.sp.X509PATH No default The certificate store used for the intermediary certificates used in validating the SAML signature.
sso_<id>.sp.CRLPATH No default Certificate store used for certificate revocation lists (CRLs) used in validating the SAML signature.
sso_<id>.sp.filter No default Specify a condition that is checked against the HTTP request, to determine whether or not the HTTP request is selected for a SAML web SSO partner. See the SAML TAI filter property section for more information on this property.
sso_<id>.sp.preventReplayAttack true (Default)
false Specify whether the SAML TAI should prevent two identical SAML tokens from being sent in client requests. This property is used in conjunction with the global property replayAttackTimeWindow.
sso_<id>.sp.trustedAlias No default If specified, only the key specified by this alias is used to validate the signature in the SAML assertion. If the signature in the incoming SAML assertion of the SAMLResponse does not include the KeyInfo element, specify this property to resolve the KeyInfo element.

sso_<id>.sp.charEncoding
No default. An example setting is UTF-8. Character encoding used to override the setting in the HTTPServletRequest.

sso_<id>.sp.disableDecodeURL
true
false (Default) When true, the original URL for redirect is used, without decoding the URL.

SAML TAI filter property

The sp.filter SAML TAI filter property is used when a client invokes a protected service provider application directly, without authenticating to the IdP. The filter property is usually used in conjunction with the sp.login.error.page property to redirect an unauthenticated client request to the URL address specified by the sp.login.error.page property.
The filter property specifies a set of conditions that are compared against the HTTP request of the client to select a SAML web SSO service provider partner for processing the HTTP request. Each condition is specified by three elements:

input required - the input element usually specifies an HTTP header name, but request-url and remote-address can also be used as special elements
operator - the operator element specifies one of the following values: ==, !=, %=, ^=, <, and >
comparison value - this element usually specifies a string, but IP address ranges are also allowed

The conditions are evaluated from left to right, as specified by the comparison value. If all the filter conditions specified by an SSO service provider partner are met in an HTTP request, the SSO service provider partner is selected for the HTTP request.
The input element identifies an HTTP request header field to extract from the request and its value is compared with the value specified in the filter property according to the operator specification. If the header field that is identified by the input element is not present in the HTTP request, the condition is treated as not being met. Any of the standard HTTP request header fields can be used as the input element in the filter condition. Refer to the HTTP specification for the list of valid headers.
In addition to the standard HTTP header fields, the following two special input elements can be used in the filter property:
request-url - the comparison value of this input is compared against the URL address used by the client application to make the request
remote-address - the comparison value of this input is compared against the TCP/IP address of the client application that sent the HTTP request

Examples

In the following example, the filter property specifies an HTTP header field From as the input with samluser@xyz.com as the comparison value and == as the operator:
sso_1.sp.filter=From==samluser@xyz.com
In this case, if a client request contains an HTTP header field From with a value of samluser@xyz.com, the SAML TAI selects the SSO service provider partner of this sso_1 filter for processing the client request.
In the following example, the filter property specifies a URL with ivtlanding.jsp as the comparison value and %= as the operator:
sso_2.sp.filter=request-url%=ivtlanding.jsp
In this case, if the URL of the target application invoked by the client contains the string ivtlanding.jsp, the SAML TAI selects the SSO partner of this sso_2 filter for processing the client request.
In the following example, the filter property specifies an application name with DefaultApplication as the comparison value and == as the operator:
sso_3.sp.filter=applicationNames==DefaultApplication
In this case, if the name of the target application invoked by the client application is DefaultApplication, the SAML TAI selects the SSO partner of this sso_3 filter for processing the client request.
The following table lists the different operators used in the filter property:

Operator Condition Example
== This operator specifies an exact match. The input element must be equal to the comparison value. From==jones@my.company.com
%= This operator specifies a partial match. The input element contains the comparison value. user-agent%=IE 6
^= The input element contains one of the comparison values. This is the only operator that can be combined with the | operator. request-url^=urlApp1|urlApp2| urlApp3
!= The input element does not contain the comparison value. request-url!=SPNEGO;request-url!=test105
> The input element is greater than the comparison value. remote-address>192.168.255.130
< The input element is less than the comparison value. remote-address<192.168.255.135

Reference topic

Global properties	Applicable to all SSO partners configured for the SAML TAI.
IdP properties	Applicable to identity providers configured for the SAML TAI. To assign unique property names that identify each identity provider partner, an idp_<id> is embedded in the property name and used to group the properties associated with each SSO IdP partner.
Service provider properties	Applicable to a service provider. Grouped together for each SSO service provider partner under a unique sso_<id>.

Property name	Values	Description
targetUrl	Any URL value.	Default target URL after successful validation of the SAMLResponse when there is no RelayState received from the IdP. Overridden by sso_<id>.sp.targetUrl.
useRelayStateForTarget	true (Default) false	Indicate if the RelayState should be used as the target URL. Overridden by sso_<id>.sp. useRelayStateForTarget.
allowedClockSkew	Any positive number. Default is three minutes.	Allowed clock skew in minutes when validating the SAML token. Overridden by sso_<id>.sp. allowedClockSkew.
enforceTaiCookie	true (Default) false	Indicate if the SAML TAI should check if an LTPA cookie is mapped to a subject created for the SSO partner. Overridden by sso_<id>.sp.enforceTaiCookie.
replayAttackTimeWindow	Any integer value. Default is 30.	Time, in minutes, within which the second request is rejected if two identical SAML tokens are received by the TAI. See also sso_<id>.sp. preventReplayAttack.

Property Name	Values	Description
sso_<id>.idp_<id>.SingleSignOnUrl	Any URL value.	URL of the SSO service of the IdP.
sso_<id>.idp_<id>.allowedIssuerDN	No default	Name of the Issuer who is allowed to sign the SAML token sent by the IdP. If the SAML token is not signed by this issuer, the token is rejected.
sso_<id>.idp_<id>.allowedIssuerName	No default.	Value of the <saml:Issuer> Issuer element in the SAML token. The SAML token received from the IdP is rejected if the Issuer in the token does not match this value.

Property Name	Values	Description
sso_<id>.sp.acsUrl	No default. We can specify one of the following values: URL of the assertion consumer service (ACS): https://host:<sslport>/samlsps/<any URI pattern String> URL of the business application	This is the only required property for each sso_<id>. It specifies the URL of the ACS or business application.
sso_<id>.sp.cookiegroup	No value.	Tag to be added to an ltpa cookie for the configured SAML SSO partner. When a web request is received with an ltpa cookie, the ltpa cookie is valid only if the tag matches this value.
sso_<id>.sp.EntityID	Default is value of sso_<id>.sp.aclUrl.	Used to verify AudienceRestriction in the SAML assertion.
sso_<id>.sp.targetUrl	No default.	URL of the target application. Used when RelayState is not present in the client request.
sso_<id>.sp.useRelayStateForTarget	true (Default) - Use the value of RelayState in the client request as the URL of the target application. false - Use the value of sso_<id>.sp.targetUrl as the URL of the target application.	Whether the RelayState value received in the client request should be used as the URL of the target application or not. If false, the sso_<id>.sp.targetUrl property is used as the URL of the target application.
sso_<id>.sp.login.error.page	Required.and does not have a default value.	Error page, IdP login page, or custom mapping class to which an unauthenticated client request is redirected to.
sso_<id>.sp.acsErrorPage	Defaults to the value for sso_<id>.sp.login.error.page.	Error page to use if the SAML token fails validation or authentication.
sso_<id>.sp.allowedClockSkew	No default.	This property specifies, in minutes, the time added to the token expiration time of the SAML token sent by the IdP.
sso_<id>.sp.trustStore	No default.	Truststore for validating the SAML signature. It specifies the name of a managed keystore.
sso_<id>.sp.trustAnySigner	false (Default) - the signer certificate is verified for trust validation true - any signer certificate is trusted without trust validation	Whether the signer certificate of the SAML token is verified for trust validation. If true, any signer certificate is trusted.
sso_<id>.sp.keyStore	No default.	Keystore containing the private key for decrypting the encrypted SAML assertion.
sso_<id>.sp.keyName	No default.	Key name for decrypting the SAML assertion.
sso_<id>.sp.keyPassword	No default.	Key password for decrypting the SAML assertion.
sso_<id>.sp.keyAlias	No default.	Key alias for decrypting the SAML assertion.
sso_<id>.sp.wantAssertionsSigned	true (Default) - the service provider requires the IdP to sign the SAML assertion false - the SAML assertion is not required to be signed by the IdP	If false, the SAML assertion is not required to be signed and the signature is not validated.
sso_<id>.sp.preserveRequestState	true (Default) - the client state is saved and restored when it is redirected to the IdP login false - the client state is not saved	When the service provider redirects the client request to the IdP login, this property specifies whether the client state needs to be saved and restored after the client request is completed.
sso_<id>.sp.enforceTaiCookie	true (Default) false	This property is used to indicate if the SAML TAI should check if an LTPA cookie is mapped to a subject created for the SSO partner.
sso_<id>.sp.realmName	This can be any string value. Default is SAML Issuer name.	Any SAML attribute. Used in conjunction with realmNameRange. The value of this attribute is used as the subject realm. If this realm does not exist in the list of realms specified by realmNameRange, the realm is rejected.
sso_<id>.sp.realmNameRange	This property has no default value.	List of allowed realm names and is used in conjunction with realmName. See the description of sso_<id>.sp.realmName.
sso_<id>.sp.principalName	This can be any string value. Default Subject NameID.	Any SAML attribute. The value of this attribute is used as the subject principal.
sso_<id>.sp.uniqueId	This can be any string value. Default is Subject NameID.	Any SAML attribute. The value of this attribute is used as the subject uniqueId.
sso_<id>.sp.groupName	No default.	Any SAML attribute. The value of this attribute is used as groups in the subject.
sso_<id>.sp.defaultRealm	IssuerName (Default) - Use the SAML token Issuer as the default realm NameQualifier - Use the SAML token NameQualifier as the default realm	Specifies whether the Issuer or the NameQualifier from the SAML assertion is used as the default realm.
sso_<id>.sp.useRealm	No default.	Realm name and is used to override the default realm. This property also overrides the realmName property.
sso_<id>.sp.idMap	idAssertion (Default) - the user specified in the SAML assertion is not checked in the local registry localRealm - the SAML token user is verified in the local user registry localRealmThenAssertion - if the user is found in the local registry, IDAssertion is used	How the SAML token is mapped to the subject.
sso_<id>.sp.groupMap	localRealm - Map the SAML token groups to groups and parent groups found in the local user registry addGroupsFromLocalRealm - Map the SAML token groups to groups and parent groups in local user registry. The group membership for this user will contains the groups from SAML assertion and the groups found in local user registry.	This property is used with IDAssertion and specifies how the SAML token is mapped to the groups.
sso_<id>.sp.userMapImpl	No default	Name of a custom user mapping module class. Used to map a user ID in the SAML token to another user ID that exists in the local user registry.
sso_<id>.sp.X509PATH	No default	The certificate store used for the intermediary certificates used in validating the SAML signature.
sso_<id>.sp.CRLPATH	No default	Certificate store used for certificate revocation lists (CRLs) used in validating the SAML signature.
sso_<id>.sp.filter	No default	Specify a condition that is checked against the HTTP request, to determine whether or not the HTTP request is selected for a SAML web SSO partner. See the SAML TAI filter property section for more information on this property.
sso_<id>.sp.preventReplayAttack	true (Default) false	Specify whether the SAML TAI should prevent two identical SAML tokens from being sent in client requests. This property is used in conjunction with the global property replayAttackTimeWindow.
sso_<id>.sp.trustedAlias	No default	If specified, only the key specified by this alias is used to validate the signature in the SAML assertion. If the signature in the incoming SAML assertion of the SAMLResponse does not include the KeyInfo element, specify this property to resolve the KeyInfo element.
sso_<id>.sp.charEncoding	No default. An example setting is UTF-8.	Character encoding used to override the setting in the HTTPServletRequest.
sso_<id>.sp.disableDecodeURL	true false (Default)	When true, the original URL for redirect is used, without decoding the URL.

Operator	Condition	Example
==	This operator specifies an exact match. The input element must be equal to the comparison value.	From==jones@my.company.com
%=	This operator specifies a partial match. The input element contains the comparison value.	user-agent%=IE 6
^=	The input element contains one of the comparison values. This is the only operator that can be combined with the \| operator.	request-url^=urlApp1\|urlApp2\| urlApp3
!=	The input element does not contain the comparison value.	request-url!=SPNEGO;request-url!=test105
>	The input element is greater than the comparison value.	remote-address>192.168.255.130
<	The input element is less than the comparison value.	remote-address<192.168.255.135