Design and Implementation

Sequence Diagram

Pre-processing

Iamge

Post-Processing

Iamge

Implementation Details

The policy fetches the token endpoint from the pre-input configurations and checks whether the cache key is available in the cache. If the keys do not exist or the key exists but the token has expired, a new token is fetched from the token endpoint and is cached.

note

In PreInputs Values, you must provide the values for defaultTtl,tokenRequestURI, readTimeout, and connectTimeout. If these values are missing, an exception will be thrown.
In the PostInputs Values, if introspectRequestURI is provided, then you must provide values for clientId, clientSecret, readTimeout, and connectTimeout. If these values are not provided, an exception will be thrown.

The policy reads the token endpoint details provided in the Pre-Input to make a call to the token endpoint to obtain an access token in the pre-process.
Any failure in pre-processing, such as obtaining a token, storing an access token, or failing to connect to the token endpoint, results in a call failure.
Upon successful pre-processing, the policy adds the access token received in the header authorization as a Bearer token.
After the target response is received for Post-processing, if introspectRequestURI details are provided in the token endpoint response, an introspect request is sent to get the details for the access token received in the token endpoint response.
The TTL calculated from the introspect endpoint is used to update the cache TTL only if it was set using the defaultTtl. However, if TTL was set using expires_in from the token endpoint response, then the introspect request is not required and hence not sent because expires_in received in the token response takes priority.

If introspectRequestURI is not provided, then no introspect request will be sent, and the cache TTL value set in the PreInputs Values field will be the defaultTtl value provided in pre-inputs.
If the target response returns a 401 error, the existing key is deleted from the cache only if it was not created within the last 5 minutes. The key is deleted to prevent further requests from using an invalid token. The 401 error indicates that the access token is no longer valid. However, if the token was created in the last 5 minutes, no action is taken. This is done to prevent thread contention between introspect and token endpoint requests.
When a scope value is provided in PreInput Values (Local Edition 6.3.0 and later versions only), the policy trims trailing spaces and URL-encodes it before adding it to the token endpoint request body, per the OAuth 2.0 spec (RFC 6749).

note
If you update scope on an endpoint that already has a cached token, the update won't take effect until that token expires. Calls made before then still use the token issued under the old scope. After it expires, the policy requests a new token, which uses the new scope.

Error Messages

Error Name	Error Message	HTTP Status Code	Cause
`InvalidPreInputConfiguration`	`defaultTtl` is required.	412	The `defaultTtl` is missing in PreInput Value.
`InvalidPreInputConfiguration`	`defaultTtl` is not a valid number.	412	The `defaultTtl` is provided incorrectly in PreInput Value.
`InvalidPreInputConfiguration`	`connectTimeout` is required and should be an integer greater than 0.	412	The `connectTimeout` is missing in PreInput Value.
`InvalidPreInputConfiguration`	`readTimeout` is required and should be an integer greater than 0.	412	The `readTimeout` is missing in PreInput Value.
`InvalidPreInputConfiguration`	`tokenType` can only be `Bearer` if provided.	412	The `tokenType` is invalid. Only `Bearer` is allowed.
`InvalidPreInputConfiguration`	`grantType` can only be `client_credentials` or `password` if provided.	412	`grantType` is invalid. Only `client_credentials` and `password` are allowed.
`InvalidPreInputConfiguration`	`tokenRequestURI` is required and should be a valid, well-formed address.	412	The `tokenRequestURI` is invalid.
`InvalidPreInputConfiguration`	`tokenClientCredentialsLocation` can only be `header` or `body` if provided.	412	The `tokenClientCredentialsLocation` is invalid.
`InvalidPreInputConfiguration`	`clientId` is required.	412	The `clientId` is not provided.
`InvalidPreInputConfiguration`	`clientSecret` is required.	412	The `clientSecret` is not provided.
`InvalidPreInputConfiguration`	Username and password is required for password `grant_type`.	412	Username or password is not provided in PreInput Value.
`InvalidPreInputConfiguration`	Exception in decrypting client credentials.	500	The `clientId` and `clientSecret` are not correctly encrypted in PreInput Value.
`InvalidPreInputConfiguration`	Exception in decrypting username/password	500	Username and password are not correctly encrypted in PreInput Value.
`InvalidPostInputConfiguration`	`introspectRequestURI` is required and should be a valid, well-formed address.	412	The `introspectRequestURI` is not a well-formed URI.
`InvalidPostInputConfiguration`	`connectTimeout` is required and should be an integer greater than 0.	412	The `connectTimeout` is not provided in PostInput Value.
`InvalidPostInputConfiguration`	`readTimeout` is required and should be an integer greater than 0.	412	The `readTimeout` is not provided in PostInput Value.
`InvalidPostInputConfiguration`	Exception in decrypting client credentials.	500	The `clientId` and `clientSecret` are not correctly encrypted in PostInput Value.
`InvalidPostInputConfiguration`	Exception in decrypting username/password.	500	Username and password are not correctly encrypted in PostInput Value.
`TokenEndpointRequestFailure`	Token Endpoint Request Interrupted.	502	Request to the token endpoint failed.
`TokenEndpointRequestFailure`	Error putting fetched token in cache.	500	Could not put access token in cache.
`TokenEndpointRequestFailure`	Error in reading response.	500	Token Endpoint returned an invalid or unexpected response.
`TokenEndpointRequestFailure`	Error fetching OAuth token from cache.	500	Could not get existing access token from cache.
`TokenEndpointRequestFailure`	Error received in response from token endpoint.	502	Error received in token endpoint response.
`IntrospectEndpointRequestFailure`	Introspect Endpoint Request Interrupted.	502	Request to introspect endpoint failed.
`IntrospectEndpointRequestFailure`	Error in reading response.	500	Introspect Endpoint returned an invalid or unexpected response.
`IntrospectEndpointRequestFailure`	Error received in response from introspect endpoint	502	Error received in introspect endpoint response.