Opaque token: concept, purpose, way it works

Find out what the opaque token is and what purpose it has. Check how to enable such a token type in Authorization Control Plane (ACP) and how to use it.

Opaque tokens in a nutshell

The opaque token is a random unique string of characters issued by the authorization server. It is one of the possible formats that access tokens or refresh tokens can take. The opaque token does not pass any identifiable information on the user so it’s impossible for the resource server to make any authorization decisions based on the opaque token itself. The opaque contains an identifier to information stored on the authorization server. To validate the token and retrieve the information on the token and the user, the resource server calls the authorization server and requests the token introspection.

With opaque tokens, you can hide personally-identifiable information (PII), prevent credentials from being shared, and limit the request headers size (to avoid rejecting overloaded requests).

Opaque tokens vs structured tokens

Although OAuth defines no limitations to the token format, there are at least two token types around if you look at the token format:

  • Opaque token (passed by reference): The token itself has no meaning to the resource server unlike the metadata connected to the token (expiration date or scopes), which is crucial for making the authorization decision. To retrieve the required information from the opaque token, the resource server sends a request to the introspection endpoint of the authorization server. The opaque token serves as a reference to the user attributes and token metadata.

  • Structured token (passed by value): Its format is well-defined so the resource server can decode and verify the token without calling the authorization server. Such a token, for example JWT, contains enough data for the resource server to make its authorization decision.

Sample opaque token

atfqI-QW3HXqF1hkot1e6hJDIj4qHnwTEUXiGJFf09k.SRHhlx6wlDz5GZncAr99HfM7FUbDQlUg73MapL0TJ2I

Sample structured token

For an example of the structured token, see JWT example.

Enable opaque tokens in ACP

In ACP, you can choose the format for your access tokens by enabling either JSON Web Tokens (structured) or opaque tokens.

To use the opaque token format for your workspace,

  • Navigate to the workspace Settings and open the Tokens view. In the Access token type section, select OPAQUE and save your changes.

    Enabling opaque tokes in ACP

  • Navigate to your application in the workspace and open its Scopes view. Make sure that the Introspect tokens scope in the OAuth2 service is enabled.

    Introspect tokens