OpenID Connect Relying Party custom properties
Custom properties for the OpenID Connect Relying Party (RP) Trust Association Interceptor (TAI) help determine the behavior of the OpenID Connect Relying Party (RP). You can define these properties in the Custom Properties window for the OpenID Connect TAI by using the administrative console.
The custom properties are used to determine the behavior of the OpenID Connect RP, and to communicate with an OpenID Connect Provider (OP). You can configure custom properties for multiple OpenID Connect providers.
If you must use a proxy to access the OpenID Connect Provider (OP), the value that you enter for any OP-related URL property must contain the proxy host and port, not the external OP host and port.
In most cases, you can replace the OP host and port with the proxy host and port. The URL that you enter must be visible to both the RP and client (browser or application). For further guidance on how to determine the correct URL to use, contact your proxy administrator.
To assign unique property names that identify each OpenID Connect provider, a
provider_<id>
is embedded in the property name and used to group the
properties that are associated with each OP. The provider_<id>s
are numbered
sequentially for each OP, where <id>
is a number. Properties that are not
prefixed with provider_<id>
are custom properties that apply to all
providers.
- Required properties: If these properties are not defined, the RP cannot initialize. Functionally, if the properties are not defined, it is equivalent to having no RP installed.
- Optional properties: These properties have a default value as documented. They are used to fine-tune the behavior of the RP.
Property name | Values | Description |
---|---|---|
|
You can specify any string value. This property does not have a default value. | Specifies a unique name for each OpenID connect provider that is identified by
the <id> in the provider_<id> prefix. This identifier is
created by you and is used to build the redirect URL that is registered with the OP.For
example:
|
provider_<id>.clientId |
You can specify any string value. This property does not have a default value. | Specifies the ID that is used to identify the OpenID Connect RP instance to the OpenID connect Provider server. It must be unique among all the RP clients that are registered to the provider. |
provider_<id>.clientSecret |
You can specify plaintext or XOR encoded value. This property
does not have a default value. |
Specifies the secret used by the OpenID Connect Provider to secure messages
sent to this RP client in callback requests. It must match the OpenID Connect Provider's secret that
is registered for this client. For
example:
|
|
When useDiscovery is set to true , the
default value for this property is
(issuerIdentifier)/.well-known/openid-configuration . |
Specifies the OpenID Connect Provider's discovery endpoint URL. When this
property is specified, the following properties are obtained from the discovery result:
When the discoveryEndpointUrl property is included in the OIDC TAI configuration, if any of these properties are also included in the configuration, their settings are ignored. A request is sent to the discovery endpoint and the data that is returned is processed when the OIDC TAI is initialized. When the discovery endpoint is not accessible at the time that the TAI is initialized, then the OIDC TAI configuration entries associated with the discovery endpoint are not active and its requests are not intercepted. The OIDC TAI does not refresh the data received from the discovery endpoint. When the OP changes information in its discovery, then the application server must be restarted. When
useDiscovery is set to |
provider_<id>.authorizeEndpointUrl |
You can specify any URL value. This property does not have a default
value.![]() provider_<id>.discoveryEndpointUrl is NOT specified. |
Specifies the endpoint URL for redirecting authorization requests to the
OpenID Connect Provider. For example:
|
provider_<id>.tokenEndpointUrl |
You can specify any URL value. This property does not have a default
value.![]() provider_<id>.discoveryEndpointUrl is NOT specified. |
Specifies the endpoint URL for redirecting token requests to the OpenID
Connect Provider. For example:
|
Property name | Values | Description |
---|---|---|
|
For information about defining this property, see the SAML TAI filter property section in the documentation about SAML single sign-on (SSO) TAI custom properties. | This property is used to specify a condition that is checked against the
request to see whether the TAI protects this request. The format for this property is the same as
for the SAML sso_<id>.sp.filter property.Unless the provider_<id>.grantType parameter is specified, at least one of the provider_<id>.filter or provider_<id>.interceptedPathFilter properties must be included in the OIDC TAI configuration.
|
|
You can specify a comma-separated list of URI patterns. This property does not have a default value. | Specifies a comma-separated list of regular expression patterns that are
compared against the request URI to see whether the TAI will intercept the request. To intercept ALL
requests use "/.*". For example: /abcCompanyApps.*, /snoop Unless the provider_<id>.grantType parameter is specified, at least one of the provider_<id>.filter or provider_<id>.interceptedPathFilter properties must be included in the OIDC TAI configuration. The callback URI from the OP,
/callbackServletContext/identifier, is automatically
intercepted by the TAI. You do not need to account for the callback in your filter. An example of a
callback URL is |
provider_<id>.excludedPathFilter |
You can specify comma-separated list of URI patterns. This property does not have a default value. | This property specifies a comma-separated list of regular expression patterns
that are compared against the request URI to determine whether the request should not be protected
by the TAI. This can be used to provide exceptions to the
interceptedPathFilter .For
example:
|
|
You can specify one of the following values:
|
Set this property to the true value if the access token that
is returned from the OP is a JWT and you want the TAI to validate the JWT. |
|
This property does not have a default value. | Set this property to the value of the session endpoint for the Open ID provider. The value for the end session endpoint of the Open ID provider can then be accessed with an API. If the provider_<id>. discoveryEndpointUrl property is specified, the value for this property is overridden. |
|
By default, this property is set to the value provided for the
provider_<id>.clientId property. |
Specifies the clientId to include in the requests to the introspection endpoint of the OpenId Provider. |
|
By default, this property is set to the value provided for the
provider_<id>.clientSecret property. |
Specifies the clientSecret to include in the requests to the introspection point of the OpenId Provider. |
|
This property does not have a default value. | Specifies the client password to include in the basic authentication scheme of the JWK request. |
|
This property does not have a default value. | Specifies the client identifier to include in the basic authentication scheme of the JWK request. |
|
You can specify one of the following values:
|
By default, if an OIDC session cookie is present on a request when a logout is
performed, the logout uses only the information associated with the OIDC session cookie. If no OIDC
session cookie exists, then the logout uses the access token in the Authorization header of the
request. If this property is set to true, the logout is performed by using information from both the OIDC session cookie and the Authorization header of the request, if they exist. |
|
This property does not have a default value. | The realm name to use if one is not obtained from the token. |
|
You can specify one of the following values:
|
When this property is set to false, the new line characters that exist in POST parameters are not encoded into encoded <br> tags. |
provider_<id>.introspectEndpointUrl |
You can specify any URL value. This property does not have a default value. | Specifies the endpoint URL for calling the OpenID Connect Provider's
introspection endpoint. For
example:
|
callbackServletContext |
You can specify any context root value, but it must match the context root that is configured for the OpenID connect RP callback servlet. By default, this property is set to the value of /oidcclient. | Specifies the context root that is configured for the OpenID Connect RP
callback servlet. The property is used by the TAI to filter callback requests from the OpenID
Connect Provider. Normally, this property must be set to /oidcclient. The value
of this property must match the context root that is configured when deploying the
com_ibm_ws_security_oidc_servlet_war into the local WebSphere®. It must also match the registered callback for the start of
the URIs in the URLs registered for this client to the OpenID Connect Provider. For example:
/oidcclient. |
provider_<id>.signatureAlgorithm |
You can specify one of the following values:
|
Specifies the algorithm that is used to secure messages from the OpenID Connect provider. |
|
You can specify any URL value. This property does not have a default value. |
Specifies the URL of the OP's JSON Web Key (JWK) set document that contains the signing key the RP uses to validate the signature from the OP. This property must be set if the |
|
By default, this property is set to the value of sub . |
This property is set to a claim name used by the vendor's ID Token that
represents a user's unique identifier. For example, you can set userIdentifier =
email if you are using Google's OP. |
|
You can specify one of the following values:
|
If a custom identifier is specified for the user
(userIdentifier ), unique user (uniqueUserIdentifier ), group
(groupIdentifier ), or realm (realmIdentifier ), then the custom
value is used only if the default value does not exist in the token. |
provider_<id>.scope |
By default, this property is set to the value of openid
profile . |
Specifies the scope of the token requested from the OpenID Connect Provider.
This property determines the level of authorization the issued token would have. For example:
openid general . |
provider_<id>.issuerIdentifier |
By default, this property is set to the value that is derived from the
authorizedEndpointUrl . |
Specifies the issuer of the IDToken . If this property is not
set, it is derived from the authorizedEndpointUrl value. For
example:
|
provider_<id>.groupIdentifier |
By default, this property is set to a value of
groupIds . |
Specifies the groups attribute name set by the OpenID Connect Provider in the
IDToken . For example: groupIds . |
provider_<id>.mapIdentityToRegistryUser |
You can specify one of the following values:
|
When this property is set to false, the WebSphere subject is populated with the user and groups from the OpenID Connect Provider's realm. The users and groups do not need to exist in the WebSphere Application Server user registry. When this property is set to true, the OpenID Connect RP maps the OpenID Connect authenticated user to the same user (by shortname) in the WebSphere Application Server user registry. All users must be maintained in the WebSphere Application Server user registry. If OpenID Connect authenticates a user that is not in the local WebSphere Application Server user registry, an error occurs. |
provider_<id>.revokeTokensOnCacheEviction |
You can specify one of the following values:
|
When this property is set to true and the revokeEndpointUrl property is set to a value, when a session is evicted from DynaCache for any reason, the tokens in the session data will be revoked. The access token will only be revoked if revokeAccessToken is set to true. |
provider_<id>.redirectToRPHostAndPort |
This custom property does not have a default value. | This RP registers its redirect URL with the OP as https://<host
name>:<ssl port> /oidcclient/signin_cb , where both the host name and ssl port are
automatically resolved. If there is a proxy in front of the RP, you can override the host name and
port with the attribute redirectToRPHostAndPort , and you can set
redirectToRPHostAndPort to https://<hostname>:<ssl
port> . For example:
|
provider_<id>.allowImplicitClientFlow |
You can specify one of the following values:
|
This property determines how the OpenID Connect RP authenticates BasicAuth tokens. When this property is set to true, the TAI authenticates the Basic Auth token and the LTPA token by using implicit flow. When the property is set to false, the TAI authenticates the Basic Auth token and the LTPA token by using the authorization code flow. |
|
This custom property does not have a default value. |
Specifies the alias of the certificate in the default truststore that might be used to verify
the signature from the OP. On a single server, the default truststore is
This property must be set if the |
jndiCacheName |
When a dynamic cache service is enabled, a
DistributedObjectCache named OIDCRPDistributedCacheMap with
KEY_ENABLE_CACHE_REPLICATION=true and
KEY_REPLICATION_DOMAIN=DynaCacheCluster is used. Only the size of the JNDI cache
can be customized with the sessionCacheSize property. All other attributes of this
DistributedMap 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. Read Using object cache instances for information about 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
sessionCacheSize and sessionCacheCleanupFrequency are ignored.
For example:
Avoid trouble: The size that you specify for your custom JNDI cache must be double the
number of sessions that you want the OpenID Connect RP to store in the cache.
|
sessionCacheSize |
You can specify -1 and any integer value greater than 0. When DynaCache is enabled on the server, the default value is -1. When DynaCache is not enabled on the server, the default value is 10000. | Specifies the number of sessions the OpenID Connect RP can keep in its
cache. When DynaCache is enabled on the server:
When DynaCache is not enabled on the server:
|
sessionCacheCleanupFrequency |
You can specify any integer value. By default, this property is set to the value of 1800. | The value of this property is in seconds, and is the frequency at which the stale value of the session cache is purged. This property is only used when the dynamic cache service is not in use. |
|
Specify an integer between 0 and 43200, inclusive. The default is 120. These values are in minutes. | Specifies the time, in minutes, that a session associated with an ID token can
remain in the session cache. By default, a session is removed from the cache based on at least the
following conditions, in priority order:
|
opServerConnectionTimeout |
Specify any integer value. By default, this property is set to the value of 20000 (20 seconds). | Specifies the time in milliseconds to wait for the OpenID Connect Provider to respond to an introspection request. |
|
You can specify one of the following values:
|
When this property is set to true, the
httpOnly flag is set on the cookie.When this property is set to
true, the |
|
You can specify one of the following values:
|
When this property is set to true, the OpenID Connect
RP only establishes a connection with an OP that supports https communication. If this property is
set to true, but the scheme of the authorizeEndpointUrl ,
tokenEndpoint or introspectEndpointURL is http, then the TAI will
fail to initialize.When this property is set to true, the
|
|
You can specify one of the following values:
|
Specifies that the client_id and
client_secret must be URL encoded before sending them to the IdP. |
|
This custom property has a default value of text/html;
charset=UTF-8 . |
Use this property to change the default value of contentType
text or html that is set on the response. |
provider_<id>.postParameterCookieSize |
You can set this property to any integer value. By default, this property is set to 16384. | Maximum session cookie size that the run time creates. At runtime, the value
must be between the minimum cookie size and maximum cookie size. If the data to be written is larger
than the value for this property, the request is rejected. This property overrides the value set for
maxCookieSize for session cookies. |
maxCookieSize |
You can set this property to any integer value greater than the minimum of 500. By default, this property is set to 16384. | Maximum cookie size that the run time creates. At runtime, if the data to be
written is larger than the value for this property, the request is rejected. This property applies
to and can be overridden by both maxStateCookieSize and
provider_.<id>postParameterCookieSize . |
clusterCaching |
You can specify one of the following values:
|
Set this property to false if you want each cluster
member to maintain its own caches. When this property is set to false and you
are operating in a cluster, session affinity is required for proper operation. When this property is
set to false, the default for useStateCookies changes to
false. |
stateIdTimeoutSeconds |
You can set this property to any integer value greater than the minimum value, which is 60. By default, this property is set to 600. | The time, in seconds, that a login request to the OP is allowed to remain outstanding. |
useStateCookies |
You can specify one of the following values:
|
When this property is true, the run time uses browser cookies to store request data when a request is redirected to the OP. When this property is false, local storage is used. When this property is set to false and you are operating in a cluster, session affinity is required for proper operation. |
useUniqueStateCookies |
You can specify one of the following values:
|
When this property is set to true, instead of using a single OIDCSTATE cookie for all requests, each request uses a new OIDCSTATE cookie. |
|
You can specify one of the following values:
|
During the initial login phase, the OpenId Connect TAI writes a browser
cookie. The value for the cookie is the original request URL. This cookie is deleted when the login
is complete or after the login timeout expires, whichever comes first. The login timeout is
configured on the stateIdTimeoutSeconds property. If you want to maintain this
information in other OIDC objects, set this property to false. If your URL
contains fragments or if the inbound URL is encoded and must remain encoded when it reaches the
protected resource, both this property and the provider_<id>.useJavaScript
property must be set to true. |
maxStateCacheSize |
You can specify -1 and any integer value greater than 25. When DynaCache is enabled on the server, the default value is -1. When DynaCache is not enabled on the server, the default value is 10000. | Maximum number of state objects that can be in the local state cache. The minimum value is 25. Setting the value to 0 turns off the local state cache. Setting the value to -1 makes the OIDC TAI inherit the active DynaCache default cache size. If DynaCache is not enabled on the application server when -1 is specified, this property reverts to its default. |
maxStateCookieSize |
You can set this property to any integer value greater than the minimum of
500 and less than the value for maxCookieSize . By default,
this property is set to the value of maxCookieSize . |
Maximum state cookie size that the run time creates. At runtime, if the data
to be written is larger than the value for this property, the request is rejected. This property
overrides the value set for maxCookieSize for state cookies. |
includeCustomCacheKeyInSubject |
You can specify one of the following values:
|
When this property is set to true, the cache key for
the Subject in the auth cache is set to
(username)(session-cookie-name)(access-token-string). When this property is set to
false, the cache key is defined by base security.
|
|
You can specify one of the following values:
|
Set this property to false if you do not want the
OpenID Connect Relying Party (RP) to include the port number in the redirectUri parameter that is
sent to the OpenID Provider (OP). This property affects only the default redirectUri parameter that
is determined by the RP. If the provider_<id>.redirectToRPHostAndPort
property is set to a value that includes a port number, then the port is included in the request to
the OP. |
provider_<id>.clockSkew |
You can set this property to any integer value. By default, this property is set to 180. | Clock skew, in seconds, used during ID token verification. |
provider_<id>.tokenEndpointAuthMethod |
You can specify one of the following values:
|
When this property is set to basic, a
BasicAuth header is sent when making a request to the token endpoint. |
provider_<id>.jsonWebKeyFile |
This custom property does not have a default value. | The file name of a JSON Web Key file that contains the public keys for signature verification. |
provider_<id>.uniqueUserIdentifier |
By default, this property is set to
uniqueSecurityName . |
This property is set to a claim name used by the vendor's ID Token that represents a user's unique security name. |
provider_<id>.useRealm |
This property does not have a default value. | Specifies the realm name to be used for each request to this provider. This property overrides both the value for the realm name in the IDToken and the value for the provider_<id>.defaultRealmName property. |
provider_<id>.realmIdentifier |
By default, this property is set to realmName |
Specifies the realm attribute name set by the OpenID Connect Provider in the IDToken. |
provider_<id>.refreshBeforeAccessTokenExpiresTime |
You can set this property to any integer value. By default, this property is set to 0. | You can use this property to adjust the time when the access token expires. Set this property to the number of seconds before the time set in the token you want the token to expire. |
provider_<id>.refreshExpiredAccessToken |
You can specify one of the following values:
|
By default, when an access token expires, the runtime attempts to refresh it. Set this property to false if you do not want to refresh access tokens. |
|
You can specify one of the following values:
|
By default, when a user logs out, a revocation request is sent only with the
refresh token. The OpenID Connect provider revokes both the refresh token and its associated access
token with this request. When this property is set to true, a separate revocation request is made for the access token. |
|
You can specify any URL value. This property does not have a default value. | Specifies the endpoint URL for calling the OpenID Connect Provider token revocation endpoint. |
provider_<id>.createSession |
You can specify one of the following values:
|
Set this property to true if you want the runtime to
create a new HTTP session for each client request. This property is required when you run in a cluster environment and you need the JSESSIONID cookie to maintain session affinity. |
|
You can specify one of the following values:
|
This property defines the responseType parameter that is used
when making the authentication request to the OpenID provider. When code is
specified, the OpenID connect code login flow is used. When this property is set to any of the other
values, the implicit login flow is used. If this property is set to anything other than code, the following conditions apply:
|
|
When the responseType property is set to code, this parameter defaults to false. If the responseType property is set to anything other than code, this property is set to true, and cannot be altered. |
When this property is set to true, a nonce parameter is sent to the OpenID Connect provider on the authentication request. |
|
If this property is not specified, the default truststore is used. On a single
server, the default truststore is NodeDefaultTrustStore. Otherwise, it is
CellDefaultTrustStore. This property has, for example, the following values:
|
Specifies the truststore from which to obtain the certificate that is specified on the provider_<id>.signVerifyAlias property. |
|
You can specify any URL value. This property does not have a default value. | Specifies the URL for the UserInfo endpoint on the OpenID Connect Provider.
The login process does not fail if an error occurs when making a call to the UserInfo endpoint. The
response received from the UserInfo endpoint is be placed on the WebSphere Subject with the [user_info] key. If the call to the endpoint is successful, the value for the [user_info] entry on the Subject is the JSON string. Otherwise, the value contains information about the error, such as the response code and error message from the OP or the exception text. The UserInfo endpoint is invoked each time the OIDC RP receives an access token from the OP. |
|
You can specify one of the following values:
|
This property controls the validation of claims against the
provider_<id>.issuerIdentifier property value in the OIDC configuration.When JWT authentication is performed:
When JWT authentication is not performed:
|
|
You can specify one of the following values:
|
This property controls processing if a JWT is found in the request authorization header. |
|
You can specify one of the following values:
|
Set this property to false if you want the runtime to reject any request that
uses a JWT containing a jti claim that was already used in another JWT on a
previous request. |
|
You can specify any comma-separated audience string or
ALL_AUDIENCES . |
This property specifies a comma-separated list of trusted audiences to be
verified against the aud claim in the JWT. If ALL_AUDIENCES is
specified, then all are trusted. An aud claim must exist in the JWT if this
property is set to a value. |
|
You can specify one of the following values:
The default value varies based on the following situations:
|
Set this property to true if you want the runtime to set an
LTPA Cookie on the response after successful authentication with the inbound JWT is complete.
Before Version 8.5.5.19 this property is supported only when the
|
|
Name of an HTTP header The name, Authentication, is the default name value. |
The name of the HTTP header which carries the JWT token in the inbound request for JWT authentication (The name, Authentication, is the default name value.) |
|
This property does not have a default value. | This property specifies the URL to which the Relying Party redirects when a login error is received from an OpenID Connect Provider. |
|
You can specify one of the following values:
|
When this property is set to true, the Relying Party forwards the error, error description, and error URI parameters that were received from the OpenID Connect Provider to the error URL. |
|
This custom property does not have a default value. | If you want a Content-Security-Policy HTTP header to be included in the
initial login request that is sent to your OP, set the
provider_<id>.contentSecurityPolicy property to the value that you want to use
for the Content-Security-Policy HTTP header. If your Content-Security-Policy value requires a
nonce , you can use the %NONCE% keyword to indicate where the
nonce should be placed in the text as shown in the following
example:
|
|
This custom property does not have a default value. | Set this property to client_credentials to use the provider
entry to obtain an access token from the OpenID Provider token endpoint by using the
client_credentials grant type. You can obtain the access token by using the
OidcClientHelper.getClientCredentialsGrantAccessToken() API. When you specify the
grantType property on a provider entry, that provider entry cannot be used for the
OpenID Connect login flow. |
|
If the useDiscovery property is set to true, the default
value for this property is (issuerIdentifier)/.well-known/openid-configuration . If
the useDiscovery property is set to false, the value for this property is
ignored. |
This property specifies the endpoint URL that calls the OpenID Connect Provider discovery
endpoint. When this property is specified, the following properties are obtained from the discovery result:
If any of these properties are also included in the same OIDC TAI configuration as the
If this property is specified, a request is sent to the discovery endpoint and the data that is returned is processed when the OIDC TAI is initialized. If the discovery endpoint is not accessible when the TAI is initialized, then the TAI configuration entries that are associated with the discovery endpoint are not active and its requests are not intercepted. The OIDC TAI does not refresh the data that is received from the discovery endpoint. If the OP changes information in its discovery, then the application server must be restarted. |
|
This property defaults to true if a value is specified
for the discoveryEndpointUrl property, otherwise, it defaults to
false. |
If this property is set to true, and no value is specified for the
discoveryEndpointUrl property, the default value for the
discoveryEndpointUrl property is used. If this property is set to false, the value
for the discoveryEndpointUrl property is ignored. |
|
The property can be set to the true value or the
false value. The default value is true. |
If this property is set to the true value and the
userinfoEndpointUrl property is set, you can get the user information during login. You can set the
userinfoEndpointUrl property from the OpenId Connect property or from discovery. If this property is
set to the false value, the setting for the userinfoEndpointUrl property is
ignored. You cannot get user information during login. However, no matter what the setting is for
this property, you can get user information from the server through an API. When you call the
OidcClientHelper.getUserInfoFromServer() method from your application, the user information is
gotten from the userinfoEndpointUrl property on the server. |
|
The default value is true. | Set this property to false if you do not want to use
JavaScript when you redirect to the OP for the initial authentication request. When you do not use
JavaScript, any URI fragments that are present on the original inbound request are lost. To preserve
URI fragments, in addition to setting this property to true , you must also set the
useUrlCookies property to true . |
Property name | Comments |
---|---|
Must be set to required | |
Both of these properties are required. | |
One of these properties must be configured to obtain the JWT signer certificate. | |
One of these properties must be configured to enable the OIDC TAI to intercept requests. | |
These properties are for use only with JWT authentication. They are optional, but you might want to use them in your configuration. | |
The name of the HTTP header which carries the JWT token in the inbound request for JWT authentication |