OpenID Connect endpoints

Client application makes a call to token server with client id, secret and authorization code to receive the ID token, access token and refresh token.

For more details refer https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint

After receiving an ID Token (JWT), the Client application must verify the signature on it before using it. Below is sample code using following dependency to verify signatures. Readers can choose their choice of approved JWT verification toolkit, below is just a sample and not a recommendation.

Available public keys for ID Token verification are retrieved from the URL (jwks_uri in OpenID Connect Configurations) below, and the received ID Token contains kid claims in the header, that should match one of the available public keys. https://nonprod.identity.healthsafe-id.com/oidc/jwks

It’s worth noting that this code sample is Java code snippet to verify a JWT signed with RS256 using a public key.

Aikyam EDA rotates JWK Set used for ID token verification, following OIDC standard. Retrieving JWK Set for every ID token verification is excessive, and caching JWK Set is recommended, with the following rules:

• When ID token is expired, there is no need for ID token verification, therefore there is no need to refresh the cache.
• When Client (Portal) sees an unfamiliar kid value in unexpired ID token, re-retrieve JWK Set by calling jwks_uri and refresh the cache.
• Re-retrieval of JWK should not be excessive, even it hits this “unfamiliar kid” case. In general, key rotation happens every 24 hours when needed. Therefore, it is unlikely for the Client to see an unfamiliar kid value within 24 hours after the cache refresh, unless ID token is tampered and used for some attacks. At least, minutes of interval could be added if the cache is refreshed recently.
• The natural cache expiration logic can be added. The expiration time would be 24 hours or less, considering the key rotation period mentioned above.
• “unfamiliar kid” cache refresh case could be monitored and logged, to see if it is happening with an unexpected rate or not. (If it happens too frequently, it would be some issues)

To see the content of a JWT ID token, you can decode it using various methods. A JWT is composed of three parts: the header, payload and signature, each separated by a dot (.). The payload contains the claims, which is the part we are interested in viewing. Below is an example of using command line using the ‘tr’ / ‘base64’ / ‘jq’ on Mac or Unix to decode base64-url JWT payload.

Token validity implementation must satisfy following specifications

• Time validity
  • "exp" (Expiration time) claim: token MUST NOT be accepted on or after any specified exp time.
  • "nbf" (Not before) claim
• OIDC ID Token verification specification

On completion of all successful validation of ID Token, client application can extract claims from ID Token and start its own loosely coupled application session and render application specific content to user.

To revoke the token, you can use the endpoint https://nonprod.identity.healthsafe id.com/oidc/token/revoke and pass the parameters client_id, client_secret, token_type_hint = access_token or refresh_token, and token in POST We can revoke both access_token and refresh token using this API.

When an access token obtained by client application has expired, client application can utilize "refresh token” To obtain a new access token. Client application can make a HTTP Post request (from server side – aka not from browser as this request requires passing client secret) at OpenID Connect/OAuth token server to obtain a new access token. Parameters will be client id, client secret, grant_type = refresh_token and refresh_token.

Additional information:

• The response payload contains a new refresh token. Client application must re-store this new refresh token for another access token refresh token endpoint call in the future.
• There is no restriction to how many times a client application can call token endpoint to refresh access token. However, new refresh token will have the same absolute expiration timing as the original refresh token (i.e. calling token endpoint does not extend the absolute expiration timing of the refresh token, for security reasons).
• As a best practice – client application should use refresh token only when the previously obtained access token has expired.
• The “expires_in” for access token obtained from the use of refresh token will mostly be same as the original access token obtained – however it’s advisable for client application to be dynamic enough and read the “expires_in” value every time a new access token is obtained and accordingly schedule the refresh task.

To check validity of the token, you can use the endpoint https://nonprod.identity.healthsafe-id.com/oidc/token/revoke and pass the parameters client_id, client_secret, token_type_hint=access_token and token in POST.

This validation is generally done by the resource server, where the user accesses their resource through applications. The application passes access token as Authorization header (bearer) together with the resource server endpoint call, and the target resource server is generally gated by the gateway server (e.g. Stargate), which does this introspection call, so that each resource server does not need to include this common introspection logic.

Here is the example of checking validity of an access_token.

Once there is a valid access token, User Info can be extracted from the user info endpoint using a GET request as below. Client application may need more identity claims about the user that for security reasons weren’t provided by ID Token validated in Step #11. To achieve that, Client application can invoke a User Info endpoint on OpenID Connect Provider and include access token along with this request (It’s implementation specific whether access token will need to be supplied as a request parameter or in Authorization header, it is preferred to have Authorization header with Bearer token). The User Info endpoint will validate the access token and as per configurations will provide/return more identity claims about end-user to client application.