oauth 2.0oidc

What is Opaque token?

An opaque token is a random, unique string that is meaningless to the client but serves as a reference key to lookup authorization data in the server's database.

What is opaque token?

An opaque token is a random, unique string that is meaningless to the client but serves as a reference key to lookup authorization data in the server’s database.

Opaque tokens are usually generated using a Cryptographically secure pseudorandom number generator to ensure its unpredictability and security, and its format is determined by its issuer.

Here is an example of an opaque token:

M-oxIny1RfaFbmjMX54L8Pl-KQEPeQvF6awzjWFA3iq

What is the difference between JWT (JSON Web Token) and opaque token?

The main difference lies in how these tokens handle and validate authorization information:

An opaque token is a random string that contains no information itself. The server must query its backend database to retrieve any authorization data associated with this token. This makes opaque tokens completely dependent on the authorization server for validation and interpretation.

JWT is a self-contained token that carries all necessary information within itself.

Here is an example of a JWT, its a base64 encoded string:

eyJhbGciOiJIUzI1NiIs.eyJzdWIiOiIxMjM0NTY3O.SflKxwRJSMeKKF2QT4f

And it contains three parts separated by dots:

Header - Contains information about the type of token and the algorithm used for signing. For example, {"alg": "HS256", "typ": "JWT"}.
Payload - Contains claims—pieces of information about the user or the authorization, like user ID, expiration time, and scopes. Anyone can decode it to see the claims because it’s encoded but not encrypted.
Signature - Generated by combining the header, payload, and a secret key using the specified algorithm. This signature is used to verify the integrity of the token and ensure that it has not been tampered with.

This structure allows JWTs to be validated and used without querying a database.

For more detailed information about JWTs, please refer to JSON Web Token (JWT) .

And check out Opaque token vs JWT to learn more about their differences in more depth.

How to validate opaque token

In simple systems, opaque token validation is typically handled directly by the server, which queries the database using the opaque token as a key to retrieve the associated authorization information.

In multi-party systems introducing OAuth 2.0, multiple resource servers (see: Resource server ) may need to validate the same opaque token. OAuth 2.0 provides a standardized token introspection mechanism for this validation:

For detailed information about token introspection, please refer to Token introspection .

How are opaque tokens used in OIDC?

In the context of OIDC ( OpenID Connect (OIDC) ), opaque tokens serve specific purposes in different scenarios:

User profile retrieval

By default, when a client requests an access token without specifying a resource and includes the openid scope, the authorization server issues an opaque access token. This token is primarily used to retrieve user profile information from the OIDC /oidc/userinfo endpoint (see: Userinfo endpoint ).

Refresh token exchange

Refresh tokens (see: Refresh token ) are typically issued as opaque tokens since they are only exchanged between the client and the authorization server. When the current access token expires, the client can use the opaque refresh token to obtain a new access token without re-authenticating the user.

What are the pros and cons of opaque token?

Pros

Security: Opaque tokens are perfect for handling sensitive data like refresh tokens. Since the content is completely random and meaningless, even if someone intercepts the token, they cannot extract any useful information. This makes them especially valuable in high-security scenarios like banking transactions or handling sensitive user data.
Revocability: The server can immediately invalidate an opaque token at any time. This is particularly useful when you need to quickly remove user access. Unlike JWTs that remain valid until they expire, opaque tokens can be instantly revoked (see: Limitations of JWT ).
Size: Opaque tokens are typically much shorter than JWTs. This smaller size reduces network bandwidth usage and storage requirements. The benefit becomes particularly noticeable in systems that frequently transmit tokens, such as mobile applications or IoT devices.
Simplicity: The implementation of opaque tokens is straightforward. You generate a random string and store it with its associated data. There’s no need to handle complex encryption or signature verification like with JWTs. This simplicity makes them ideal for internal system authentication.

Cons

Stateful: Every opaque token requires storage on the server side. This creates additional complexity in distributed systems because token data must be synchronized across multiple servers. For example, if you have multiple authentication servers, they all need access to the same token database or cache system to validate tokens properly.
Performance: Token validation always requires a database lookup or API call. In high-traffic systems, these extra database queries can create performance bottlenecks. For instance, if your system handles thousands of requests per second, each requiring token validation, the additional database load becomes significant.
Interoperability: Different systems might implement opaque tokens in different ways. This can cause integration challenges when working with third-party services or different authorization servers. While standards like OAuth 2.0 token introspection help, you may still encounter compatibility issues when systems use different token formats or validation methods.