Connecting the dots: An in-depth exploration of OIDC resource and your JWT access tokens

Background#

In a previous session, we provided an introduction to the OpenID Connect (OIDC) Protocol, refresh tokens, access tokens, and ID tokens, essential components for building robust authentication in your application. However, questions still linger in our community, with one recurring inquiry: "Why is my access token not a JWT?”

For those new to the concepts, or even for those needing a refresher, this blog post aims to shed light on the relationship between OIDC resource indicators and their role in obtaining access tokens.

Understanding OIDC resource#

If you are familiar with OAuth 2.0 protocol, the term “resource” should ring a bell. As OIDC is built upon OAuth 2.0, it inherits this same concept.

A "resource" or "protected resource" is a representation of an entity that the client application wants to access on behalf of the authenticated user. This could be user information, server APIs, or any other data authorized by your server.

According to the protocol, the resource is a parameter in requests to the authorization server. It's a value represented as an absolute URI, like https://my-company.com/api. It acts as an identifier for the resource, potentially corresponding to a network-addressable location or even a unique but fictional URI.

In Logto, you can create an “API resource” through the “Admin Console → API resources” page. You can refer to this documentation for more details.

JWT access token#

The JWT (JSON web token) format access token is issued only when the "resource" parameter is specified during the access token request, and it carries a set of claims, which you can decrypt and validate, for example, to ensure the token's integrity and the user's permissions.

This "resource" then becomes one of the aud token claim in the JWT, indicating the intended audience for the token. See RFC-7519.

So, the relationship becomes clear:

• Specify the resource indicator when requesting a JWT token.
• The resource indicator aligns with the aud token claim.
• When making API requests, the JWT access token must be included as the bearer token header. Your API server should decrypt and validate the aud claim and other permission-related claims to secure the API request.
• Each access token corresponds to a single resource. If you have multiple API resources registered with different URIs, request distinct access tokens for each.

🤔 But what if the client doesn't specify the resource when requesting the access token?

Opaque access token#

In Logto’s case, if the resource indicator is not specified when requesting the access token, the authorization server assumes it is for the OIDC /userinfo endpoint, and thus an opaque access token will be issued which can be used later by the client to request user profile such as user ID, name, email, etc., from the OIDC userinfo endpoint.

In any Logto SDK, you can obtain such token if you call getAccessToken() or directly request OIDC token endpoint without specifying the resource parameter.

Be noted that this opaque access token isn't suitable for your own API resource requests, since there's no way to verify it without requesting the OIDC server.

In summary#

OIDC resources define specific data or services a client application wants to access on behalf of the user, with JWT access tokens serving as the secure means for this access. The "aud" claim in JWT access tokens aligns with the resource indicator, aiding servers in verifying permissions upon client requests.

In Logto, the opaque access token is solely for fetching user profile information from the OIDC userinfo endpoint, while clients can request multiple access tokens, each dedicated to a specific resource.

We hope this blog post clears any doubts and connects the dots for you. Feel free to let us know your thoughts.