This document contains troubleshooting information for OpenID Connect (OIDC) Trust Association Interceptor (TAI) problems in the WebSphere® Application Server. This can help address common issues with this component before calling IBM support and save you time.
Resolving The Problem
This topic contains the custom properties that are available for use in the latest version of the OpenID Connect TAI. To find the latest OpenID Connect run time, see the technote Obtaining WebSphere OpenID Connect (OIDC) latest version, or click the 'Get the Latest OIDC TAI' tab above.
The OpenID Connect TAI custom properties are documented in the IBM Knowledge Center, for example: WebSphere OpenID Connect Relying Party custom properties for v9.0.5. These custom properties pages are updated when fix packs are published. Since the OpenID Connect TAI is published more frequently than WebSphere Application Server fix packs, the custom property pages tend to become out of date. This page will remain in sync with the latest version of the OpenID Connect TAI that is published as an interim fix.
- How to display properties from command line
In case you aren't running the latest OIDC runtime, you can emit the custom properties that are supported by the OIDC runtime that you have installed by running the following commands:
java -cp ./com.ibm.ws.security.oidc.client.jar com.ibm.ws.security.oidc.util.Usage
- How to set the provider_<id>.filter property
For additional information on how to set the provider_<id>.filter property, see the Examples section at the bottom of the SAML web single sign-on (SSO) trust association interceptor (TAI) custom properties topic in the IBM Knowledge Center.
- Avoid Trouble when using an outbound proxy
Avoid Trouble: When you're using an outbound proxy, note that the OpenId Connect RP does not provide a means to route requests through a proxy host automatically:
- When 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 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 the client (browser or application).
- For further guidance on how to determine the correct URL to use, contact your proxy administrator.
|provider_<id>.identifier||Specifies a unique name for each OpenID connect provider identified by the <id> in the provider_<id> prefix. This identifier is used to build the redirect URL that is registered with the OP. For example, provider_<id>.identifier=abc would yield the redirect URL
|provider_<id>.clientId||Specifies the id used to identify the OpenID Connect RP instance to the OpenID connect Provider server. It must be unique among all the RP clients registered to the provider.|
|provider_<id>.clientSecret||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.|
|Either discoveryEndpointUrl or both authorizeEndpointUrl and tokenEndpointUrl are required.|
|provider_<id>.discoveryEndpointUrl||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 will be obtained from the discovery result:
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 will not be active and its requests will not be 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 true, the default value for this property is (issuerIdentifier)/.well-known/openid-configuration. When the useDiscovery property is set to false, the value for this property will be ignored.
|provider_<id>.authorizeEndpointUrl||Specifies the endpoint URL for redirecting authorization requests to the OpenID Connect Provider.
If an acr_values parameter is present in the value of this property, the TAI verifies that the IDToken contains an 'acr' claim when an IDToken is returned from the OP. The TAI also verifies that the value of the claim matches the value of the acr_values parameter.
|provider_<id>.tokenEndpointUrl||Specifies the endpoint URL for redirecting token requests to the OpenID Connect Provider.|
|provider_<id>.filter||Specifies a condition for the TAI to protect a request. The format for this property is the same as for the SAML sso_<id>.sp.filter property.|
|provider_<id>.interceptedPathFilter||A comma-separated list of URI patterns.||Specifies a comma-separated list of regular expression URI patterns for the TAI to protect a request. To intercept ALL requests use /.*. For example: /abcCompanyApps.*, /snoop|
|provider_<id>.excludedPathFilter||A comma-separated list of URI patterns.||Specifies a comma-separated list of regular expression URI patterns for the TAI to not protect a request. This can be used to provide exceptions to the interceptedPathFilter.|
|provider_<id>.callbackServletContext||default: /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.|
|provider_<id>.redirectToRPHostAndPort||This RP registers its redirect URL with the OP as https://<hostname>:<ssl port> /oidcclient/signin_cb, where both the hostname and ssl port are automatically resolved. When there is a proxy in front of the RP, you can override the hostname and port with the attribute redirectToRPHostAndPort, and you can set redirectToRPHostAndPort to https://<hostname>:<ssl port>.|
|provider_<id>.includePortInDefaultRedirectUrl||default: true||Set this property to false when you do not want the RP to include the port number in the redirectUri that is sent to the OP. This property only affects the default redirect Uri that is determined by the RP. When the redirectToRPHostAndPort property is set to a value that includes a port number, the port will be included in the request to the OP.|
|provider_<id>.useDiscovery||This property defaults to true when a value is specified for the discoveryEndpointUrl property, otherwise, it defaults to false.||When this property is set to true, but a value is not specified for the discoveryEndpointUrl property, the default value for the discoveryEndpointUrl property will be used. When this property is set to false, the value for the discoveryEndpointUrl property will be ignored.|
|provider_<id>.introspectEndpointUrl||Specifies the endpoint URL for calling the OpenID Connect Provider's introspection endpoint.|
|provider_<id>.userinfoEndpointUrl||Specifies the URL for the UserInfo endpoint on the OpenID Connect Provider.
The login process will not fail when an error occurs while making a call to the UserInfo endpoint. The response received from the UserInfo endpoint will be placed on the WebSphere Subject with the [user_info] key.
When the call to the endpoint was successful, the value will be the JSON string. Otherwise, the value placed on the Subject will contain 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.
|provider_<id>.userinfoEndpointEnabled||default: true||Set this property to false when you want to ignore the setting for the userinfoEndpointUrl property. This applies when the endpoint was obtained either from a TAI property or discovery. When a userinfoEndpointUrl is available and the userinfoEndpointEnabled property is set to false, you can still use the OidcClientHelper.getUserInfoFromServer() method to obtain the userinfo from the server in an application.|
|provider_<id>.revokeEndpointUrl||Specifies the endpoint URL for calling the OpenID Connect Provider's token revocation endpoint.|
|provider_<id>.revokeAccessToken||default: false||By default, when a log out is performed, a revocation request is only made for the refresh token. The OP may revoke 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.|
When this property is set to true and the provider_<id>.revokeEndpointUrl property is set to a value, when a session is evicted from the cache for any reason, the tokens in the session will be revoked.
Set this property to the value for the OPs end session endpoint so that it can be accessed with an API. The value for this property is overridden when the discoveryEndpointUrl property is specified.
|provider_<id>.httpsRequired||default: true||When this property is set to true, the OpenID Connect RP will only establish a connection with an OP that supports https communication. When this property is set to true, but the scheme of the authorizeEndpointUrl, tokenEndpoint or introspectEndpoint is http, then the TAI will fail to initialize.|
|provider_<id>.httpOnly||default: true||When this property is set to true, the httpOnly flag is set on the cookie.|
|provider_<id>.createSession||default: false||Set this property to true when you want the runtime to create a new HTTP session for each client request. This property is required when running in a cluster environment and you need the JSESSIONID cookie to maintain session affinity.|
|provider_<id>.scope||default: 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>.mapIdentityToRegistryUser||default: false||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. When OpenID Connect authenticates a user that is not in the local WebSphere Application Server user registry, an error occurs.|
|provider_<id>.issuerIdentifier||By default, this property is set to the value that is derived from the authorizedEndpointUrl.||Specifies the issuer of the IDToken. When this property is not set, it is derived from the authorizedEndpointUrl value.|
|provider_<id>.userIdentifier||default: 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 when you are using Google's OP.|
|provider_<id>.uniqueUserIdentifier||default: 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>.groupIdentifier||default: groupIds||Specifies the groups attribute name set by the OpenID Connect Provider in the IDToken. For example: groupIds.|
|provider_<id>.realmIdentifier||default: realmName||Specifies the realm attribute name set by the OpenID Connect Provider in the IDToken.|
|provider_<id>.useDefaultIdentifierFirst||default: false||Specifies that, when a custom identifier is specified for the user (userIdentifier), unique user (uniqueUserIdentifier), group (groupIdentifier), or realm (realmIdentifier), the custom value will only be used when the default value does not exist in the token.|
values: none, HS256, RS256, RS512
|Specifies the algorithm that is used to secure messages from the OpenID Connect provider. none, HS256, RS256|
|provider_<id>.jwkEndpointUrl||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 when the signatureAlgorithm custom property is set to RS256 and you do not set the signVerifyAlias custom property to obtain the OP's signing certificate from the default truststore.|
|provider_<id>.jsonWebKeyFile||The file name of a JSON Web Key file that contains the public keys for signature verification.|
|provider_<id>.trustStore||When this property is not specified, the default truststore is used. On a single server, the default truststore is NodeDefaultTrustStore, otherwise, it is CellDefaultTrustStore||Specifies the truststore from which to obtain the certificate specified on the provider_<id>.signVerifyAlias property.
Example values for this property are:
|provider_<id>.signVerifyAlias||Specifies the alias of the certificate in the truststore that might be used to verify the signature from the OP. This property must be set when the signatureAlgorithm custom property is set to RS256 and you do not set the jwkEndpointUrl custom property to obtain the OP's JSON Web Key (JWK).|
|provider_<id>.clockSkew||default: 180||Clock skew, in seconds, to use when verifying the ID token.|
|provider_<id>.refreshExpiredAccessToken||default: true||By default, when an access token has expired, the runtime will attempt to refresh it. Set this property to false when you do not want to refresh access tokens.|
|provider_<id>.refreshBeforeAccessTokenExpiresTime||default: 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>.contentType||default: 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>.allowImplicitClientFlow||default: false||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 using implicit flow. When the property is set to false, the TAI authenticates the Basic Auth token and the LTPA token with the authorization code flow.|
|provider_<id>.tokenEndpointAuthMethod||default: post||When this property is set to 'basic', a BasicAuth header is sent when making a request to the token endpoint.|
|provider_<id>.encodeParameters||default: false||Specifies to URL encode that the client_id and client_secret before sending them to the IdP.|
|Maximum session cookie size that the run time will create. At run time, when the data to be written is larger than the value for this property, the request will be rejected. This property will override the value set for maxCookieSize for session cookies.|
|provider_<id>.introspectEndpointMethod||default: post||To be spec compliant, the HTTP method to use with the introspect endpoint must be POST. To use GET, set this property to anything other than POST. Previous to APAR PI80549, the OIDC runtime always used GET.|
|provider_<id>.defaultRealmName||The realm name to use when one is not obtained from the token.|
|provider_<id>.verifyIssuerInIat||default: false||Set this property to true when you want to validate the issuer (iss) in an introspection access token against the value for the provider_<id>.issuerIdentifier property in the OIDC configuration.|
|provider_<id>.encodeNewline||default: true||When this property is set to false, the new line characters that exist in POST parameters will not be transformed into encoded br tags.|
The time, in minutes, that a session associated with an ID token may remain in the session cache. By default, a session will be removed from the cache based on at least four things, in priority order:
Setting this property will override the value for the ID token expiration for session caching purposes. When this property is set to , only the other three conditions will be used for removing sessions from the session cache. The expiration of ID token is provided on the [exp] claim. When this property is not set to a value in the configuration and there is no expiration in the ID token, the default timeout is  minutes.
When the DynaCache service is not available, the setting will be ignored when this property is set to  because the local cache has no eviction policy.
values:no, required, ifPresent
|This property controls processing when a JWT is found in the request authorization header. The allowed values are:
|provider_<id>.tokenReuse||default: true||Set this property to false when 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.|
|provider_<id>.audiences||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. When ALL_AUDIENCES is specified, then all are trusted. An aud claim must exist in the JWT when this property is set to a value.|
|provider_<id>.setLtpaCookie||default: in the OIDC RP path, true
in the JWT authentication path, false
|Set this property to true when you want the runtime to set an LTPA Cookie on the response after successful authentication.|
values: code, id_token, id_token token, id_token+token
This property defines the value for the [response_type] parameter that will be sent to the OpenID Connect provider on authentication requests. When code is specified, the OpenID connect code login flow is used.
When this property is set to true, a nonce parameter is sent to the OpenID Connect provider on the authentication request. When the responseType property is set to [code], this parameter defaults to false. When the responseType property set to anything other than [code], this property will be set to [true] and cannot be altered.
This property specifies a realm name and is used to override the realm name specified in the ID token. This property also overrides the defaultRealmName property.
Specifies the URL to which the RP is to redirect when a login error is received from an OP.
When this property is set to true, the RP will forward to the error URL, the error, error_description, and error_uri parameters that were received from the OP.
When you want add Content-Security-Policy header to the initial login HTTP request, set this property to the string required. When a nonce is required, you can use the %NONCE% keyword to indicate where the nonce is to be placed in the text; for example, \"script-src 'self' 'nonce-%NONCE%' ; object-src 'self'; frame-src 'self'\"
Set this property to [client_credentials] when you want to enable the provider entry to be used to obtain an access token from the OpenID Provider's token endpoint with the client_credentials grant_type. You can obtain the access token with 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.
|provider_<id>.introspectClientId||default: clientId value||
Specifies the client_id to include in the requests to the OpenId Provider's introspection endpoint.
|provider_<id>.introspectClientSecret||default: clientSecret value||
Specifies the client_secret to include in the requests to the OpenId Provider's introspection endpoint.
Specifies the client identifier to include in the basic authentication scheme of the JWK request.
Specifies the client password to include in the basic authentication scheme of the JWK request.
Set this property to true if the access token that is returned from the OP is a JWT and you want the RP to validate the JWT.
|opServerConnectionTimeout||default: 20000||Specifies the time in milliseconds to wait for the OpenID Connect Provider to respond to an introspection request.|
|sessionCacheSize||default values: -1/10000
minimum value: 1
alternative value: -1 (use active DynaCache default maximum)
|Specifies the size of the cache the OpenID Connect RP uses for session data.
When DynaCache is enabled on the server:
When DynaCache is not enabled on the server:
|sessionCacheCleanupFrequency||default: 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.|
|includeCustomCacheKeyInSubject||default: true||When this property is set to true, the cache key for the Subject in the auth cache will be set to (username)(session-cookie-name)(access-token-string), otherwise the cache key is left up to base security.
The OIDC RP relies on the custom cache key to refresh the access token in the Subject therefore, when you want the Subject to contain the new access token after a refresh, this property must be set to true.
|jndiCacheName||When 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 sessionCacheCleanupFrequency and clusterCaching are ignored.|
|clusterCaching||default: true||Set this property to false when you want each cluster member to maintain their own session cache. When DynaCache is enabled on the application server, it will always be used for cache management, but when this property is set to false, session data will not be shared among cluster members. When DynaCache is enabled on the server, the OIDC TAI allows DynaCache to default the maximum number of entries in the cache. When cluster caching is turned on, the number of cache entries is shared among all cluster members. When cluster caching is turned off, each cluster member can store up to the DynaCache default maximum number of entries.|
|The time, in seconds, that a login request to the OP is allowed to remain outstanding.|
|useStateCookies||default: true||By default, the run time uses both local storage and browser cookies to store request data when a request is redirected to the OP. When this property is false, the OIDC TAI will not use browser cookies; only local storage will be used.|
|useUniqueStateCookies||default: false||When this property is set to true, instead of using a single OIDCSTATE cookie for all requests, each request uses a new OIDCSTATE cookie.|
|useUrlCookies||default: true||During the initial login phase, the OIDC TAI writes a browser cookie called OIDCREQURL_(nnn). The value for this cookie is the original request URL. This cookie is deleted when the login is complete or after the login timeout expires (stateIdTimeoutSeconds), whichever comes first. If you want to maintain this information in other OIDC objects, set this property to false. This property must be set to true when your URL contains fragments or when the inbound URL is encoded and must remain encoded when it reaches the protected resource.|
|maxStateCacheSize||default value: 10000
minimum value: 25
alternative value: -1 (use active DynaCache default maximum)
alternative value: 0 (off)
|Maximum number of state objects that can be in the local state cache. Setting the value to 0 (zero) turns off the local state cache. Setting the value to -1 will make the OIDC TAI inherit the active DynaCache default maximum cache size. When DynaCache is not enabled on the application server, when -1 is specified, this property will revert to its default.|
|Maximum cookie size that the run time will create. At run time, when the data to be written is larger than the value for this property, the request will be rejected. This property applies to, and can be overridden by both maxStateCookieSize and
|Maximum state cookie size that the run time will create. At run time, when the data to be written is larger than the value for this property, the request will be rejected. This property will override the value set for maxCookieSize for state cookies.|
|alwaysInvalidateAccessTokenOnLogout||default: false||By default, when a log out is performed, if an OIDC session cookie is present on a request, the log out is performed using only the information associated with the OIDC session cookie. When there is no OIDC session cookie, then the log out is performed with the access token in the Authorization header of the request.
When this property is set to true, the log out will be performed using information from both the OIDC session cookie and the Authorization header of the request, when they exist.
|provider_<id>.useJwtFromRequest||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.|
This document uses the term WebSphere traditional to refer to WebSphere Application Server v9.0 traditional, WebSphere Application Server v8.5 full profile, WebSphere Application Server v8.0 and earlier, WebSphere classic, traditional WebSphere, traditional WAS, and tWAS.
23 September 2020