Keycloak Configuration
The ORT Server uses Keycloak for authentication and for user management. To ensure that the ORT Server can be used with a Keycloak instance, the following configuration steps are required.
The authentication flows used in this document are officially supported by the ORT Server. There is no guarantee that other authentication flows will work correctly, and they are not tested. If you need support for an authentication flow that is not listed here, please open an issue.
Clients
It is recommended to create the following clients in Keycloak. While a single client could be used for all purposes, separating clients allows a more flexible and secure configuration. An example for this configuration can be seen in the Docker Compose setup.
ORT Server Backend
This client is used for authentication by the ORT Server backend to access the Keycloak Admin API. It is recommended to use the "Service account roles" flow in Keycloak which corresponds to the "Client credentials" flow in OAuth2. This allows the ORT Server to authenticate with Keycloak without the need for a user account.
- Default client ID:
ort-server-backend - Client authentication: Enabled
- Authentication flow: Service account roles
- Client scopes: Default
- Service account roles:
default-roles-<realm-name>,admin
Required configuration for the core application:
| Environment variable | Description |
|---|---|
KEYCLOAK_BASE_URL | The base URL of the Keycloak instance. |
KEYCLOAK_REALM | The Keycloak realm to use. |
KEYCLOAK_CLIENT_ID | The client ID of this client. |
KEYCLOAK_API_USER | Set to an empty string to use the service account instead of a user account. |
KEYCLOAK_API_PASSWORD (secret keycloak.apiSecret) | The client secret of this client. |
Alternatively, the client can be configured to use the "Direct access grants" flow, which corresponds to the "Resource owner password credentials" flow in OAuth2.
This allows the ORT Server to authenticate with Keycloak using a user account, but requires the user to have the admin role.
For this, the KEYCLOAK_API_USER must be set to the username instead of an empty string, and the KEYCLOAK_API_PASSWORD must be set to the password of the user.
ORT Server API
This client is not used for authentication but for the audience claim in the access tokens issued by Keycloak. The ORT Server API validates that the audience claim in the access token matches the client ID of this client.
- Default client ID:
ort-server-api - Client authentication: Enabled
- Authentication flow: None
- Client scopes: None
Required configuration for the core application:
| Environment variable | Description |
|---|---|
JWT_ISSUER | The expected issuer claim in the access tokens issued by Keycloak. This is usually the base URL of the Keycloak instance followed by /realms/<realm-name>. |
JWT_URI | The URI where Keycloak exposes the public keys for token validation. This is usually the base URL of the Keycloak instance followed by /realms/<realm-name>/protocol/openid-connect/certs. |
JWT_AUDIENCE | The expected audience claim in the access tokens issued by Keycloak. This must be set to the client ID of this client. |
JWT_REALM | The Keycloak realm to use. This is used for token validation and must match the realm used in the KEYCLOAK_REALM variable. |
Client scope
It is recommended to create a client scope ort-server-api-access to easily include the correct audience claim in the access tokens issued by Keycloak for other clients.
The client scope needs the following protocol mapper:
- Mapper type: Audience
- Included client audience:
ort-server-api - Add to access token: On
ORT Server UI
This client is used for authentication by the ORT Server UI. Currently, the UI only supports the "Standard flow" which corresponds to the "Authorization code" flow in OAuth2.
- Default client ID:
ort-server-ui - Client authentication: Disabled
- Authentication flow: Standard flow
- PKCE method: S256
- Client scopes:
basic,email,profile,ort-server-api-access - Valid redirect URIs: The URL where the UI is hosted followed by
/*, for examplehttp://localhost:8082/*. - Web origins: Use
+to allow all valid redirect URIs.
The remaining default scopes are not required and can be removed to minimize the token size.
Required configuration for the ui application:
| Environment variable | Description |
|---|---|
UI_AUTHORITY | The URL of the Keycloak realm to use for authentication. This is usually the base URL of the Keycloak instance followed by /realms/<realm-name>. |
UI_CLIENT_ID | The client ID of this client. |
ORT Server CLI
This client is used for authentication by the ORT Server CLI. Currently, the CLI only supports the "Direct access grants" flow which corresponds to the "Resource owner password credentials" flow in OAuth2.
- Default client ID:
ort-server-cli - Client authentication: Disabled
- Authentication flow: Direct access grants
- Client scopes:
basic,email,profile,ort-server-api-access,offline_access
The remaining default scopes are not required and can be removed to minimize the token size.
Required configuration for the core application:
| Environment variable | Description |
|---|---|
CLI_KEYCLOAK_BASE_URL | The base URL of the Keycloak instance. |
CLI_KEYCLOAK_REALM | The Keycloak realm to use. |
CLI_KEYCLOAK_CLIENT_ID | The client ID of this client. |
With this configuration, the CLI can auto-detect the necessary information to authenticate with Keycloak via the API.
Additional clients
If additional applications need to authenticate with Keycloak to access the ORT Server API, it is recommended to create separate clients for each application and include the ort-server-api-access client scope to ensure that the correct audience claim is included in the access tokens issued by Keycloak.
For testing purposes, it is also possible to use the ort-server-cli client, as it uses the "Direct access grants" flow which allows authentication with a user account.
Token lifespan
To configure the lifespan of access and refresh tokens, or how long an offline token is valid, see the following sections of the Keycloak documentation: