Custom JWT Authentication

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

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

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.

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

JWT Header

The header portion of the JWT consists of a Base64UrlEncoded document of the following form:

{
  "alg": "HS256",
  "typ": "JWT"
}

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

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
)