Custom JWT Authentication

On this page

Overview

Configuration
Audience
Verification Method
Metadata Fields
JSON Web Tokens
JWT Header
JWT Payload
JWT Signature
Examples
Walkthrough
Prerequisites
Procedure
Summary

Overview

The Custom JWT authentication provider allows users to authenticate with an authentication system that is independent from Atlas App Services. The external system must return a signed JSON Web Token that contains a unique ID value for the authenticated user.

App Services 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.

Diagram of Custom JWT authentication architecture.

Configuration

Audience

The Audience of a JWT specifies its intended recipient. JWTs describe their audience in the aud claim. By default, App Services expects aud to contain the App ID of the 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.

You can input a single audience or multiple audiences as a comma-separated list. If you add multiple audiences, a toggle appears containing the following options:

All of these audiences: the JWT must include every audience in the list.
Any one of these audiences: the JWT only needs to include one audience from the list.

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: `HS256` `RS256`
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.

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:

HS256
RS256

The Signing Algorithm configuration dropdown

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 App Services 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 `RS256` algorithm.

Metadata Fields

Metadata Fields are additional data that describe each user. App Services 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 App Services will use that field as the user's display name. App Services refreshes a user's metadata whenever they log in and exposes the fields in the data object of the user object.

Important

2048 Character Limit

The length of a JWT token increases with the number of metadata fields in the token and the size of each field. App Services limits the length of a JWT token to 2048 characters. If you exceed this limit, App Services 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 (\) to escape period (.) characters in JWT keys. Take this JSON object for example:

{ "valid.json.key": {
    "nested_key": "val"
  }
}

You could represent the "nested_key" in the path name as valid\.json\.key.nested_key.

Field Name

field_name

Optional. A name for the field in the user object's data document that exposes the metadata field value. If not specified, this defaults to the same name as the JWT field that contains the value. The metadata field name may contain a maximum of 64 characters.

Example

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

alg

Required. A string representing the hashing algorithm being used.

App Services supports JWTs encoded with the following algorithms:

Algorithm	Value
HMAC SHA-256	`"HS256"`
RSA Signature SHA-256	`"RS256"`

typ

Required. The type of the token. App Services expects a JSON web token so the value should be "JWT".

kid

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
`aud`	Required. The audience of the token. By default, App Services expects this value to be the App ID of your App. If your external authentication service returns a different `aud` value, you should specify that value instead.
`sub`	Required. The subject of the token. The value should be a unique ID for the authenticated user from your custom-built authentication system.
`exp`	Required. The Expiration date of the token. The value should be a NumericDate number indicating the time at which the token expires. Note App Services will not accept expired authentication tokens.
`iat`	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`.
`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`.

Note

App Services 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
)

Examples

For code examples that demonstrate how to register and log in using Custom JWT authentication, see the documentation for the Realm SDKs:

Walkthrough

In this walkthrough, you will implement Custom JWT Authentication for your App Services App. You will learn how to:

Enable JWT Authentication
Use a third-party JWT provider to generate a valid token
Authenticate against the backend from a client application

Prerequisites

You can use any App Services App for this tutorial. If you do not have a test app to use, you can create an app or use one of the Template Apps.

Procedure

This procedure is divided into three logical steps:

Create a JWT token
Enable and configure JWT Authentication in App Services
Add authentication code to your client app

Create a JWT Token

For this tutorial, we will use a third-party website, jwt.io, to generate a JWT token.

Go to jwt.io. Scroll down until you see the Encoded and Decoded headers. In the Decoded column, you will see three sections that comprise a JWT token: Header, Payload, and Verify Signature areas, each of which is explained in the next sections.

Header

The header of a JWT informs consuming applications what algorithm was used to encode the token. The default, which we will use for this tutorial, is HS256.

Note

For more information on JWT algorithms, see JSON Web Token (JWT) Signing Algorithms Overview. App Services supports HS256 and RS256.

Payload

The Payload section contains the information that we need to configure for our App Services-specific needs. By default, three fields are included: sub, name, and iat. We will use these three, plus two more fields. The following table explains each field and the value expected:

Field	Description	Value
`sub`	The subject of the jwt, which you set according to your business needs. For more information, see RFC 7519 4.1.2.	<your email or any other unique value>
`name`	The name of the user to whom this JWT is assigned. If specified, App Services uses this value as the user's display name. Optional.	<your name>
`iat`	"Issued At" is a Unix epoch timestamp of when the token was issued.	The current date-time in seconds since Unix epoch.
`exp`	The date-time when this token expires.	A specific time defined in seconds since January 1, 1970 (i.e. the Unix epoch). Before this time, the JWT is valid. After this time, the JWT is expired. The Custom JWT provider rejects any login attempt that includes an expired JWT.
`aud`	The audience (consumer) of the token.	Your App Services App ID, which you can find in the App Services UI. If applicable, you can input multiple App IDs as a comma-separated list. When inputting multiple, you can specify whether the JWT requires all or any one of the listed audiences.

For this tutorial, we have created a JWT for a user named "Caleb". The token was issued at the time of writing and will expire in exactly 1 year, and is intended to be used by an App Services with an ID of "boiboi-cul8r". Our completed JSON payload looks like this:

{
   "sub": "1234567890",
   "name": "Caleb",
   "iat": 1617313420,
   "exp": 1648849420,
   "aud": "boiboi-cul8r"
}

Verify Signature

The final step in creating the JWT is to add a 256-bit secret with which the token is encoded. In this last section, find the field with the placeholder text of "your-256-bit-secret". Paste in any 256-bit string value into this field. If you are uncertain what value to use, consider visiting a random key generator website, like keygen.io, and copy one of the 256-bit values that has been generated.

Important

The key you use must only contain ASCII letters, numbers, underscores, and hyphens, and must be between 32 and 512 characters long.

Note

Keep track of this secret, as you will need it in the next section when we configure App Services authentication.

After pasting in your key, check the secret base64 encoded check box.

At this point, you have generated a JWT key that can be used with — and only with — the App you specified. Copy this key from the Encoded box and temporarily save it in a text document. Your JWT will be 3 sections of values, separated by periods, and looks something like the following (your token will not match this!):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9. ⤶
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkNhbGViIiwiaWF0IjoxNjE3MzEzNDIwLCJle ⤶
HAiOjE2NDg4NDk0MjAsImF1ZCI6ImJvaWJvaS1jeWFsOHIifQ. ⤶
GaIE4e6mGxlIBNnz4FcheFBUmxd25GK-rfOfF6F85rY

Enable JWT Authentication in Your App

If you are not currently logged in to App Services do so now and navigate to the App that you specified when generating the JWT in the previous section.

In the left-hand navigation, under Data Access, select Authentication.
Select the Authentication Providers tab.
Near the bottom of the list of providers, select Custom JWT Authentication.

Use the following table to set the properties on this page:

Field	Value
Provider Enabled	Select to enable
Verification Method	`Manually specify signing keys`
Signing Algorithm	`HS256`
Signing Key (Secret Name)	Provide a name that will have some meaning to you (for example, "newKey"), and then click the box that appears immediately below the name that reads "Create <key name>". In the resulting Signing Key text box, paste in the 256-bit key that you used when generating the JWT in the previous section. Do not click the "Add Signing Key" button. 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.
Metadata Fields (Optional)	Leave blank
Audience (Optional)	Leave blank.

When you have set all of the values, click Save. If you are prompted at the top of the screen to do so, review and deploy your changes.

Update Your Client to Use JWT Authentication

The final step in this tutorial is to update your client application to use JWT authentication. The a Realm SDKs make this process straightforward, and while each language has its own specific implementation, the pattern they each use is the same: pass the generated token to a login call. For code examples that demonstrate 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 App Services.
App Services expects JWT audience values to be the App ID of the App unless otherwise configured in the application.
App Services 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 App Services refreshes whenever the user refreshes their token.

← Custom Function Authentication Firebase JWT Authentication (Custom JWT) →