JWT Authorization Schema #

Starting from UB@5.24.13 UnityBase support authorization by JWT token in Authorization: Bearer jwt_token header.

Token is verified using public key / secret either JSON Web Key Set (preferred) or file with publicKeyOrSecret.

If token is valid and match all configured restrictions (issuer, audience, subject etc.) username is extracted from token payload (key what specified in usernameClaim) and used to create a user session (or retrieve an existed session from globalCache).

Configuring #

@unitybase/ub model adds a partial config with JWT settings. Minimal set of environment variables to enable JWT authorization are:

UB_USE_JWT_AUTH=true
UB_JWT_JWKS_URL=https://jwks.url.of.jwt.provider

Most identity providers implements a JSON Web Key Set (JWKS) endpoint, and this is preferred way to get public keys for verification A well known URLs are

• Azure: https://login.microsoftonline.com/common/discovery/v2.0/keys
• Keycloak: https://Keycloak.server.host/auth/realms/{your-realm}/protocol/openid-connect/certs

In case JWKS endpoint is not available JWSK json can be stored in file /var/opt/unitybase/shared/jwks.json

For symmetric keys (not recommended) key can be stored in file from UB_JWT_KEY_FILE env variable or directly in env variable JWT_SECRET

A full partial:

{
  "security": {
    //#ifdef(%UB_USE_JWT_AUTH||false%=true)
    "jwtAuthorization": {
      "enabled": true,
      // reserved "headerName": "Authorization", // HTTP header to look into to get a JWT token. Default is "Authorization". Value is RESERVED for future, current implementation expect only `Authorization: Bearer token_here`
      "usernameClaim": "%UB_JWT_USERNAME_CLAIM||sub%", // a claim to use as a username to sign in. Default is "sub"
      "verification": {
        "signature": {
          "JWKSUrl": "%UB_JWT_JWKS_URL%", // https endpoint to load a [JSON Web Key Set](https://auth0.com/docs/tokens/json-web-tokens/json-web-key-sets). If not set public key must be defined either in JWKSFilePath or
          // reserved "JWKSCacheTTLSec": 0, // Cache TTL in seconds for data loaded from https JWKS endpoint
          "JWKSFilePath": "%UB_JWT_JWKS_FILE||/var/opt/unitybase/shared/jwks.json%",           // if JWKSUrl is not specified JWK Set can be defined in file
          "keyFilePath": "%UB_JWT_KEY_FILE%", // if neither `JWKSUrl` nor `JWKSFilePath` are specified - use a PEM-encoded key file in PKIX, PKCS #1, PKCS #8 or SEC 1 format OR file with symmetric `secret` (not recommended)
          "HS256Secret": "%JWT_SECRET%" // symmetric key secret
        },
        "options": {
          "algorithms": %UB_JWT_ALGO||[]%, // (optional) List of strings with the names of the allowed algorithms. For instance, `["HS256", "HS384"]`. If not specified a defaults will be used based on the type of key provided
          "audience": "%UB_JWT_AUDIENCE%", // (optional) if you want to check audience (aud), provide a value here. The audience can be checked against a string, a regular expression or a list of strings and/or regular expressions. Eg: "urn:foo", /urn:f[o]{2}/, [/urn:f[o]{2}/, "urn:bar"]
          "issuer": "%UB_JWT_ISSUER%", // issuer (optional): string or array of strings of valid values for the iss field
          "ignoreExpiration": %UB_JWT_IGNORE_EXPIRATION||false%, // if `true` do not validate the expiration (exp) of the token
          "ignoreNotBefore": %UB_JWT_IGNORE_NOT_BEFORE||false%, // if `true` do not validate the not before (nbf) of the token
          "subject": "%UB_JWT_SUBJECT%", // (optional) if you want to check subject (`sub`), provide a value here
          "clockTolerance": %UB_JWT_CLOCK_TOLERANCE||0%, // number of seconds to tolerate when checking the `nbf` and `exp` claims, to deal with small clock differences among different servers,
          "maxAge": %UB_JWT_MAX_AGE||0%, // the maximum allowed age (in seconds) for tokens to still be valid. Default is 0 - do not verify and ralay on exp
          "clockTimestamp":  %UB_JWT_CLOCK_TIMESTAMP||0%, // the time in seconds that should be used as the current time for all necessary comparisons instead of current host time
          "nonce": "%UB_JWT_NONCE%" // if you want to check `nonce` claim, provide a string value here. It is used on Open ID for the ID Tokens. ([Open ID implementation notes](https://openid.net/specs/openid-connect-core-1_0.html#NonceNotes))
        }
      },
      // reserved
//      "autoSignUp": {
//        "enable": false,
//        // auto-create users if they are not already matched. Default is false.
//        "emailClaim": null,
//        // a claim to use as an email to auto-create users
//        "rolesClaim": null,
//        // a claim with array of user roles
//        "rolesMapping": {
//          "roleFromJwtRolesClaim": "roleFrom_uba_role"
//        }
//      }
    }
  }