Azure JWT
The Timbr REST API Service supports offline authentication using JWT tokens (Open ID). This authentication method allows Azure AD, Microsoft Identity Platform and OAuth 2.0 Open ID Connect (OIDC) to verify user identities using JWT tokens, even in multi-tenant environments.
To enable JWT token authentication with Timbr, follow these steps:
- Set the environment variable
ENABLE_TOKEN
totrue
. - Set the environment variable
JWT_TYPE
toazure
. - Configure other environment variables outlined in the next section.
Environment Variables
Please note the following requirements for environment variables:
- All environment variables must be in uppercase.
The following environment variables can be set and serve as default values for the Timbr API Service:
Environment Variable | Required | Default Value | Possible Values | Description |
---|---|---|---|---|
ENABLE_TOKEN | ✔️ | false | false or true | This value must be set to true to enable JWT authentication in Timbr. |
JWT_TYPE | ✔️ | custom | custom or azure | This value must be set to azure in order to enable JWT authentication with Azure in Timbr. |
JWT_DEFAULT_ALGORITHM | ✖️ | RS246 | HS256 , RSA-OAEP , RS256 , AES | RS246 or RSA-OAEP should be used with a Public Key, while HS256 (hmac) or AES should be used with a Secret Password. You can specify multiple algorithms by separating them with commas, for example, RS246,RSA-OAEP , to use both algorithms in the decryption process. |
JWT_DEFAULT_AUDIENCE | ✖️ | None | string | The audience is commonly the Client ID. If this value is not set, the JWT will be decrypted without audience validation. This can also be set through using the x-jwt-client-id header in the request |
JWT_USE_EMAIL_OR_USER | ✖️ | upn | string | The key storing the value in the JWT token with information about the username or email to be authernticated in Timbr. |
JWT_ISSUER | ✖️ | None | string | The default value for the issuer of the JWT token, can also be passed as a request header for multi-tenant environments. The issuer value is a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components. |
Request Headers
Please note the following requirements for request headers:
- All headers must be in lowercase.
Header Key | Required | Header Value | Description |
---|---|---|---|
x-jwt-token | ✔️ | string | The access token of the JWT. |
x-jwt-tenant-id | ✖️ | string | The tenant ID value used by the JWT_<TENANT_ID>... environment variables. |
x-jwt-issuer | ✖️ | string | Issuer identifier for the Issuer of the token. The issuer value is a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components. |
x-jwt-client-id | ✖️ | string | The audience for the JWT. Audience(s) that this ID Token is intended for. It MUST contain the OAuth 2.0 client_id of the Relying Party as an audience value. It MAY also contain identifiers for other audiences. In the general case, the aud value is an array of case sensitive strings. In the common special case when there is one audience, the aud value MAY be a single case sensitive string. |
x-jwt-nonce | ✖️ | string | If present in the JWT, Clients MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authentication request. The nonce value is a case sensitive string. |
Using JWT in Multi-tenant Environments
In a multi-tenant environment, you can set specific credentials for different realms by defining environment variables specific to each tenant. Replace <TENANT_ID>
with an alphanumeric tenant identifier. These settings take precedence over the JWT_DEFAULT...
values when decrypting the JWT access token.
Environment Variable | Required | Default Value | Possible Values | Description |
---|---|---|---|---|
JWT_<TENANT_ID>_ALGORITHM | ✖️ | RS246 | HS256 , RSA-OAEP , RS256 , AES | RS246 or RSA-OAEP should be used with a Public Key, while HS256 (hmac) or AES should be used with a Secret Password. You can specify multiple algorithms by separating them with commas, for example, RS246,RSA-OAEP , to use both algorithms in the decryption process. |
JWT_<TENANT_ID>_AUDIENCE | ✖️ | None | string | The audience is commonly the Client ID. If this value is not set, the JWT will be decrypted without audience validation. This can also be set through using the x-jwt-client-id header in the request |
JWT_USE_TENANT_USER | ✖️ | False | False or True | When set to True , the username or email will have a prefix of the tenant id (as specified by the x-jwt-tenant-id header in the request) and will be authenticated as <tenant id>/<username or email> according to the value specified in the environment variable JWT_USE_EMAIL_OR_USER . |
JWT_USE_TENANT_USER
Environment Variable ExampleConsider the following scenario:
- An incoming request with a x-jwt-tenant-id header containing the value
tenant-5
. - A JWT token of the username
bob
.
In this scenario, when the following environment variables are set:
- JWT_USE_EMAIL_OR_USER environment variable set to
username
. - JWT_USE_TENANT_USER environment variable set to
True
.
(Assuming the other required environment variables are also set)
Timbr will authenticate the user with the username tenant-5/bob