JWT Checks

Your API must perform the following verifications on the JWT it receives.

Mandatory Checks

The following is a list of checks you must perform on every JWT:

  • Verify the signature. You can get the public key to verify the JWT signature at: https://visibility.amp.cisco.com/.well-known/index.html#/Metadata/get__well_known_jwks.

  • Verify the standard expiration dates. The JWT will contain the claims exp and nbf. You should compare them to your local time and ensure that there isn't too much clock skew. There is also an iat claims, but you do not need to perform any check with it as this will not improve the security. Just checking exp and nbf is sufficient.

  • Verify that there is a sub claim is identical to the following claim: https://schemas.cisco.com/iroh/identity/claims/user/id.

  • Verify that the jti claim exists.

  • Verify that the value of the following kind claim must either be session-token or access-token: https://schemas.cisco.com/iroh/identity/claims/oauth/kind. Any other value must be rejected to access your API.

  • Verify that the following Org Id claim exists: https://schemas.cisco.com/iroh/identity/claims/org/id.

  • Verify that the following email claim exists: https://schemas.cisco.com/iroh/identity/claims/user/email.

    Note: in some rare cases, it might not contain a valid email address but the field must exist.

  • If you need to handle specific authorizations, you must only use this claim: https://schemas.cisco.com/iroh/identity/claims/scopes. DO NOT use the role claim.

Audiences

While optional, we recommend that you configure your OAuth2 Client with some audience. Audience configuration is restricted and should be approved by the IROH team.

For your consumption of the JWT, you must verify that the aud claim (which is a list of strings) contains the audience you expect. If you receive a JWT without this audience, it is an indication that the JWT was meant to be used by another API.

Common Issues

  • The certificate used to sign the JWT can change. You should check the JWKS endpoint regularly.
  • Do not check the value of the claim iss (issuer) because this could change for any reason. It does not necessarily contain a specific string nor URL.
  • Never use the role of a user to handle authorizations (access rights). Always use the scopes because the administrator can grant some authorizations to non-admin users.
  • The scopes allowed to the current JWT are specified in the following claim: https://schemas.cisco.com/iroh/identity/claims/scopes. When decoding the JWT, there are other lists of scopes which should not be mandatory. For authorization, do not look at the following:
    • https://schemas.cisco.com/iroh/identity/claims/user/scopes
    • https://schemas.cisco.com/iroh/identity/claims/oauth/scopes