Validating Access or ID Token - omnissa-archive/idm GitHub Wiki

Validating your Access or ID Token

Your app can validate Access and ID tokens itself or it can pass them to VMware Identity Manager for validation. Validating the tokens within your app is generally the better choice; it’s faster, requires no additional API calls, and can be done easily with common JWT libraries. The only downside of validating locally local validation cannot tell you if a token is revoked by Identity Manager. The best combination of security and performance for most apps comes from validating tokens locally for performance and asking for very short-lived tokens (around five minutes) for security.

If you want to validate tokens within your app, see Validating tokens locally. If you want to send tokens to Identity Manager for validation, see Validating tokens at the Identity Manager token endpoint. Only Access tokens can be validated using the Identity Manager endpoint.

Understanding tokens: What is a JWT?

Identity Manager uses the JWT format for Access and ID tokens.

JWT stands for JSON Web Token. A very good explanation of JWTs can be found at https://jwt.io/introduction/.

A JWT is composed of 3 parts separated by dots (.) that are URL encoded:

A header: contains information about the token type and the algorithm used to sign/encrypt the token
A payload: contains the in the token claims
A signature: the header and claims are signed using the algorithm specified in the header.

These parts of the JWT are combined like this: <header>.<payload>.<signature>

Identity Manager creates its JWT signature by base64url encoding the header, payload, and a secret and encrypting the string with RS256: RS256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)

Why should I validate a JWT?

The JWT should never be trusted as is—JWTs can be reused, intercepted, or spoofed by attackers. When your app receives a JWT, it should always validate it:

Validate the algorithm used is RS256
Validate the signature
Validate the token was intended for your application
Validate the token has not expired

Validating tokens locally

For example code showing how to validate tokens locally, see the Java sample application, or the Go implementation in our CLI tool.

Because Identity Manager JWT Access Token and ID Tokens, you can use common JWT libraries to make validation easy. The https://jwt.io/ site maintains a list of JWT libraries with notes on what validation features they include.

When picking a library to use with Identity Manager JWTs, make sure it meets the following requirements:

RS256 support
Signature verification
iss verification
exp verification
nbf verification
iat verification

Once you’ve picked a library, your app needs to get Identity Manager’s public key to use for token validation. The public key is available in JWK format by default, but can also be requested in PEM format.

Getting Identity Manager’s public key

To get Identity Manager’s public key, make a call to the following endpoint:

GET https://[tenant location]/SAAS/API/1.0/REST/auth/token

The URL accepts the following query parameters:

attribute=publicKey. Required.
format=pem. Optional. Your app can receive the public key in PEM format rather than the default JWK format using this parameter.

Example Request

GET https://acmecorp.vmwareidentity.com/SAAS/API/1.0/REST/auth/token?attribute=publicKey

Identity Manager will respond with a public key in the format you requested.

Example JWK response

{
 "alg":"RSA",
 "mod":"154675937118342208940229283653317844719008594292395458891707502085911308623056413736878494976093211526578988160068209226859232263248068815437014749304613654419078204639340886884754366331879598157014621752774637503664934309963040984593807701429638049054316249615797032695411334328096938536768696119132549304813",
 "exp":"65537",
 "kid":"1466446999"
}

Example PEM response

Once your app has Identity Manager’s public key, you can use your JWT library to validate the JWTs from Identity Manager.

Validating the JWT signature

To validate the JWT’s signature, use the public key from Identity Manager. Check the signature is SHA-256.

In the Java example, the Spring library takes care of the signature validation when the JwtAccessTokenConverter bean is created with Identity Manager public key.

Validating JWT claims

To ensure that the JWT your app receives is still valid and comes from Identity Manager, you should verify the following claims in the JWT:

"iss" : "https://[tenant location]/SAAS/auth". The issuer of your token should be your Identity Manager tenant. To verify this claim, make sure the URL matches your tenant location and follows the path /SAAS/auth. For example, with acmecorp.vmwareidentity.com as the tenant location, the URL would be https://acmecorp.vmwareidentity.com/SAAS/auth.
"exp":[expiration in unix time]. The time at which the JWT will expire. Given in Unix time. Make sure the time given has not passed.
"iat":[issuing time in unix time]: The time at which the JWT was issued. Given in Unix time. Make sure the "iat" value was in the past.
"nbf":[activation time in unix time]. For ID Tokens. This is the "not before" time, or the time before which JWT must not be used. Given in Unix time. Make sure the time given has not passed.
"aud":"[client_id]". For ID tokens. The audience must be checked to ensure it matches the client_id used to get this token.
"at_hash":[at_hash value]. Only available in ID Tokens. This value links an ID Token to the Access Token it was issued with. When using the Authorization Code Flow, your application may use it to validate the Access Token. To validate it, encrypt the access token with SHA-256. After encrypting, take the 128 left-most bits and base64url encode them. This value should match the at_hash value. For more information, see http://openid.net/specs/openid-connect-core-1_0.html#ImplicitTokenValidation.

Once your app has validated these claims, it can assume the JWT it received is valid and from Identity Manager.

For ID tokens validation, refer to http://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation

Validating tokens at the Identity Manager token endpoint

Your app can validate an Access token by sending it to the Identity Manager token endpoint. If the token is valid, Identity Manager responds with true. Otherwise, Identity Manager responds with false. Identity Manager does not validate ID Tokens.

Your app needs to send the following request:

GET https://[tenant location]/SAAS/API/1.0/REST/auth/token

The URL requires the following query parameters:

attribute=isValid. Required.

The URL requires the following headers:

Authorization: Bearer [Access Token]. Use the Access Token you want to validate.

Example Request:

GET https://acmecorp.vmwareidentity.com/SAAS/API/1.0/REST/auth/token?attribute=isValid

Headers:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiIxM2NjOTUyMi0zZWQwLTRkNjEtYTgyMi04MTdmYWVjYzAxNWMiLCJwcm4iOiJBY21lX0FwcElEQFNJTEVSQiIsImRvbWFpbiI6IkxvY2FsIFVzZXJzIiwidXNlcl9pZCI6IjEwODc1ODIiLCJhdXRoX3RpbWUiOjE0NzgwMjI0NDAsImlzcyI6Imh0dHBzOi8vc2lsZXJiLnZtd2FyZWlkZW50aXR5LmNvbS9TQUFTL2F1dGgiLCJhdWQiOiJodHRwczovL3NpbGVyYi52bXdhcmVpZGVudGl0eS5jb20vU0FBUy9hdXRoL29hdXRodG9rZW4iLCJjdHgiOiJbe1wibXRkXCI6XCJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6YWM6Y2xhc3NlczpQYXNzd29yZFByb3RlY3RlZFRyYW5zcG9ydFwiLFwiaWF0XCI6MTQ3ODAyMjQ0MCxcImlkXCI6MjE3NzI5fV0iLCJzY3AiOiJhZG1pbiIsImlkcCI6IjAiLCJlbWwiOiJPQXV0aENsaWVudF9BY21lX0FwcElEQG5vcmVwbHkuY29tIiwiY2lkIjoiQWNtZV9BcHBJRCIsImRpZCI6IiIsIndpZCI6IiIsImV4cCI6MTQ3ODA0NDA0MCwiaWF0IjoxNDc4MDIyNDQwLCJzdWIiOiIxZDIzY2IyYS0yMGYzLTRlNWUtYjdlZS03MWVhYmRiMmZhMmMiLCJwcm5fdHlwZSI6IlNFUlZJQ0UifQ.BKMCTTK5kzN2pm0BwVbQob6AXXBBFOzptWQSKOtkQM7weSJNiblEoGgXosYr_DG-EGomSWvoICjdaH6eqJtvE9XZ9lq9M2XUP5D7VwAgRh00m5X7c0IcmuZB0MJDyvwaF0OvYiHGgsSqTlzzgrgIGqw6b8RQUtFjpEMkl95J0r8

If the token is valid, Identity Manager responds with true. Otherwise, Identity Manager responds with false

This endpoint does not validate ID tokens.