Custom JWT Authentication
On this page
Overview
The Custom JWT authentication provider allows users to authenticate with an authentication system that is independent from MongoDB Realm. The external system must return a signed JSON Web Token that contains a unique ID value for the authenticated user.
Realm uses the JWT to identify your application's users and authenticate their requests but does not impose any restrictions on the external authentication system's requirements or authentication methods. For example, the system could require the user to perform two factor authentication, provide specific credentials, or otherwise identify themself.

Configuration
Audience
The Audience of a JWT specifies its intended recipient. JWTs
describe their audience in the aud
claim. By default, Realm expects
aud
to contain the App ID of the Realm app for which the provider
is configured.
If the external authentication system JWT specifies a different aud
value, then you can configure the provider to use that value instead.
Verification Method
The Verification Method configures how the provider determines which signing algorithm and signing keys the external authentication system must use to sign each JWT.
You can either manually specify signing keys or specify a JSON Web Key URI.
Manually Specify Signing Keys
You can manually configure the signing algorithm and specify one or more signing keys that the external authentication system may use to sign JWTs.
Field | Description |
---|---|
Signing Algorithm config.signingAlgorithm | The cryptographic method that the external system uses to sign the JWT. Custom authentication supports JWTs signed using any of the following algorithms:
![]() |
Signing Key secret_config.signingKeys | A list of the names of up to three Secrets that each contain a signing key used by the external authentication system to sign JWTs. Each signing key Secret must be a string with length between 32 and 512 characters. ![]() Warning A Signing Key is a secret key and anyone with the key can issue valid user credentials for your app. Ensure that it's never stored in a publicly accessible location, such as a git repository, message board, or in your code. |
Use a JWK URI
Some external authentication systems provide a JSON Web Key Set that describes the signing
algorithm and signing keys the system uses to sign JWTs. You can use the
JWKS to configure the provider instead of manually specifying the
signing algorithm and keys. When enabled, each token must include a
kid
header that specifies the Key ID of a key from the JWKS.
Field | Description |
---|---|
Use JWK URI config.useJWKURI | If true , configures Realm to use a signing algorithm and
signing keys defined in a JWK or
JWKS. The JWKS must be accessible at a
URL that you specify. |
JWK URI config.jwkURI | A URL that hosts a JWK or JWKS that describes the signing method
and signing keys the JWTs should use. The JWKS may specify up to
three signing keys and must use the ![]() |
Metadata Fields
Metadata Fields are additional data that describe each user.
Realm determines the value of each metadata field from the value of
some field included in the JWT from the external authentication system.
If you set the name
field of a user, then Realm will use that
field as the user's display name. Realm refreshes a user's metadata
whenever they log in and exposes the fields in the data
object of the
user object.
The length of a JWT token increases with the number of metadata fields in the token and the size of each field. Realm limits the length of a JWT token to 2048 characters. If you exceed this limit, Realm logs an error and the ticket is not processed.
Field | Description | ||||
---|---|---|---|---|---|
Required required | If true , the metadata field is required for all
users associated with the provider, i.e. the JWT returned by the external system must have a
value assigned to the field designated by Path. | ||||
Path name | The name of a field in the JWT that contains the value for the metadata field. To specify a field in an embedded object, use dot notation. Note Escaping periods in JWT keys Use a backslash (
You could represent the | ||||
Field Name field_name | Optional. A name for the field in the user object's |
An external authentication system returns JWTs that include
additional information about each user in the user_data
field:
{ "aud": "myapp-abcde", "exp": 1516239022, "sub": "24601", "user_data": { "name": "Jean Valjean", "aliases": [ "Monsieur Madeleine", "Ultime Fauchelevent", "Urbain Fabre" ] } }
To include the values from the user_data
field in each user's
user object, you could specify the following
metadata fields:
Path | Field Name |
---|---|
user_data.name | name |
user_data.aliases | aliases |
We can now access the mapped values directly from the user object, which would resemble the following for the given JWT:
{ "id": "59fdd02846244cdse5369ebf", "type": "normal", "data": { "name": "Jean Valjean", "aliases": [ "Monsieur Madeleine", "Ultime Fauchelevent", "Urbain Fabre" ] }, identities: [ { "id": "24601", "provider_type": "custom-token", "data": { "name": "Jean Valjean", "aliases": [ "Monsieur Madeleine", "Ultime Fauchelevent", "Urbain Fabre" ] }, } ] }
JSON Web Tokens
The external authentication system must return a JSON web token that uniquely identifies the authenticated user. JSON web tokens are an industry standard (see RFC 7519) for securely representing claims between two parties. A JWT is a string that consists of three parts: a header, a payload and a signature and has the following form:
<header>.<payload>.<signature>
JWT Header
The header portion of the JWT consists of a Base64UrlEncoded
document of the following form:
{ "alg": "HS256", "typ": "JWT", "kid": "<JWK Key ID>" }
Field | Description | ||||||
---|---|---|---|---|---|---|---|
Required. A string representing the hashing algorithm being used. Realm supports JWTs encoded with the following algorithms:
| |||||||
Required. The type of the token. Realm expects a JSON web token
so the value should be "JWT" . | |||||||
Optional. The Key ID of a specific key to use from a set of keys
in a JWK. You must include the kid header when you use
a JWK URL. |
JWT Payload
The payload portion of the JWT consists of a Base64UrlEncoded
document of the following form:
{ "aud": "<realm app id>" "sub": "<unique user id>", "exp": <NumericDate>, "iat": <NumericDate>, "nbf": <NumericDate>, ... }
Field | Description |
---|---|
Required. The audience of the token.
By default, Realm expects this value to be the App ID of your
Realm app. If your external authentication service
returns a different aud value, you should specify that value
instead. | |
Required. The subject of the token. The value should be a unique
ID for the authenticated user from your custom-built
authentication system. | |
Required. The Expiration date of the token. The value should be a NumericDate number indicating the time at which the token expires. Note Realm will not accept expired authentication tokens. | |
Optional. The "issued at" date of the token . The value
should be a NumericDate number that indicates the time after
which the token is considered valid. This field is functionally
identical to nbf . | |
Optional. The "not before" date of the token. The value should be
a NumericDate number that indicates the time before which the
token is considered invalid. This field is functionally identical
to iat . |
Realm maps certain values from the JWT the user object so that you can access them in your application:
- The required fields listed in this section map to the
User.identities.data
property for their Custom JWT provider identity. - The metadata fields listed in the Custom JWT provider configuration map to the
User.data
property. - Any optional fields not listed in the provider configuration are ignored and do not map to the user object.
JWT Signature
The signature portion of the JWT is a hash of the encoded
token header and payload. To form 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 of the header.
HMACSHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), signingKey )
Firebase JWT Authentication
You can use the Firebase Authentication service to authenticate users into Realm apps as well as Firebase apps. Use Realm Custom JWT authentication to access Realm services with Firebase credentials.
To set up Firebase Authentication as your Custom JWT provider in Realm:
Configure Firebase Authentication
Follow the official docs to set up Firebase Authentication for your project.
Configure Realm JWT Authentication
For more details, refer to the JWT authentication configuration documentation.
Log In to Realm Using Firebase JWT with Client SDK
Now that you've configured Realm to work with Firebase JWTs, you can log users in using Firebase and Realm client SDKs in languages supported by both.
- Log the user into Firebase. See the relevant Firebase SDK documentation.
- Retrieve the user's Firebase JWT. See the documentation on using a client Firebase SDK to get a user's JWT.
- Pass the Firebase JWT to a a Realm SDK Custom JWT authentication method. For more information how to use Realm SDKs to perform Custom JWT authentication, refer to Custom JWT Examples.
Examples
For code examples that demonstrate how to register and log in using Custom JWT authentication, see the documentation for the Realm SDKs:
Summary
- Custom JWT authentication allows you to identify your application's users via a JSON Web Token issued outside of Realm.
- Realm expects JWT audience values to be the App ID of the Realm app unless otherwise configured in the application.
- Realm can verify JWTs using either manually specified keys and signing algorithms or a JSON Web Key URI.
- You can pass custom user data in your JWT that Realm refreshes whenever the user refreshes their token.