Client Checklist

⚠ IMPORTANT

As a client of IROH, you must take care of the following details.

Do Not Rely Only on the JWT Expiration Date

Keep in mind that:

  • JWT can be revoked anytime.
  • Users can revoke the grant of your application.
  • IROH can also reduce the lifetime of JWTs.

You can alway check the validity of a JWT using the following request: https://visibility.amp.cisco.com/iroh/session/session-status

Your integration should take care of the following:

  1. Expect to get back a 401 HTTP status even from a totally valid JWT. When getting a 401 status response, you should try to get a new access token.

  2. Refer to those requests to have technical details, in particular you will get the issuer of IROH JWTs as well as the public key that you can use to verify the JWT:

While those values might not change often, they will change. In particular, the JWT signing key will change. The issuer might change due to region changes.

Change Refresh Token

  1. As stated in the OAuth2 RFC, if IROH provides you a new refresh token, you must revoke the old one and replace it. IROH should accept the old refresh token for a short grace period after which your refresh token will be rejected.

  2. If you cannot retrieve a new access token from the refresh token, you must ask the user to approve your application again to get a new refresh token.

Do Not Rely on the JWT Scopes Claim

Even if you hold an access-token that contains the scopes field, you should not rely on this information to accurately attribute the permissions of a user.

IROH can change the JWT specific claims for certain clients, especially if there are size constraints to the JWT and the scopes field will no longer be present.

Consider to make a HTTP GET request to https://visibility.amp.cisco.com/iroh/profile/scopes to get the full list of scopes for that specific user.