Auth0Free JWT Book

articles

ID Token

Overview

The ID token, usually referred to as id_token in code samples, is a JSON Web Token (JWT) that contains user profile attributes represented in the form of claims. These claims are statements about the user, which can be trusted if the consumer of the token can verify its signature, which is generated with the Auth0 app's Client Secret in the case of HS256. In case the client uses RS256 encryption then the id_token will be signed with a private key and verified with a public key.

The id_token is consumed by the client and used to get user information like the user's name, email, and so forth, typically used for UI display. It was added to the OIDC specification as an optimization so the client can know the identity of the user, without having to make an additional network requests.

The id_token conforms to an industry standard (IETF RFC 7519) and contains three parts: a header, a body and a signature.

  • The header contains the type of token and the hash algorithm used on the contents of the token.
  • The body, also called the payload, contains identity claims about a user. There are some claims with registered names, for things like the issuer of the token, the subject of the token (who the claims are about), and the time of issuance. Any number of additional claims with other names can be added. For the cases where the id_token is returned in URLs, care must be taken to keep the JWT within the browser size limitations for URLs.
  • The signature is used by the recipient to verify that the sender of the JWT is who it says and to ensure that the message wasn't changed along the way.

How to get an ID token

The id_token can be returned when calling any of the Auth0 functions which invoke authentication. This includes calls to the Lock widget, to the auth0.js library, or the libraries for other languages. You can view the implementation details for retrieving the id_token at the Lock web library and Auth0.js library documents.

How to validate an ID token

The way to validate an ID token depends on the hash algorithm used by your Client:

  • If you used HS256 then the token is signed with the Client Secret, using the HMAC algorithm. You can verify the signature using the Client Secret value, which you can find at the Client Settings page.
  • If you used RS256 then the token is signed with a public/private key pair, using RSA. You can verify the signature using the Public Key or Certificate, which you can find at the Client Settings > Show Advanced Settings > Certificates page.

To check or update the algorithm your Client uses go to Client Settings > Show Advanced Settings > OAuth > JsonWebToken Signature Algorithm. The most secure practice, and our recommendation, is to use RS256.

How to control the contents of an ID token

In order to retrieve an id_token the responseType should be set to id_token, both for client-side and server-side authentication flows.

The attributes included in the issued id_token are controlled by the use of a parameter called scope.

  • If scope is set to openid, then the id_token will contain only the iss, sub, aud, exp and iat claims.
  • If scope is set to openid email, then the id_token will contain additionally the email and email_verified claims.
  • If scope is set to openid profile, then the id_token will contain all default profile Claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.

If you are using Lock, the options object used in Lock’s instantiation can specify optional authentication parameters as follows:

var options = {
  auth: {
    responseType: 'id_token',
    params: {scope: 'openid email'}
  }
};

var lock = new Auth0Lock(
  YOUR_CLIENT_ID,
  YOUR_AUTH0_DOMAIN,
  options
);

lock.show();

The id_token will contain only the claims specified as the value of the scope parameter.

Add claims using Rules

If you are using OAuth 2.0 API Authorization, you can add claims to the id_token using Rules, with the following format: context.idToken['http://my-custom/claim'] = 'some-value'.

Lifetime

The purpose of the id_token is to cache user information for better performance and experience, and by default, the token is valid for 36000 seconds, or 10 hours. You may change this setting as you see fit; if there are security concerns, you may certainly shorten the time period before the token expires, but remember that the id_token helps ensure optimal performance by reducing the need to contact the Identity Provider every time the user performs an action that requires an API call.

The expiration time can be changed in the Dashboard > Clients > Settings screen using the JWT Expiration (seconds) field.

There are cases where you might want to renew your id_token. In order to do so, you can either perform another authorization flow with Auth0 (using the /authorize endpoint) or use a Refresh Token.

When performing the initial authorization flow, you can ask for a refresh_token, by adding offline_access at the scope parameter, for example scope=openid offline_access. The refresh_token is stored in session, alongside with the id_token. Then when a session needs to be refreshed (for example, a preconfigured timeframe has passed or the user tries to perform a sensitive operation), the app uses the refresh_token on the backend to obtain a new id_token, using the /oauth/token endpoint with grant_type=refresh_token.

This method is not an option for Single Page Apps (SPAs), since for security reasons you cannot get a refresh_token from the Implicit Grant (the OAuth flow typically used from Client-side Web Apps). In that case you would have to use silent authentication.

If you are using auth0.js on an SPA, then you can fetch a new token using the renewAuth() method.

auth0.renewAuth({
  audience: 'https://mystore.com/api/v2',
  scope: 'read:order write:order',
  redirectUri: 'https://example.com/auth/silent-callback',

  // this will use postMessage to comunicate between the silent callback
  // and the SPA. When false the SDK will attempt to parse the url hash
  // should ignore the url hash and no extra behaviour is needed.
  usePostMessage: true
  }, function (err, authResult) {
    // Renewed tokens or error
});

Revoke access

Once issued, tokens can not be revoked in the same fashion as cookies with session id’s for server-side sessions. As a result, tokens should be issued for relatively short periods, and then renewed periodically if the user remains active.

More Information