OpenID Relying Party custom properties

The following tables list the custom properties for the OpenID Relying Party (RP) Trust Association Interceptor (TAI). You 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.
Table 1. Required custom properties for the OpenID Relying Party
Property name Values Description
providerIdentifier You can specify any URL value. This property does not have a default value Specifies a URL that has the OpenID Provider details.
effectiveUriList You can specify a comma-separated list of URI patterns here. This property does not have a default value Specifies a comma-separated list of URIs (it uses regular expressions) that are intercepted by the RP. For example, /oidapp.*, /snoop, /dash/dashboard.
axRequiredAttribute You 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.
Table 2. Optional custom properties for the OpenID Relying Party
Property name Values Description
mapAliasAsPrincipal You 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. Specifies a 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 You can specify any URL value. This property does not have a default value. Specifies a comma-separated list of URIs(uses regex) that should not be intercepted by the TAI. For example: "/oidapp.*, /dash.*
axOptionalAttribute You can specify any string value. This property does not have a default value. Specifies the 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 You can specify any integer value. The default value is 1. Specifies the number of values that the OpenID RP TAI requests for all required and optional attributes from the OpenID Provider. If this property is 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 You can specify comma-separated list of URI patterns here. This property does not have a default value Specifies a 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 You can specify one of the following values:
  • 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 You can specify one of the following values:
  • 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 You can specify any string value that represents character encoding. The default value is UTF-8. Determines the character encoding to use if the TAI receives a request that does not contain the character encoding set.
allowStateless You can specify one of the following values:
  • 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 You can specify one of the following values:
  • 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 You can specify any string value. The default value is checkid_setup. Review OpenID Authentication 2.0 for more information about this property. Another value that it can use is checkid_immediate.
maxAssociationAttempts You can specify any integer value. The default value is 4. Specifies the number of times the TAI attempts to establish association with the OpenID provider server before it stops.
nonceValidTime You can specify any integer number. The default value is 300, This value is in seconds. This is the maximum time the TAI expects a response from the OpenID provider. The nonce value that is sent in the request and received in the response expires in this given time.
sharedKeyEncryptionEnabled You can specify one of the following values:
  • true (default)
  • false
 Specifying this value as true sets the OpenID RP and OpenID provider to use a shared HMAC key for signing.
hashAlgorithm You can specify one of the following values:
  • SHA256 (default)
  • SHA1
 The OpenID RP assumes this is the algorithm used to sign the response from the OpenID provider.

httpsRequired

 You can specify one of the following values:
  • true (default)
  • false
 When this property is set to 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 this property is 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 You can specify any integer value. The default value is 60. This value is in seconds. Specifies the timeout value that is used by the OpenID RP during the discovery phase, while also establishing connection with the OpenID provider.
socketTimeout You can specify any integer value. The default value is 60. This value is in seconds. Specifies the timeout value that is used by the OpenID RP during the discovery phase, while also communicating with the OpenID provider.
HostNameVerificationEnabled You can specify one of the following values:
  • 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 You can specify any integer value. The default value is 2. The number of attempts RP makes to establish connection with the OpenID provider.
realmName You can specify any string value. The default value is OpenIDDefaultRealm. The realm name that is 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 You can specify any integer value. The default value is 10000. Specifies the 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 You 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 If you want to use an object cache instance with properties that are different from the default, use this property to specify a custom object cache instance that is 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 You can specify any string value. This property does not have a default value This property is 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 You can specify any string value. This property does not have a default value. This property is 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 You can specify one of the following values:
  • true (default)
  • false
 The value of this property determines whether a custom cache key is included in the subject created by the TAI.

httpOnly

 You can specify one of the following values:
  • true (default)
  • false
 When this property is set to true, the httpOnly flag will be set on the cookie.