Understanding refresh tokens, access tokens, and ID tokens in OIDC protocol

Introduction

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 refresh token and access token in the OAuth era, and now here comes new concept in OIDC? Do you really understand the differences between these tokens?

Logto, our comprehensive Customer Identity and Access Management (CIAM) solution, is built on top of the OIDC protocol. In our community, one of the most frequently asked questions from our users is:

What are the differences between a refresh token, an access token and an ID token?

So in this post, we will delve into the key aspects of OIDC tokens, while also illuminating how Logto enhances the overall developer experience.

Let’s start with a practical scenario

Imagine you are working on 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. Then you might come up with the first question:

Which type of token do I need for protecting my API?

The quick answer is: Access token.

In OIDC, each protected API is treated as a resource. The access token is the very credential that the client transmits to the server when requesting an API resource, typically via the request header. On the server side, whenever a request comes in, the server only needs to validate if the incoming request carries a valid access token.

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 refresh tokens and ID 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 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 OIDC introduces refresh tokens.

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).

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.

The essence of ID token

ID token enables the client to obtain basic user information without requesting the server.

The ID token is a JSON Web Token (JWT) that contains user claims such as user name, email, avatar picture, etc. It is signed by the authorization server and can be verified and decoded by the client offline. This is especially useful for modern single-page web apps, and mobile apps, where the client can cache the ID token and use it to determine the user’s authentication status, which greatly helps the overall performance and user experience.

It is also important to note that ID tokens are not used for authorizing access to protected resources; access tokens fulfill that role.

In Logto, we also use ID token in our SDKs to help determine the authentication status on the client side. For example, in our JS SDKs, you can see:

const isAuthenticated = Boolean(await this.getIdToken());

Yet, just as mentioned above, the client SDK’s isAuthenticated flag is only a client cached status. The realtime authentication status still has to be determined by the server, through validating the refresh and access tokens.

We also provide a getUserClaims() function in our SDKs to help you decode the ID token and get the user claims. However, the cached status is not refreshed until the user signs-in again. If you want to fetch realtime user information from OIDC server, use fetchUserInfo() instead.

Logto's benefits and features

Logto is built strictly following the OIDC protocol, meanwhile providing additional features and benefits for developers and businesses:

1. Convenient SDKs: Logto SDKs streamline token management for you. You don’t have to manually store your refresh token and access token yourself. Simply call getAccessToken() every time and the SDK will always try to reuse the stored access token, or automatically renew it if it’s expired.
2. Refresh token rotation: Logto enforces refresh token rotation mechanism to make sure your refresh token is always renewed after it is consumed, which mitigates the risk of being leaked or compromised. Although you can still disable it in the admin console, but it is strongly recommended to keep it on.
3. Optimized performance: With the help of ID tokens, you can always get basic user information without requesting the server. Leverage isAuthenticated status and getIdTokenClaims() function provided by Logto SDKs to check user authentication status and decode user claims on the client side.
4. Enhanced security: Logto enforces secure connections between the client and the authorization server using HTTPS and TLS. This safeguards your tokens against potential theft by unauthorized third parties and guarantees the security of your system.

Conclusion

In the OIDC protocol, Refresh Tokens, Access Tokens, and ID Tokens work together to provide secure and seamless user authentication.

• Refresh tokens eliminate user intervention for new access tokens.
• Access tokens provide authorization to access protected resources.
• 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.

By choosing Logto, developers and businesses can unlock the full potential of such OIDC features, integrate robust and secure authentication systems that protect user data and provide a seamless user experience.