Understanding access tokens, refresh tokens, and ID tokens in OpenID Connect (OIDC) protocol

OIDC, OAuth 2.0, and tokens#

The OpenID Connect Protocol, also known as OIDC, has emerged as a widely adopted standard for providing a fundamental framework for identity management. It is an authentication layer built on top of the well-known OAuth 2.0 protocol. While OAuth 2.0 is merely for resource authorization, OIDC is the protocol that standardizes and strengthens client authentication, with the help of the new introduced ID token.

Wait... You might have heard of access tokens and refresh tokens in the OAuth era, and now here comes the new concept in OIDC? Do you really understand the differences between these tokens?

What are the access tokens, refresh tokens, and an ID tokens in OIDC?#

Let's start with a practical scenario.

Imagine you are developing a typical client-server application, and they communicate to each other through RESTful APIs. You want to keep most of your APIs private, permitting only authorized clients to access. You will need a mechanism to authenticate the client and authorize the API requests to your server.

Ideally, your RESTful APIs should be stateless, meaning the server should not store any client session information. Whenever a valid request comes in, the server should just respond with the requested data. This is where tokens come into play. So, what type of token should you use in such case?

Access tokens are used for protecting your APIs#

In OAuth 2.0 and OIDC, each protected API is treated as a resource. The access token is the very token that the client transmits to the server when requesting an API resource, typically via the request header and in JWT format.

On the server side, whenever a request comes in, the server only needs to validate if the incoming request carries a valid access token. The validation process usually includes decoding the JWT token, verifying the signature and expiration time, as well as the scope claim to ensure the client has the necessary permissions.

However, you might ponder: If my client application can have a valid access token after a successful login, and use the access token to request server APIs, isn't that sufficient? Why do I need the other tokens?

Indeed, a valid question, and let's explain it step by step.

Why do we need refresh tokens?#

While technically access tokens do meet the minimum requirements to make the system work, however, due to security concerns the validity of the access tokens are usually very short (typically an hour). So imagine if we only have access tokens, the end users will have to re-authenticate every time the access token expires. For modern single-page web applications (SPAs) and especially mobile applications, frequently logging out is a rather painful user experience, even though we are just trying to protect their user security.

Therefore, we need a balance of token security and user convenience. That's why the refresh tokens are introduced.

Why can refresh tokens have longer lifespan?#

Access tokens are used to access API resources, so their short-lived nature helps mitigate the risk of being leaked or compromised. On the other hand, since refresh tokens are only used to exchange for new access tokens, they are not used as frequently as access tokens and thus the risk of exposure is reduced. Therefore, having a longer validity period is considered acceptable for refresh tokens.

Ensuring refresh token security#

Since the refresh token is also stored on the client side, ensuring their non-compromise is challenging, especially for public clients such as single-page web applications (SPA) and mobile apps.

In Logto, refresh tokens have an automatic rotation mechanism enabled by default, which means the authorization server will issue a new refresh token once the it meets the criteria:

• Single-page applications: Recognized as non-sender constrained clients, these apps mandate refresh token rotation. The refresh token's time-to-live (TTL) cannot be specified.
• Native apps and traditional web apps: Refresh token rotation is inherently enabled, automatically renewing upon reaching 70% of its TTL. Learn more

While you still have the option to disable refresh token rotation on application details page in admin console, it is strongly recommended to retain this safeguarding measure.

What is an ID token and why is it important?#

The ID token is a unique feature of OIDC that provides identity information about the authenticated user.

While access tokens are used to access protected resources and refresh tokens are used to obtain new access tokens, the ID tokens are typically used to cache user information on the client side, reducing the need to make additional requests to the authorization server for user data. In most cases, it's even safe to say, having the ID token is equivalent to user being authenticated.

Best practices for handling tokens#

• Use HTTPS: Always use HTTPS to secure the communication between the client and the authorization server. This prevents unauthorized parties from intercepting and stealing tokens.
• Set proper token expiration time: Access tokens should have a short lifespan to minimize the risk of exposure. Refresh tokens can have a longer validity period.
• Enable refresh token rotation: Implement refresh token rotation to mitigate the risk of refresh token leakage.
• Use fine-grained access control: Use fine-grained scopes to limit the permissions of access tokens. Only request the permissions necessary for the client application. Avoid using "all" or "admin" scopes to bypass most permission checks unless absolutely necessary.

Recap: Key differences of access tokens, refresh tokens, and ID tokens in OIDC#

In the OIDC protocol, refresh tokens, access tokens, and ID tokens work together to provide secure and seamless user authentication.

• Access tokens provide authorization to access protected resources.
• Refresh tokens eliminate user intervention for new access tokens.
• ID tokens provide cached user information on the client, enhancing performance.

Understanding the role and significance of these tokens is crucial for developers implementing OIDC authentication in their applications.