Custom JWT

The Timbr REST API Service supports offline authentication using JWT tokens (Open ID). This authentication method allows custom applicationa nd authentication services like Keycloak and more to verify user identities using JWT tokens, even in multi-tenant environments.

To enable JWT token authentication with Timbr, follow these steps:

1. Set the environment variable ENABLE_TOKEN to true.
2. 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_DEFAULT_KEY	✔️	None	Public Key or Secret Password	A string representing the Public Key or Secret Password used for decryption with JWT_DEFAULT_ALGORITHM. In the case of a Public Key (e.g., for Keycloak), the public key should include the placeholders before (\n-----BEGIN PUBLIC KEY-----\n) and after (\n-----END PUBLIC KEY-----\n) the key itself.
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	For Keycloak, the audience is commonly the Client ID in a Keycloak realm. If this value is not set, the JWT will be decrypted without audience validation.
JWT_USE_EMAIL_OR_USER	✖️	email	email or username	Whether or not Timbr should use the email or the username value from the token to internally authenticate with Timbr.
JWT_TYPE	✖️	custom	custom or azure	Specify the type of JWT token to be used to with authenticating to Timbr. By default the value is custom so no change needed for this type of authentication.

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.

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>_KEY	✖️	None	Public Key or Secret Password	A string representing the Public Key or Secret Password used for decryption with JWT_<TENANT_ID>_ALGORITHM. In the case of a Public Key (e.g., for Keycloak), the public key should include the placeholders before (\n-----BEGIN PUBLIC KEY-----\n) and after (\n-----END PUBLIC KEY-----\n) the key itself.
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	For Keycloak, the audience is commonly the Client ID in a Keycloak realm. If this value is not set, the JWT will be decrypted without audience validation.
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.

Using JWT_USE_TENANT_USER Environment Variable Example

Consider 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