Validate Access Tokens

When using IMSG

For services hosted behind an IMSG, nothing needs to be done. The IMSG does already support access tokens. The IMSG will take care of validating the access token and create a service token, just as if the API was accessed with an ID token.

Validate without IMSG

Authentication

Authentication means being sure of who the caller is

The steps required to ensure an access token is valid are the following:

1. Ensure ntt (Naviga Token Type) claim in the access token payload equals access_token

2. Read the kid (key id) from the access token header.

3. Fetch the corresponding public key from https://imas.stage.imid.infomaker.io/v1/jwks for stage env or https://imas.imid.infomaker.io/v1/jwks for production env.

4. Ensure alg (algorithm) in the access token header is identical to the key's alg

5. Use a suitable library for your language to validate the access-token signature using the key

6. Check that current time is less than exp in access token payload.

It's important that server clock is synchronized, if not, the application might accept tokens that have expired.

The keys published on /jwkscan, and should, be cached for up to 10 min in the application.

Note, a token with a kid that does not exist in a cached /jwks might still be a valid token. It might be that a new key has been published but not yet fetched by the application. For that reason, the application should re-fetch the /jwks (once) if an unknown kid appears.

Similarly, a key might be revoked at any time, so never cache /jwks for more than 10min. If /jwks is cached for a longer period of time, tokens with invalidated kid/signature can appear to be valid when they are not.

Authorization

Authorization means knowing what actions the caller is allowed to do

Permissions are included as described by the payload below. Permission strings are on the format service_name:permission_name. Permissions in the permissions.org array should are valid in all units while permissions in permissions.units[unit_name] array is only valid in that specific unit.

More information about Naviga ID's permission model can be found on the authorization schema page.

The Access Token payload is as follows:

{ 
  "ntt": "access_token", // ntt stands for Naviga Token Type
  "org": string, // org name
  "sub": uuid_string, // subject is the unique user id in Naviga ID
  "groups": [string, string,...], // groups the sub belongs to in the organization's identitity provider
  "userinfo": { 
    "given_name": string, // optional
    "family_name": string,  // optional
    "email": string, // optional
    "picture": string // optional
  },
  "permissions": {
    "org": [string, string,...] // permissions valid in all units,
    "units": {
      unit_string_name : [string, string...], // permissions only valid in unit unit_string_name
      ...
    } 
  } 
  "iat": unix_timestamp_seconds, // issued at
  "exp": unix_timestamp_seconds,  // expires at
  "jti": uuid_string, // token id
}