Custom JWT Authentication

Authentication and Authorization

The third-party JWT provider authenticates users and returns a JWT. App Services uses the JWT to identify your application's users and authorize their requests.

App Services is agnostic to the authentication methods used by the third-party provider. It 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 multi-factor authentication (MFA), provide specific credentials, or otherwise identify themselves.

How JWT Authentication Works

There are many resources online that dive into the intricacies of JWT authentication and the token structure. In the context of App Services, the following diagram provides the process flow of a user logging on to a Device Sync app. The steps below the diagram provide details.

click to enlarge

JWT authentication with App Services follows these general steps:

1. The user logs on to the third-party authentication provider by whatever means the provider requires.

2. If authentication succeeds, the provider returns a JWT to the client app.

3. The client app logs on to the App Services app, providing the JWT credential.

4. App Services parses and decodes the JWT.

5. If you manually provided signing keys in App Services, App Services checks if the signing key in the JWT matches one of the signing keys you specified. If so, the user is authenticated.

6. If you configured App Services to use a JSON Web Key (JWK) URI, App Services passes the JWT and public key to the third-party provider's JWK API.

   1. The provider decodes and verifies the signature and returns a JWK.

   2. App Services checks if the signature in the JWK matches the JWT's signature. If so, the user is authenticated.

Configuration

You configure Custom JWT Authentication from the UI or with the CLI. Choose your preferred method below.

{
  "custom-token": {
    "name": "custom-token",
    "type": "custom-token",
    "config": {
      "audience": "<JWT Audience>",
      "requireAnyAudience": <boolean>,
      "signingAlgorithm": "<JWT Signing Algorithm>",
      "useJWKURI": <boolean>,
      "jwkURI": "<JWK or JWKS URL>",
    },
    "secret_config": {
      "signingKeys": [
        "<Signing Key Secret Name>",
        ...
      ]
    },
    "metadata_fields": [
      {
        "required": <boolean>,
        "name": "<JWT Field Path>",
        "field_name": "<Metadata Field Name>",
      },
      ...
    ],
    "disabled": <boolean>
  }
}

Verification Method

The Verification Method field determines how App Services will validate the JWT returned from the JWT provider. You can configure App Services to validate the JWT by using the signing key(s) you provide, or to validate by using a JSON Web Key (JWK) URI issued by the third-party provider.

Manually Specify Signing Keys

You can configure your app to use one or more signing keys to validate the JWT. There are two settings you need to provide:

Field	Description
Signing Algorithm config.signingAlgorithm	The cryptographic method that the external system uses to sign the JWT. Custom authentication supports JWTs signed using either of the following algorithms: HS256 RS256
Signing Key secret_config.signingKeys	A list of up to three Secrets that each contain a signing key used by the third-party authentication system to sign JWTs. The key can only contain ASCII letters, numbers, underscores, and hyphens, and must be between 32 and 512 characters long. The following is a valid 256-bit signing key: 231a58b00632c9c4d8ac02b268ca4caf8dd48fd020e3dffa72666523d860988f Note If you are uncertain of what value to use, consider visiting a random key generator website, like keygen.io, and using one of the generated 256-bit values.

App Services UI

App Services CLI

1. Set the Signing Algorithm:

   

2. Create one or more signing keys to sign the JWT. To do this, provide a name for the key (which is solely for your reference later), and then specify a 256-bit signing key.

   

"config": {
  "signingAlgorithm": "<JWT Signing Algorithm>",
},
"secret_config": {
  "signingKeys": [
    "<Signing Key Secret Name>",
    ...
  ]
}

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 (JWKS) 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. The returned JWKS must include a kid header that specifies the Key ID of a key from the JWKS. The JWKS may specify up to three signing keys and must use the RS256 algorithm.

Note

JWK and JWKS are used synonymously in Atlas App Services.

There is only one value you need to provide:

• JWK URI, which is the third-party URL that hosts a JWK or JWKS service. When you choose this option, App Service automatically sets encryption to the required RS256 method.

App Services UI

App Services CLI

Specify the URL to the third-party JWKS endpoint:

"config": {
  "useJWKURI": <boolean>,
  "jwkURI": "<JWK or JWKS URL>"
}

Metadata Fields

Metadata Fields are additional data that describe each internal App Services user. App Services determines the value of each metadata field from the value of a field included in the third-party JWT. For example, if you set the name field of a user, then App Services will use that field in the JWT as the user's display name.

Note

App Services refreshes a user's metadata whenever they log in and exposes the fields in the data object of the user metadata.

Important

JWT and Metadata Field Character Limits

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 1 million characters, and the length of each metadata field to 4096 characters. If you exceed these limits, App Services logs an error and the ticket is not processed.

There are three values that you need to specify for each metadata field:

Field	Description
Required required	If true , the metadata field is required for all users associated with the provider. The JWT returned by the external system must have a value assigned to the field designated by Path.
Path name	The name of, or the path to, a field in the JWT that contains the value for the metadata field. To specify the path to a field in an embedded object, use dot notation. If the name of the field itself in the JWT contains a period (.) character, use a backslash (\) to escape the period. For example, if the name is http://example.com/id, use http://example\.com/id.
Field Name field_name	Optional. A name for the metadata field in the user object's data document that maps to the JWT Path. This field name must be less than 64 characters long. Default Value Rules If this field is not specified, the name defaults to the name of the JWT field that contains the value. If this field is not specified and the Path value uses dot notation, the default name will be the last part of the notation. For example, if you specify a path of location.primary.city, the default value for the name is city.

App Services UI

App Services CLI

To define a metadata field, click Add Field and specify the mapping between the metadata field in the JWT and its corresponding field name in the user object.

To define a metadata field in a Custom JWT authentication configuration file, add an entry for the field to the metadata_fields array. Each entry should be a document of the following form:

{
  required: <boolean>,
  name: "<field path>",
  field_name: "<metadata field name>"
}

Use a backslash (\) to escape period (.) characters in JWT keys.

For example, in this JSON object, you represent the "nested_key" in the path name as valid\.json\.key\.nested_key.

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

Example

An external authentication system returns JWTs that include additional information about each user in the user_data field:

(JWT JSON)
{
  "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, specify the following metadata fields in your App Services configuration:

Path	Field Name
user_data.name	name
user_data.aliases	aliases

The user object, will now include those fields:

(USER METADATA OBJECT)
{
  "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"
        ]
      },
    }
  ]
}

Audience

The Audience of a JWT specifies the intended recipient of the token. JWTs describe their audience in the aud claim. App Services expects aud to contain the App ID of the App for which the provider is configured. However, if the external authentication system JWT specifies a different aud value, then you can configure the provider to use that value instead.

App Services UI

App Services CLI

There are two fields you configure:

Field	Description
Audience	A single value or comma-separated list of values for the audience or audiences expected to be found in a client JWT.
Require	If you provide multiple audiences, you must specify how to handle them. Your options are: 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.

To set an audience, configure config.audience. There are two fields you configure:

Field	Description
audience	An array of strings specifying the audience or audiences expected to be found in a client JWT.
requireAnyAudience	Boolean. If false, the JWT must include all of the listed audiences. If true, the JWT must only include one or more of the listed audiences.

"config": {
  "audience": [
    "<JWT Audience>",
  ],
  "requireAnyAudience": <boolean>,
}

Using JWT Authentication

You can register new Custom JWT users and log them in using one of the Realm SDKs or an API service.