ID Tokens

The ID Token is conceptually the same as an identity card, with information about a user packaged as a JWT token. ID Tokens can be returned as a result when an application makes an OpenId Connect (OIDC) authentication request to the Identity Provider. The statements (called claims) of an ID Token are packaged in a simple JSON object (this is the Body of the JWT token).

  {
   "iss": "https://instance.irmciam.se",
   "sub": "f404a4ff-6037-4097-afa7-24b397239009",
   "tid": "d10a1624-6de7-4b50-b662-0f1cc6733edf",
   "aud": "APPLICATION CLIENT ID",
   "nonce": "VALUE",
   "exp": 1311281970,
   "iat": 1311280970,
   "auth_time": 1311280969,
   "amr": "pwd"
  }

An ID Token has these features:

• Asserts the identity of the user, called subject in OIDC and represented with a sub claim.
• Asserts the identity of the tenant, represented with a tid claim. This is not standardized or required in the protocol, but a claim that Authway always issues.
• Specifies the issuing authority, represented with a iss claim.
• Is generated for a specific application, called client in OIDC and represented with a aud claim.
• Has an issue (iat claim) and expiration time (exp claim).
• May contain other protocol claims like
  • A nonce that associates a client session with the token, which is used to mitigate replay attacks.
  • One or more authentication method reference (amr claim) that represents how the user was authenticated. There are standardized values that Authway uses if it exists.
• May contain other claims about the user, like name and email, depending on what scopes was requested.

The ID token header, claims JSON and signature are encoded into a base 64 URL-safe string, so it can easily be passed around.

Considerations to make for ID Tokens

What claims end up in the ID Token is controlled by passing Scopes to the Authorization endpoint. The openid scope is required when requesting an ID Token, but other can be requested to retrieve more information about the user. In Authway the openid scope contains the sub and tid claims.

When requesting many scopes the returned ID Token will contain many claims, which can result in a large ID Token. The size of the token can effect how good it is to keep in a cookie or other state for the client application. It is good to keep the token as small as possible. It is possible to request more information about the user from the UserInfo endpoint instead. The downside of that alternative is that it results in more network requests which can affect the latency of the application during sign-in.

Access Tokens

Refresh Tokens

Refresh tokens are used to retrieve a new access token for a user without requiring the user to interactively authenticate again. A refresh token is typically long-lived (from days up to a month is common), but they enable the creation of short-lived (from minutes to hours) access tokens. This is good from security perspective since anyone that is in possession of an access token is allowed to call API:s that the token has access too and by giving them a short life-time the consequence of a stolen access token is less than if it is long-lived.

Get a refresh token

It is easy for the application to request a refresh token, since all that is necessary is to add the offline_access scope to the scope parameter list when making the authorization request.

Since it is a privileged operation to use a refresh token, the client must be configured to allow offline access. In client administration it is also possible to configure for how long a refresh token is valid and other settings.

Use a refresh token

The refresh token is used to retrieve a new access token (and/or ID token) for a user without re-authenticating the user. This should be done a short while before the access token expires (and not each time you need an access token) so that you always have an access token that are valid when calling the API.

To get a new access token, the refresh token is send to the token endpoint and the result is a token response containing a new access token, its expiration and potentially a new refresh token.

POST /connect/token
    client_id=client&
    client_secret=secret&
    grant_type=refresh_token&
    refresh_token=the_refresh_token

Security Consideration

Refresh tokens are extremally valuable (because they are long-lived) and must be carefully protected by the clients that are allowed to use them.

Refresh Token Rotation

By default Authway rotates the refresh token on each usage so that the refresh token only can be used once. This reduces the attack surface because there is a chance that a stolen token becomes unusable before the attacker have used it.

Since this is the default configuration for a client, it is important that the client takes this in consideration when using the refresh token. The client is responsible to synchronize the renewal between threads (so the refresh token isn’t used multiple times) and since the second use of a refresh token will result in a response with status code 400, it is a risk that the client invalidates the user session.

For .NET developers we recommend you to use Duende Access Token Management which has support for many token management tasks.

Revoke Tokens