ID Tokens

The ID Token is conceptually the same as an identity card, with information about a user packaged as a JWT token. It is used by the application (client) to identify the user as a result of an authentication. 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

The Access Token is conceptually the same as an entrance ticket, with information about a user or application packaged as a JWT token or just a random string. It is used by a resource server (API) to allow the call or not and it should not be used by the client at all. A client should not pass the ID Token to the resource server.

The access tokens created by Authway is passed as Bearer tokens to the resource server. Authway supports two different types of access tokens that are configured per client:

• JWT tokens
• Reference tokens, which is just a random string. This random string is exchanged for token claims when the resource server uses the introspection endpoint. The resource server must identify itself when calling the introspection endpoint.

  {
   "iss": "https://instance.irmciam.se",
   "nbf": 1311277370,
   "iat": 1311280970,
   "exp": 1311281970,
   "client_id": "client",
   "jti": "44CE5DT8B9F8E7F2DCB231ED6C546BE8",
   "scope": "api1",
   "token_type": "access_token",
   "active": true
  }

An Access Token has these features:

• Specifies the issuing authority, represented with a iss claim.
• Is generated for a specific application, called client in OIDC and represented with a client_id claim.
• Has an issue (iat claim) and expiration time (exp claim) as well as a not before time (nbf claim).
• A unique identifier of the token, represented with the jticlaim.
• The scope that the access token is inteended for. The resource server should validate the scope to be sure that the access token is inteended to be used for this resource (or not).
• May contain other claims about the user and/or client, like name and email, depending on what claims are configured to be part of the scope.

In the case of introspection the returned claims will also have these features:

• A value indicating if the token is still valid, represented with the active claim.
• The type of token.

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

The revocation endpoint can be used to revoke access tokens (reference tokens only) and refresh tokens.

POST /connect/revocation HTTP/1.1
Host: instance.irmciam.se
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=...&token_type_hint=refresh_token

Explanation of the request parameters in the example:

• token must contain the token to revoke and is a required parameter.
• token_type_hint is an optional parameter with either access_token or refresh_token

The revocation endpoint is one way to sign-out a user with a backchannel call, but to do a full sign-out of a user it is better to use the End session endpoint which uses the browser to do the sign-out.