Custom JWT Authentication

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.

Configuration

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.

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.

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

{
  "aud": "myapp-abcde",
  "exp": 1516239022,
  "sub": "24601",
  "user_data": {
    "name": "Jean Valjean",
    "aliases": [
      "Monsieur Madeleine",
      "Ultime Fauchelevent",
      "Urbain Fabre"
    ]
  }
}

{
  "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>

{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "<JWK Key ID>"
}

{
  "aud": "<realm app id>"
  "sub": "<unique user id>",
  "exp": <NumericDate>,
  "iat": <NumericDate>,
  "nbf": <NumericDate>,
  ...
}

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

Firebase JWT Authentication

You can use the Firebase Authentication service to authenticate users into App Services apps as well as Firebase apps. Use App Services Custom JWT authentication to access App Services with Firebase credentials.

To set up Firebase Authentication as your Custom JWT provider in App Services:

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