The Identity Service provides a central authentication store exposed over a REST service.

Workflow

The user provides their credentials (username and password) to the Identity Service, and requests an access token. This access token may be a JSON Web Token (JWT), and contain information that describes the user, including any roles that they have. This access token is also signed by the Identity Service's private key, so anyone that has the public key can verify that the access token definitely comes from the Identity Service.

Access tokens are short-lived, and only valid for a short duration of time. The time at which it expires is included in the JWT. When a user successfully requests an access token, they will also be provided with a refresh token. Before the access token expires, a user can send the refresh token to the Identity Service in order to receive a new access token and refresh token. This immediately invalidates the old refresh token but the old access token will still work until it expires. This allows user to re-authenticate with the Identity Service without having to send their username and password every time, thus reducing their exposure.

The user may then request resources from a back-end service that requires them to be authenticated. To do this, the user includes his access token along with their request. The back-end service should then check that:

• the access token has not expired.
• the access token is authentic by validating it against the Identity Service's public key.
• the access token indicates that the user has the correct permissions to access the requested resource.

If all of these conditions are true, then the service returns the resource that was requested.

Access tokens

An Access Token is a JSON Web Tokens (JWT). These are used to communicate authorization and authentication between services, and allow this to be done without the 3rd party service from having to communicate with the Identity service directly, through the magic of private key and shared public key.

An example of a JSON Web Token is as follows:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MTgxNTcxNzEsInBlcm1pc3Npb25zIjoiYWRtaW4gaWRlbnRpdHkgbGV2ZWwwIHJhYmJpdG1xIHJlcG9ydCBzdHMiLCJ1c2VybmFtZSI6InNlcnZpY2UifQ.CUtlNsJWCh-5von_YGQmKevlxjKwdFsQw3lYq5wi6nP-LnxxutUGvckPTSFUfryGiAKZxbDHoMXJ2VBmnef2_zom0MTAcRkvBs0g6paTzZWkahwepnicQLourygQNcVgC_7OeQidyr04h041qhZdt4CWBMwok2wBOS9k975G2gHrcTiSIFzA-qykyItuqivearnLHqat0XCtmtRjjEjapy4Q60tU7rf-EcgLzdeXZOHZOuvyxck8LoDmwU0KBDUkAanStaIjmlcR5hEg2bGDBcVxzNiK6mXPcDwYffsLHhb_pvsve_GPfiYhRtVNhi8krIsniUPLaBJvkOwuqj7V4w

This is delimited by the . character, and is broken up into three distinct parts:

1. Header
2. Payload
3. Signature

For more information on JSON Web Tokens, see https://jwt.io.

Refresh tokens

A Refresh Token is simply a unique string associated with a particular Access Token, which may be used while the Access Token is still valid (not expired) in order to obtain a new Access Token and Refresh Token pair.

This is typically used in order to implement fast-expiring tokens, while allowing a user to remain authenticated for an extended period of time.

For example, lets say an Access Token remains valid for an hour. If a user authenticates with the Identity service at 13H45, they will be issued with an Access Token that expires at 14H45, and a uniquely associated Refresh Token.

If that user sends the Refresh Token to the Identity service before 13H45, they will be issued with a brand new set of tokens, and the previous tokens will immediately become invalid and unuseable. However, they will have the new tokens, so should be able to continue working seemlessly.

If they user attempts to use the Refresh Token after the Access Token has expired, they will receive an authentication error from the Identity service.