JSON Web Tokens (JWT) are encoded JSON objects that contain information which uniquely identifies the authenticated user, and is formatted in three parts containing: <header>.<payload>.<signature>.

Realm uses JWT to authenticate your users with an authentication system that is independent of MongoDB Realm (either external or custom).

The <header> format

The Base64UrlEncoded document <header> contains the alg (signing algorithm) and the typ (type of token, whose value should be JWT) fields. Extra fields and values are not allowed. Realm supports JWTs encoded using either the HS256 (HMAC with SHA256) or RS256 (RSA Signature with SHA-256) cryptographic algorithms.

Here is an example of <header> in JSON:

"alg": "HS256",
"typ": "JWT"

The <payload> format

The Base64UrlEncoded document <payload> contains the registered claims, or a set of predefined claims, which require the aud (audience), sub (subject), and exp (expiration date) token fields.

  • The value for aud field is typically your Realm App ID, or the Audience value you specify when enabling Custom Authentication in the Users > Providers tab of your Realm App:

  • The value for sub field is a unique user ID for the authenticated user from your custom-built or external authentication system.

  • The value for exp field should be a NumericDate number indicating the time at which the token expires. Realm does not accept any expired authentication tokens.

Here is an example of the required <payload> fields in JSON:

"aud": "<realm app id> / <audience value>"
"sub": "<unique user id>",
"exp": <NumericDate>,
"iat": <NumericDate>,
"nbf": <NumericDate>,

To specify additional fields and values, ensure these fields have been mapped to metadata fields in the provider configuration; otherwise the fields will be ignored in the JWT payload.

The <signature> format

<signature> is a hash of the encoded JWT token <header> and <payload>.

To create the signature, concatenate the encoded header and payload with a period “.” and sign the result with the Signing Key specified in the authentication provider configuration, using the hashing algorithm specified in the alg field in <header>. See the example below:

base64UrlEncode(header) + "." + base64UrlEncode(payload),

Adding more fields in the <header> of the JWT

You can add the additional fields to the <payload> instead of the <header>. If this is not possible, this request usually comes up because your external authentication system has already provided a non-editable JSON Web Key Set (JWKS). You can then provide the JWKS or a URL that hosts a JWK to configure the provider instead of manually specifying the signing algorithm and keys.

Verifying JWT formatting

Yes; navigate to the debugger in jwt.io. Omit any sensitive information inside the <payload> before generating the JWT, and paste the generated JWT in the encoded section. In the decoded section, the decoded information of the <header> and <payload> will appear.


Did this answer your question?