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.

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.

231a58b00632c9c4d8ac02b268ca4caf8dd48fd020e3dffa72666523d860988f

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

(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"
        ]
      },
    }
  ]
}

Using JWT Authentication

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