SAML web single sign-on (SSO) TAI custom properties
The following tables list custom properties for the SAML trust association interceptor (TAI). We can define these properties in the custom properties panel for the SAML TAI using the administrative console. Each SSO service provider (SP) partner uses an sso_id embedded in the property name and used to group the properties associated with each SSO partner. The sso_ids are numbered sequentially for each SSO service provider partner.
Categories
Properties Description Global Applicable to all SSO partners configured for the SAML TAI. Identity provider 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 Applicable to a service provider and are 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 identity provider. Overridden by sso_id.sp.targetUrl. useRelayStateForTarget true (Default)
falseUse RelayState in the client request as the URL of the target application. Overridden by sso_id.sp.useRelayStateForTarget. allowedClockSkew Any positive number. The default is three minutes. Allowed clock skew in minutes when validating the SAML token. Overridden by sso_id.sp.allowedClockSkew. enforceTaiCookie true (Default)
falseIndicates 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. preventReplayAttackScope None SAML TAI uses a distributed cache to store SAML Assertion IDs for preventing replay attack. If we set this property to server, the SAML TAI uses a local cache instead. replayAttackTimeWindow Any integer value. The 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. retryOnceAfterTrustFailure true
falseSet 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 true (Default)
falseIndicates that the TAI should redirect to the IdP itself. Set to false to do a client-side redirect. Set to false if URL fragments are being lost on the redirect; the TAI will then do a client-side redirect. Overridden by sso_id.sp.redirectToIdPonServerSide.
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 value. Subject DN of the certificate allowed to sign the SAML token sent by the IdP. If token is not signed by this certificate, the token is rejected. If specified, the sso_id.sp.wantAssertionSigned custom property must be true. Use this property when, instead of IdP's signer certificate, we 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 No default value. Specify the value of the saml:Issuer Issuer element in the SAML token. The SAML token received from the identity provideris 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 Assertion Consumer Service URL https://hostname:sslport/samlsps/URL_pattern
...or URL of the business application
URL of the ACS or business application. Only required property for each sso_id. To have multiple, similar entry points for our SAML workflows, specify a URL with a wildcard at the end of the string...
- https://server/context_root/ep1/path1/p*
- https://server/context_root/ep1/*
The value must have a unique URL path. A URL path does not include the protocol and hostname:port parts of a URL string. For example, the following have the same URL path, /samlsps/app/go, so only one of them can be configured as an acsUrl entry.
- https://here.com/samlsps/app/go
- https://there.com/samlsps/app/go
sso_id.sp.cookiegroup No default 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 sso_id.sp.aclUrl. Verify AudienceRestriction in the SAML assertion. sso_id.sp.targetUrl No default value. URL of the target application. Used when RelayState is not present in the client request. sso_id.sp.useRelayStateForTarget true (Default)
falseIf true, use the RelayState value received in the client request as the URL of the target application. If false, the sso_id.sp.targetUrl property is used as the URL of the target application. sso_id.sp.login.error.page No default value. 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 No default value. Overrides sso_id.sp.login.error. page. sso_id.sp.allowedClockSkew No default value. 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 No default value. Truststore for validating the SAML signature. Name of a managed keystore. Examples:
- myKeyStoreRef
- name=myKeyStoreRef managementScope=(cell):myCell:(node):myNode
sso_id.sp.trustAnySigner false (Default) - the signer certificate is verified for trust validation
true - any signer certificate is trusted without trust validationSpecifies whether the signer certificate of the SAML token is verified for trust validation. If set to true, any signer certificate is trusted. Use for diagnosis purposes only. Do not use in a production environment. sso_id.sp.keyStore Required to receive and process EncryptedAssertions. No default value. Name of the managed keystore containing the private key for decrypting an encrypted SAML assertion. Examples:
- myKeyStoreRef
- name=myKeyStoreRef managementScope=(cell):myCell:(node):myNode
sso_id.sp.keyName Required to receive and process EncryptedAssertions. No default value. Key name for decrypting the SAML assertion. sso_id.sp.keyPassword Required to receive and process EncryptedAssertions. No default value. Key password for decrypting the SAML assertion. sso_id.sp.keyAlias Required to receive and process EncryptedAssertions. No default value. Key alias for decrypting the SAML assertion. sso_id.sp.wantAssertionsSigned true (Default) - SP provider requires the IdP to sign the SAML assertion
false - SAML assertion not required to be signed by the IdPIf 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 true - (Default). Client state is saved and restored when 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
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. Specifies any SAML attribute and is used in conjunction with realmNameRange. 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.retryOnceAfterTrustFailure - true
falseSet 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. Specifies any SAML attribute. 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. Specifies any SAML attribute. Used as the subject uniqueId. sso_id.sp.groupName No default value. Specifies any SAML attribute. 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
Specify whether the Issuer or the NameQualifier from the SAML assertion is used as the default realm. sso_id.sp.useRealm No default value. Specifies a realm name and is used to override the default realm. This property also overrides the realmName property. sso_id.sp.idMap idAssertion (Default) - User specified in the SAML assertion is not checked in the local registry
localRealm - SAML token user is verified in the local user registry
localRealmThenAssertion - if the user is not found in the local registry, IDAssertion is usedSpecifies 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 value. 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. The custom mapping class must implement the interface... com.ibm.wsspi.security.web.saml.UserMapping
The .jar file containing the custom class must be placed in either the (WAS_HOME)/lib or (WAS_HOME)/lib/ext directory. If a user mapping error occurs, and we want to use an error page other than what is set on the sso_id.sp.acsErrorPage, use the method...
com.ibm.websphere.security.UserMappingException.setErrorPage
sso_id.sp.X509PATH No default value. Certificate store used for the intermediary certificates used in validating the SAML signature. sso_id.sp.CRLPATH No default value. Certificate store used for certificate revocation lists (CRLs) used in validating the SAML signature. sso_id.sp.filter No default value. 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)
falseSpecify 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 None By default, the SAML TAI uses a distributed cache to store SAML Assertion IDs for preventing replay attack. If we set this property to server, the SAML TAI uses a local cache instead. sso_id.sp.trustedAlias No default value. 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 value. 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. sso_id.sp.redirectToIdPonServerSide true (Default)
falseTAI should redirect to the IdP itself. Set 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. 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 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 There is no logical OR operator we can use with filter properties.
Related:
SAML web single sign-on