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). You can define these properties in the custom properties panel for the SAML TAI using the administrative 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 that are associated with each SSO partner. The sso_<id>s are numbered sequentially for each SSO service provider partner.
- Global properties - these properties are applicable to all SSO partners that are configured for the SAML TAI.
- IdP properties - these properties are applicable to identity providers that are 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 that are associated with each SSO IdP partner.
- Service provider properties - these properties are applicable to a service provider and are grouped together for each SSO service provider partner under a unique sso_<id>.
The following table describes the global SAML TAI custom properties:
Property name | Values | Description |
---|---|---|
targetUrl | You can specify any URL value. | This property is overridden by sso_<id>.sp.targetUrl. This is the default target URL after successful validation of the SAMLResponse when there is no RelayState received from the IdP. |
useRelayStateForTarget | You can specify one of the following values:
|
This property is overridden by sso_<id>.sp. useRelayStateForTarget. This is used to indicate if the RelayState should be used as the target URL. |
allowedClockSkew | You can specify any positive number. The default is three minutes. | This property is overridden by sso_<id>.sp. allowedClockSkew. This is used to specify the allowed clock skew in minutes when validating the SAML token. |
enforceTaiCookie | You can specify one of the following values:
|
This property is overridden by sso_<id>.sp. enforceTaiCookie. This is used to indicate if the SAML TAI should check if an LTPA cookie is mapped to a subject created for the SSO partner. |
preventReplayAttackScope | This property does not have a default. You can specify the following value:
|
By default, the SAML TAI uses a distributed cache to store SAML Assertion IDs for preventing replay attack. If you set this property to server, the SAML TAI uses a local cache instead. |
replayAttackTimeWindow | You can specify any integer value. The default value is 30. | This property specifies the 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. |
retryOnceAfterTrustFailure | You can specify one of the following values:
|
Set this property to true to enable the run time to reload the trust store after trust validation has failed. This allows the trust store to be updated with new IdP certificates while the application server is running. |
redirectToIdPonServerSide | You can specify one of the following values:
|
This property is overridden by sso_<id>.sp. redirectToIdPonServerSide. This property is used to indicate that the TAI should redirect to the IdP itself. Set this property to false to do a client-side redirect. Set this property to false if URL fragments are being lost on the redirect; the TAI will then do a client-side redirect. |
The following table describes the IdP SAML TAI custom properties:
Property Name | Values | Description |
---|---|---|
sso_<id>.idp_<id>.SingleSignOnUrl | You can specify any URL value. | This custom property specifies the URL of the SSO service of the IdP. |
sso_<id>.idp_<id>.allowedIssuerDN | This custom property does not have a default value. | This custom property specifies the Subject DN of the certificate who is allowed to sign the SAML token sent by the IdP. If the SAML token is not signed by this certificate, the token is rejected. If this property is specified, the sso_<id>.sp.wantAssertionSigned custom property must be true. Use this property when, instead of IdP's signer certificate, you have the signer certificate's Issuer in the trust store. This will prevent you from allowing all signers with certificates issued by the same Issuer. |
sso_<id>.idp_<id>.allowedIssuerName | This custom property does not have a default value. | This custom property specifies the 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. |
The following table describes the service provider SAML TAI custom properties:
Property Name | Values | Description |
---|---|---|
sso_<id>.sp.acsUrl | This property does not have a default value. You can specify one of the
following values:
|
This is the only required property for each sso_<id>. It
specifies the URL of the ACS or business application. If you need to have multiple, similar entry
points for your SAML workflows, you can specify a URL with a wildcard at the end of the string
instead of a specific URI pattern string for this property. For example:
The value for each sso_<id>.sp.acsUrl property must have a unique URL path. A URL path does not include the protocol and <hostname>:<port> parts of a URL string. For example, https://here.com/samlsps/app/go and https://elsewhere.com/samlsps/app/go have the same URL path, /samlsps/app/go, so only one of them can be configured as an acsUrl entry. |
sso_<id>.sp.cookiegroup | This property does not have a default value. | This property specifies a 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 | By default, this property is set to the value of sso_<id>.sp.aclUrl. | This property is used to verify AudienceRestriction in the SAML assertion. |
sso_<id>.sp.targetUrl | This property does not have a default value. | This property specifies the URL of the target application. It is used when RelayState is not present in the client request. |
sso_<id>.sp.useRelayStateForTarget | You can specify one of the following values:
|
This property specifies whether the RelayState value received in the client request should be used as the URL of the target application or not. If this property is set to false, the sso_<id>.sp.targetUrl property is used as the URL of the target application. |
sso_<id>.sp.login.error.page | This property does not have a default value. | This property specifies the error page, IdP login page, or custom mapping
class to which an unauthenticated client request is redirected to. If a custom mapping class is specified on this custom property, the .jar file containing the custom class must be placed in either the (WAS_HOME)/lib or (WAS_HOME)/lib/ext directory. |
sso_<id>.sp.acsErrorPage | This property does not have a default value. | This property is used to override sso_<id>.sp.login.error. page. |
sso_<id>.sp.allowedClockSkew | This property does not have a default value. | This property specifies, in minutes, the time that is added to the token expiration time of the SAML token sent by the IdP. |
sso_<id>.sp.trustStore | This property does not have a default value. | This property specifies the truststore for validating the SAML signature. It
specifies the name of a managed keystore. Examples:
|
sso_<id>.sp.trustAnySigner | You can specify one of the following values:
|
This property specifies whether the signer certificate of the SAML token is verified for trust validation. If this property is set to true, any signer certificate is trusted. |
sso_<id>.sp.keyStore | This property is required to receive and process EncryptedAssertions and does not have a default value. | This property specifies the name of the managed keystore that contains the
private key for decrypting an encrypted SAML assertion. Examples:
|
sso_<id>.sp.keyName | This property is required to receive and process EncryptedAssertions and does not have a default value. | This property specifies the key name for decrypting the SAML assertion. |
sso_<id>.sp.keyPassword | This property is required to receive and process EncryptedAssertions and does not have a default value. | This property specifies the key password for decrypting the SAML assertion. |
sso_<id>.sp.keyAlias | This property is required to receive and process EncryptedAssertions and does not have a default value. | This property specifies the key alias for decrypting the SAML assertion. |
sso_<id>.sp.wantAssertionsSigned | You can specify one of the following values:
|
If this property is set to false, the SAML assertion is not
required to be signed and the signature is not validated. When the value for this property is true, either sso_<id>.sp.trustAnySigner must be set to true or sso_<id>.sp.trustStore set to a valid managed keystore. |
sso_<id>.sp.preserveRequestState | You can specify one of the following values:
|
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 | You can specify one of the following values:
|
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. By default, this property is set to the SAML Issuer name. | This property specifies any SAML attribute and is 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. | This property specifies a list of allowed realm names and is used in conjunction with realmName. See the description of sso_<id>.sp.realmName. |
sso_<id>.sp.retryOnceAfterTrustFailure | You can specify one of the following values:
|
Set this property to true to enable the run time to reload the trust store after trust validation has failed. This allows the trust store to be updated with new IdP certificates while the application server is running. |
sso_<id>.sp.principalName | This can be any string value. By default, this property is set to the Subject NameID. | This property specifies any SAML attribute. The value of this attribute is used as the subject principal. |
sso_<id>.sp.uniqueId | This can be any string value. By default, this property is set to the Subject NameID. | This property specifies any SAML attribute. The value of this attribute is used as the subject uniqueId. |
sso_<id>.sp.groupName | This property does not have a default value. | This property specifies any SAML attribute. The value of this attribute is used as groups in the subject. |
sso_<id>.sp.defaultRealm | You can specify one of the following values:
|
This custom property specifies whether the Issuer or the NameQualifier from the SAML assertion is used as the default realm. |
sso_<id>.sp.useRealm | This property does not have a default value. | This property specifies a realm name and is used to override the default realm. This property also overrides the realmName property. |
sso_<id>.sp.idMap | You can specify one of the following values:
|
This property specifies how the SAML token is mapped to the subject. |
sso_<id>.sp.groupMap | You can specify one of the following values:
|
This property is used with IDAssertion and specifies how the SAML token is mapped to the groups. |
sso_<id>.sp.userMapImpl | This property does not have a default value. | This property specifies the name of a custom user mapping module class. It is
used to map a user ID in the SAML token to another user ID that exists in the local user
registry. The custom mapping class must implement the com.ibm.wsspi.security.web.saml.UserMapping interface. The .jar file containing the custom class must be placed in either the (WAS_HOME)/lib or (WAS_HOME)/lib/ext directory. If, when a user mapping error occurs, you want to use an error page other than what is set on the sso_<id>.sp.acsErrorPage custom property, use the com.ibm.websphere.security.UserMappingException.setErrorPage method. |
sso_<id>.sp.X509PATH | This property does not have a default value. | This property specifies the certificate store that is used for the intermediary certificates used in validating the SAML signature. |
sso_<id>.sp.CRLPATH | This property does not have a default value. | This property specifies the certificate store that is used for certificate revocation lists (CRLs) used in validating the SAML signature. |
sso_<id>.sp.filter | This property does not have a default value. | This property is used to 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 | You can specify one of the following values:
|
This property is used to 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.preventReplayAttackScope | This property does not have a default. You can specify the following value:
|
By default, the SAML TAI uses a distributed cache to store SAML Assertion IDs for preventing replay attack. If you set this property to server, the SAML TAI uses a local cache instead. |
sso_<id>.sp.trustedAlias | This property does not have a default value. | If this property is 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. |
|
This property does not have a default value. An example setting is UTF-8. | This property specifies the character encoding that is used to override the setting in the HTTPServletRequest. |
|
You can specify one of the following values:
|
When this property is set to true, the original URL for redirect is used, without decoding the URL. |
sso_<id>.sp.redirectToIdPonServerSide | You can specify one of the following values:
|
This property is used to indicate that the TAI should redirect to the IdP itself. Set this property to false if URL fragments are being lost on the redirect; the TAI will then do a client-side redirect. |
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 sp.filter properties do not apply to a SAMLResponse. The request URL in a SAMLResponse is evaluated against the sp.acsURL.
- 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 that is 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.
- request-url - the comparison value of this input is compared against the URL address that is 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
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.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.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.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 6request-url%=company.com/urlApp1 |
^= | 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!=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 |
; | Logical AND Operator | request-url!=test105;From==jones@my.company.com5 |