OpenID Relying Party custom properties

OpenID Relying Party custom properties

The following tables list the custom properties for the OpenID Relying Party (RP) Trust Association Interceptor (TAI). We can define these properties in the Custom Properties panel for the OpenID TAI using the administrative console.

The custom properties are used to determine the behavior of the OpenID RP, and to communicate with an OpenID Provider (OP).

The properties are grouped into two categories:

Required OpenID Relying Party custom properties: The RP does not initialize if these properties are not defined.
Optional OpenID Relying Party custom properties: These properties are defaulted to some value as documented. They are used to fine-tune the behavior of the RP.

Property name Values Description
providerIdentifier We can specify any URL value. This property does not have a default value Specifies a URL that has the OpenID Provider details.
effectiveUriList We can specify a comma-separated list of URI patterns here. This property does not have a default value Comma-separated list of URIs (it uses regular expressions) intercepted by the RP. For example, /oidapp.*, /snoop, /dash/dashboard.
axRequiredAttribute We can specify any string value. This property does not have a default value Specifies an attribute that is requested by the relying party from the OpenID provider. It is in the format "alias, uriType".
For example: email, http://axschema.org/contact/email.

Multiple attributes can be provided to the TAI by adding property names that begin with the axRequiredAttribute, and each ending with a unique suffix, in the format "axRequiredAttributesuffix". For example: axRequiredAttribute1: email, http://axschema.org/contact/email, or axRequiredAttribute2:dn,http://www.ibm.com/axschema/bluepages/dn.

Property name Values Description
mapAliasAsPrincipal We can specify a comma-separated list of string values. This property does not have a default value. If the property is not specified, the OpenID claimed identifier is used for the identity. Comma-separated list of the attribute aliases in the OpenID Provider response to use as the principal name when creating the JAAS subject. The first entry that matches an alias in the response will be used. For instance, if this property is set toemail, guid, dn, given the following attribute aliases in the response, someone@ibm.com will be used as the principal name. For example:

openid.ax.type.dn=uid=someone@ibm.com,o=ibm.com
openid.ax.type.email=someone@ibm.com
.
excludedUriList We can specify any URL value. This property does not have a default value. Comma-separated list of URIs(uses regex) that should not be intercepted by the TAI. For example: "/oidapp.*, /dash.*
axOptionalAttribute We can specify any string value. This property does not have a default value. Attribute that is requested by the relying party from the OpenID provider. It is in the format - "alias, uriType". For example: email, http://axschema.org/contact/email. Multiple attributes can be provided to the TAI by adding property names that begin with the axOptionalAttribute and each ending with a unique suffix, in the format "axOptionalAttributesuffix" For example: axRequiredAttribute1: email, http://axschema.org/contact/email, or axRequiredAttribute2:dn,http://www.ibm.com/axschema/bluepages/dn.
axAttributeCount We can specify any integer value. The default is 1. Number of values that the OpenID RP TAI requests for all required and optional attributes from the OpenID Provider. If set to 0, the TAI requests all values available for attributes. For example, if the OpenID Provider has two values for the first name, set axAttributeCount to 2 to get both values.
basicAuthUriList We can specify comma-separated list of URI patterns here. This property does not have a default value Comma-separated list of URIs (uses regex) for which the TAI should authenticate using HTTP Authorization header of type Basic (Basic Auth token). These URIs should be within the set of URIs specified in "effectiveUriList". "effectiveUriList" is evaluated first to determine if the TAI should handle the request. "basicAuthUriList" is evaluated next.
tryOpenIDIfBasicAuthFails Specify one of the following:

true (default)
false

This property is valid for a URI if that URI is in the "basicAuthUriList" set. If the authentication using HTTP Authorization header of type Basic (Basic Auth token) fails, the TAI attempts to authenticate the user using OpenID (it redirects the request to the OpenID provider for authentication)
mapIdentityToRegistryUser Specify one of the following:

true
false (default)

If this property is set to false, the IBM IdP users need not be in the local repository for authentication to work. This is the default behavior. If the property is set to true, the IBM IdP users should also be in the local repository before authentication can occur.
characterEncoding We can specify any string value that represents character encoding. The default is UTF-8. Determines the character encoding to use if the TAI receives a request that does not contain the character encoding set.
allowStateless Specify one of the following:

true
false (default)

A flag that indicates to the TAI if it can fallback to stateless mode of authenticating with the OpenID provider server if an association cannot be established.
useClientIdentity Specify one of the following:

true
false (default)

A flag that indicates to the TAI if it can use the client identity as a principal if it might not chose any alias as the principal.
authenticationMode We can specify any string value. The default is checkid_setup. Review OpenID Authentication 2.0 for more information about this property. Another value that it can use is checkid_immediate.
maxAssociationAttempts We can specify any integer value. The default is 4. Number of times the TAI attempts to establish association with the OpenID provider server before it stops.
nonceValidTime We can specify any integer number. The default is 300, This value is in seconds. This is the maximum time the TAI expects a response from the OpenID provider. The nonce value sent in the request and received in the response expires in this given time.
sharedKeyEncryptionEnabled Specify one of the following:

true (default)
false

Specify this value as true sets the OpenID RP and OpenID provider to use a shared HMAC key for signing.
hashAlgorithm Specify one of the following:

SHA256 (default)
SHA1

The OpenID RP assumes this is the algorithm used to sign the response from the OpenID provider.
httpsRequired
Specify one of the following:

true (default)
false

When true, the OpenID Connect RP will only establish a connection with an OP that supports https communication. If this property is set to true, but the scheme of the authorizeEndpoint, tokenEndpoint or introspectEndpoint is http, then the TAI will fail to initialize.
If set to true, the RP will not attempt to process any requests that do not use the https scheme and the RP will not accept user authentication through the OP if the OP endpoint is http.

connectTimeout We can specify any integer value. The default is 60. This value is in seconds. Timeout value used by the OpenID RP during the discovery phase, while also establishing connection with the OpenID provider.
socketTimeout We can specify any integer value. The default is 60. This value is in seconds. Timeout value used by the OpenID RP during the discovery phase, while also communicating with the OpenID provider.
HostNameVerificationEnabled Specify one of the following:

true (default)
false

Specifies whether the OpenID RP can also validate the host name in the certificate received by it while it establishes an SSL connection with the OpenID Provider.
maxDiscoveryRetry We can specify any integer value. The default is 2. The number of attempts RP makes to establish connection with the OpenID provider.
realmName We can specify any string value. The default is OpenIDDefaultRealm. The realm name used by the RP while the JAAS Subject is created, using the ID received from the OpenID provider. The realmName used (either OpenIDDefaultRealm or a custom value) must be configured as a trusted realm.
maxDiscoveryCacheSize We can specify any integer value. The default is 10000. Maximum size of the internal cache the OpenID RP uses. All subsequent requests to the RP are rejected with the HTTP response code 503 (service unavailable) once the cache size limit is reached.
cacheCleanupFrequency We can specify any integer value. The defaults value is 3600. This value is in seconds, and is the frequency at which the stale objects in the cache are purged.
jndiCacheName When dynamic cache service is enabled, a DistributedObjectCache named OIDCRPDistributedCacheMap with KEY_ENABLE_CACHE_REPLICATION=true and KEY_REPLICATION_DOMAIN=DynaCacheCluster is used. The attributes of this cache cannot be changed To use an object cache instance with properties that are different from the default, use this property to specify a custom object cache instance managed by the dynamic cache service. Refer to the Using object cache instances topic for more information on how to set up a custom object cache instance. The dynamic cache service must be enabled to use an object cache instance or DistributedObjectCache. When the dynamic cache service is not in use, a server-based cache is used. When the dynamic cache service is in use, the values for maxDiscoveryCacheSize and CacheCleanupFrequency are ignored.
realmIdentifier We can specify any string value. This property does not have a default value Set to the alias of one of the attributes that are returned by the OpenID provider server. The value of this attribute is the realmName. If multiple values are returned by the OpenID provider for this alias, any of the values can get selected.
groupIdentifier We can specify any string value. This property does not have a default value. Set to the alias of one of the attributes that are returned by the OpenID provider server. The value of this attribute is the group to which the authenticated user belongs. If multiple values are returned by the OpenID provider for this alias, all of the values are selected.
includeCustomCacheKeyInSubject Specify one of the following:

true (default)
false

The value of this property determines whether a custom cache key is included in the subject created by the TAI.
httpOnly
Specify one of the following:

true (default)
false

When true, the httpOnly flag will be set on the cookie.

Related:

OpenID authentication overview
Configure an OpenID Connect Relying Party
Use object cache instances

Property name	Values	Description
mapAliasAsPrincipal	We can specify a comma-separated list of string values. This property does not have a default value. If the property is not specified, the OpenID claimed identifier is used for the identity.	Comma-separated list of the attribute aliases in the OpenID Provider response to use as the principal name when creating the JAAS subject. The first entry that matches an alias in the response will be used. For instance, if this property is set toemail, guid, dn, given the following attribute aliases in the response, someone@ibm.com will be used as the principal name. For example: openid.ax.type.dn=uid=someone@ibm.com,o=ibm.com openid.ax.type.email=someone@ibm.com .
excludedUriList	We can specify any URL value. This property does not have a default value.	Comma-separated list of URIs(uses regex) that should not be intercepted by the TAI. For example: "/oidapp., /dash.
axOptionalAttribute	We can specify any string value. This property does not have a default value.	Attribute that is requested by the relying party from the OpenID provider. It is in the format - "alias, uriType". For example: email, http://axschema.org/contact/email. Multiple attributes can be provided to the TAI by adding property names that begin with the axOptionalAttribute and each ending with a unique suffix, in the format "axOptionalAttributesuffix" For example: axRequiredAttribute1: email, http://axschema.org/contact/email, or axRequiredAttribute2:dn,http://www.ibm.com/axschema/bluepages/dn.
axAttributeCount	We can specify any integer value. The default is 1.	Number of values that the OpenID RP TAI requests for all required and optional attributes from the OpenID Provider. If set to 0, the TAI requests all values available for attributes. For example, if the OpenID Provider has two values for the first name, set axAttributeCount to 2 to get both values.
basicAuthUriList	We can specify comma-separated list of URI patterns here. This property does not have a default value	Comma-separated list of URIs (uses regex) for which the TAI should authenticate using HTTP Authorization header of type Basic (Basic Auth token). These URIs should be within the set of URIs specified in "effectiveUriList". "effectiveUriList" is evaluated first to determine if the TAI should handle the request. "basicAuthUriList" is evaluated next.
tryOpenIDIfBasicAuthFails	Specify one of the following: true (default) false	This property is valid for a URI if that URI is in the "basicAuthUriList" set. If the authentication using HTTP Authorization header of type Basic (Basic Auth token) fails, the TAI attempts to authenticate the user using OpenID (it redirects the request to the OpenID provider for authentication)
mapIdentityToRegistryUser	Specify one of the following: true false (default)	If this property is set to false, the IBM IdP users need not be in the local repository for authentication to work. This is the default behavior. If the property is set to true, the IBM IdP users should also be in the local repository before authentication can occur.
characterEncoding	We can specify any string value that represents character encoding. The default is UTF-8.	Determines the character encoding to use if the TAI receives a request that does not contain the character encoding set.
allowStateless	Specify one of the following: true false (default)	A flag that indicates to the TAI if it can fallback to stateless mode of authenticating with the OpenID provider server if an association cannot be established.
useClientIdentity	Specify one of the following: true false (default)	A flag that indicates to the TAI if it can use the client identity as a principal if it might not chose any alias as the principal.
authenticationMode	We can specify any string value. The default is checkid_setup.	Review OpenID Authentication 2.0 for more information about this property. Another value that it can use is checkid_immediate.
maxAssociationAttempts	We can specify any integer value. The default is 4.	Number of times the TAI attempts to establish association with the OpenID provider server before it stops.
nonceValidTime	We can specify any integer number. The default is 300,	This value is in seconds. This is the maximum time the TAI expects a response from the OpenID provider. The nonce value sent in the request and received in the response expires in this given time.
sharedKeyEncryptionEnabled	Specify one of the following: true (default) false	Specify this value as true sets the OpenID RP and OpenID provider to use a shared HMAC key for signing.
hashAlgorithm	Specify one of the following: SHA256 (default) SHA1	The OpenID RP assumes this is the algorithm used to sign the response from the OpenID provider.
httpsRequired	Specify one of the following: true (default) false	When true, the OpenID Connect RP will only establish a connection with an OP that supports https communication. If this property is set to true, but the scheme of the authorizeEndpoint, tokenEndpoint or introspectEndpoint is http, then the TAI will fail to initialize. If set to true, the RP will not attempt to process any requests that do not use the https scheme and the RP will not accept user authentication through the OP if the OP endpoint is http.
connectTimeout	We can specify any integer value. The default is 60.	This value is in seconds. Timeout value used by the OpenID RP during the discovery phase, while also establishing connection with the OpenID provider.
socketTimeout	We can specify any integer value. The default is 60.	This value is in seconds. Timeout value used by the OpenID RP during the discovery phase, while also communicating with the OpenID provider.
HostNameVerificationEnabled	Specify one of the following: true (default) false	Specifies whether the OpenID RP can also validate the host name in the certificate received by it while it establishes an SSL connection with the OpenID Provider.
maxDiscoveryRetry	We can specify any integer value. The default is 2.	The number of attempts RP makes to establish connection with the OpenID provider.
realmName	We can specify any string value. The default is OpenIDDefaultRealm.	The realm name used by the RP while the JAAS Subject is created, using the ID received from the OpenID provider. The realmName used (either OpenIDDefaultRealm or a custom value) must be configured as a trusted realm.
maxDiscoveryCacheSize	We can specify any integer value. The default is 10000.	Maximum size of the internal cache the OpenID RP uses. All subsequent requests to the RP are rejected with the HTTP response code 503 (service unavailable) once the cache size limit is reached.
cacheCleanupFrequency	We can specify any integer value. The defaults value is 3600.	This value is in seconds, and is the frequency at which the stale objects in the cache are purged.
jndiCacheName	When dynamic cache service is enabled, a DistributedObjectCache named OIDCRPDistributedCacheMap with KEY_ENABLE_CACHE_REPLICATION=true and KEY_REPLICATION_DOMAIN=DynaCacheCluster is used. The attributes of this cache cannot be changed	To use an object cache instance with properties that are different from the default, use this property to specify a custom object cache instance managed by the dynamic cache service. Refer to the Using object cache instances topic for more information on how to set up a custom object cache instance. The dynamic cache service must be enabled to use an object cache instance or DistributedObjectCache. When the dynamic cache service is not in use, a server-based cache is used. When the dynamic cache service is in use, the values for maxDiscoveryCacheSize and CacheCleanupFrequency are ignored.
realmIdentifier	We can specify any string value. This property does not have a default value	Set to the alias of one of the attributes that are returned by the OpenID provider server. The value of this attribute is the realmName. If multiple values are returned by the OpenID provider for this alias, any of the values can get selected.
groupIdentifier	We can specify any string value. This property does not have a default value.	Set to the alias of one of the attributes that are returned by the OpenID provider server. The value of this attribute is the group to which the authenticated user belongs. If multiple values are returned by the OpenID provider for this alias, all of the values are selected.
includeCustomCacheKeyInSubject	Specify one of the following: true (default) false	The value of this property determines whether a custom cache key is included in the subject created by the TAI.
httpOnly	Specify one of the following: true (default) false	When true, the httpOnly flag will be set on the cookie.