What is an opaque token?

Question

And what does it mean that they are in a "proprietary format"? I am reading about JWT refresh tokens and they are opaque tokens, but I don't understand the term.

Answer 1

A JWT has readable content, as you can see for example on https://jwt.io/. Everyone can decode the token and read the information in it. The format is documented in RFC 7519.

An opaque token on the other hand has a format that is not intended to be read by you. Only the issuer knows the format.

The meaning of the word already gives a hint:

opaque /ə(ʊ)ˈpeɪk/ adjective

not able to be seen through; not transparent.

Here's a quote from https://auth0.com/docs/tokens:

Opaque tokens: Tokens in a proprietary format that typically contain some identifier to information in a server’s persistent storage. To validate an opaque token, the recipient of the token needs to call the server that issued the token.

A "opaque JWT refresh token" is a contradiction as per definition above. What actually is meant here is, that in some JWT frameworks only the authentication token is a JWT, but as refresh token they use opaque tokens.

Answer 2

Here, the term "opaque" means the string (that serves as token) is like a reference (in OOPs), or pointer (in C), or foreign keys (in relational DBs). i.e. You need an external content to resolve it.

Simple versus Composite:

The string is a "simple" string, as opposed to JWS, where is "composite"; It has parts "inside" it.

Inside versus Outside:

You can extract a payload (with claims, etc) out of it without referring to an external server or storage, "outside" this string.

Since an opaque token is a simple string it is just a reference, hence, naturally, its format is entirely arbitrarily determined by the server that issues it (hence the term "proprietary format"). The token string is determined at the time of creation of the underlying (referred-to) content, i.e. when it is paired (associated) with the contents that this token (as the reference or foreign key) refers to.