To use an external identity provider (IdP), ensure it supports the OIDC protocol, including the OIDC Discovery extension, and configure it to provide valid RS256 ID tokens.
Set up the external identity provider by creating two clients (also called
Applications in Auth0 or App Registrations in Microsoft Entra) named
tenzir-app
and tenzir-cli
.
The tenzir-app
client is used for logging into the Tenzir Platform in the web
browser.
- The Authorization Code flow must be enabled.
- The allowed redirect URLs must include
https://app.platform.example/login/oauth/callback
. - The client secret should be noted down so it can be added to the configuration of the Tenzir Platform in the next step.
The tenzir-cli
client is used to authenticate with the tenzir-platform
CLI.
- The Device Code flow must be enabled.
- The identity provider must either return an
id_token
for the device code flow, or anaccess_token
in JWT format.
You may want to to run CLI commands in environments where no user is available to perform the device code authorization flow, for example when running CLI commands as part of a CI job.
In this case, you can set up another client with the Client Credentials flow
enabled. The access_token
obtained from this client must be in JWT format. The
CLI will automatically attempt to use the client credentials flow if
the TENZIR_PLATFORM_CLI_CLIENT_SECRET
environment variable is set. You can
also force the use of the client credentials flow by using the
tenzir-platform auth login --non-interactive
option.
You must provide the following environment variables for the OIDC provider configuration used for logging into the platform:
TENZIR_PLATFORM_OIDC_PROVIDER_NAME=example-idpTENZIR_PLATFORM_OIDC_PROVIDER_ISSUER_URL=https://my.idp.example
TENZIR_PLATFORM_OIDC_CLI_CLIENT_ID=tenzir-cli
TENZIR_PLATFORM_OIDC_APP_CLIENT_ID=tenzir-appTENZIR_PLATFORM_OIDC_APP_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
You must provide the following environment variable containing a JSON object with the OIDC issuer and audiences that should be accepted by the platform.
TENZIR_PLATFORM_OIDC_TRUSTED_AUDIENCES='{"https://my.idp.example": ["tenzir-cli", "tenzir-app"]}'
You must configure the set of admin
users in your platform instance. An admin
user is a user who is permitted to run the tenzir-platform admin
CLI command.
The TENZIR_PLATFORM_OIDC_ADMIN_RULES
setting contains a JSON list of access
rules that determine who is considered an admin for this platform instance. If
any of the provided rules match, the user is considered to be an admin. The
example rule grants admin access to all users with a valid and signed id_token
containing the fields {"tenzir/org": "TenzirPlatformAdmins"}
.
TENZIR_PLATFORM_OIDC_ADMIN_RULES='[{"organization_claim": "tenzir/org", "organization": "TenzirPlatformAdmins", "auth_fn": "auth_organization"}]'
See the documentation on Access Rules
for more information about the possible types of rules and their syntax. Use the
tenzir-platform tools
subcommand of the CLI to generate valid JSON objects that
you can enter here.
Keycloak
Section titled “Keycloak”This section explains how to configure Keycloak as an external Identity Provider for use with the Tenzir Platform.
We assume that you already have a Keycloak instance up and running that is reachable with a browser. We provide an example stack of the Tenzir Platform with a bundled Keycloak instance here. The remainder of this section assumes you’re running this example stack, but the setup is the same for any other Keycloak instance.
Setting up the Keycloak Instance
Section titled “Setting up the Keycloak Instance”Admin Login
Section titled “Admin Login”Navigate to the Keycloak instance and log in as a user with admin permissions.
If you use the bundled Keycloak instance, the initial username is admin
and password is changeme
.
Remember to change the default password after logging in for the first time, and to set up 2-factor authentication for your admin user.
Create a new tenzir
realm (optional)
Section titled “Create a new tenzir realm (optional)”Keycloak defaults to the master
realm and the bundled Docker Compose
stack is configured to use this realm.
If you want to use a different realm, or already have an existing one,
update the TENZIR_PLATFORM_OIDC_ISSUER_URL
variable to point to the
new realm instead.
Create a Client for the App
Section titled “Create a Client for the App”Use the Add Client
button in the Clients
menu on the left. The new
client should be configured as follows:
Under General settings, set the client type to OpenID Connect and the
client id to tenzir-app
. If you use a different client id,
remember to update the TENZIR_PLATFORM_OIDC_PROVIDER_CLIENT_ID
variable
in your Tenzir Platform configuration accordingly.
Under Capability config, enable client authentication and the Standard flow access method.
Under Login settings, enter a redirect URL that points to ${TENZIR_PLATFORM_DOMAIN}/login/oauth/callback
,
where TENZIR_PLATFORM_DOMAIN
is the domain that is configured in your Tenzir Platform configuration.
For example, if the app is running under https://tenzir-app.example.org
then this should be
https://tenzir-app.example.org/login/oauth/callback
.
Finally, in the client view, go to the Credentials tab and copy the value of
the generated client secret. This must be added to the Tenzir Platform configuration
under TENZIR_PLATFORM_OIDC_PROVIDER_CLIENT_SECRET
.
Create a Client for the CLI
Section titled “Create a Client for the CLI”In order to use the tenzir-platform
CLI we need to set up an additional
client that supports device code authentication. (It is possible but not
recommended to use the same client for both Tenzir UI and Tenzir Platform CLI)
To do this, proceed exactly as above, but use tenzir-cli
as
the client id and under Capability config disable the Client authentication
setting and enable the OAuth 2.0 Device Authorization Grant authentication flow.
Microsoft Entra Identity
Section titled “Microsoft Entra Identity”To use Microsoft Entra Identity as an OIDC provider, you need to create two App registrations in Entra ID and configure them to use with the Tenzir UI and the Tenzir Platform CLI.
Follow these steps to create the required resources:
- Navigate to
portal.azure.com
and open the page for “Microsoft Entra ID”.
- Open the “App registrations” sub page.
- Create a new registration named
Tenzir Platform CLI
.
- Enable the public client flows for this app.
- Create a second registration named
Tenzir UI
.
- For this registration, open “Certificates & Secrets”.
- Create a new secret and give it a descriptive name.
- Make a local copy of the secret value.
- Copy the client id to your local machine.
- Copy the issuer url to your local machine.
Now you can supply the created resources and values to the stack by setting
editing the .env
file in your compose folder:
TENZIR_PLATFORM_OIDC_PROVIDER_NAME="Entra ID"
# The client id of the registration created in step 3.TENZIR_PLATFORM_OIDC_CLI_CLIENT_ID=082a9391-b645-4278-a16e-3cf54fb1bcf0
# The client id and secret created in steps 8 and 9.TENZIR_PLATFORM_OIDC_APP_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxTENZIR_PLATFORM_OIDC_APP_CLIENT_ID=d8ea5612-6745-47bc-b9fe-5024b1ca18fe
# The issuer url copied in step 10.TENZIR_PLATFORM_OIDC_PROVIDER_ISSUER_URL=https://login.microsoftonline.com/40431729-d276-4582-abb4-01e21c8b58fe/v2.0TENZIR_PLATFORM_OIDC_TRUSTED_AUDIENCES='{"issuer": "https://login.microsoftonline.com/40431729-d276-4582-abb4-01e21c8b58fe/v2.0","audiences": ["d8ea5612-6745-47bc-b9fe-5024b1ca18fe", "082a9391-b645-4278-a16e-3cf54fb1bcf0"]}'
Now you can restart your Tenzir Platform stack and you will be redirected to a Microsoft login page when you next login to the Tenzir UI.
Advanced Topics
Section titled “Advanced Topics”Custom Scopes
Section titled “Custom Scopes”By default, the Tenzir Platform requests the profile email openid offline_access
scopes
when logging in. To adjust this, set the PUBLIC_OIDC_SCOPES
environment variable
to a space-separated list of scope names.
Profile Pictures
Section titled “Profile Pictures”To include custom profile pictures, include a picture
claim in the returned
ID token containing an URL to the image file.
The Tenzir Platform will read that claim and use it as the profile picture in the top right corner of user interface, or fall back to a default image if the claim is not present.
Refresh Tokens
Section titled “Refresh Tokens”The Tenzir Platform supports the use of refresh tokens and will by default request
the offline_access
scope to automatically refresh sessions after the initial
id token has expired. To this end, the offline_access
scope is requested by
default.
Unfortunately, the OIDC spec is ambiguous on the precise semantics of
the offline_access
scope, and Keycloak’s interpretation is different
from most other OIDC providers: It always includes refresh tokens by default,
and adds additional permissions to the token when the offline_access
scope
is requested.
Therefore, some organizations forbid the use of tokens with offline_access
permissions for security reasons. In that case, add an environment variable
PUBLIC_OIDC_SCOPES=profile email oidc
to the app
environment in order to explicitly
remove the scope request. The bundled Docker Compose file in this directory does this
by default.