Keycloak

This page explains how to use Keycloak as the identity provider (IdP) to manage access to API Portals.

Introduction¶

You can use Keycloak as IdP or as an identity broker for Traefik Hub.

Before you begin¶

If you replace your Traefik Hub internal IdP with an external IdP, all users, user groups, and tokens created by the internal IdP will be deleted.

This action is irreversible!

Keycloak¶

Keycloak is an open-source identity and access management solution that provides authentication and authorization.

Permissions¶

Before you begin, please ensure the realm management account has all the required permissions.

Please do not use the Master realm of your Keycloak instance!
It is recommended to always create and use a new realm with reduced permissions.

A realm manages a set of users, credentials, roles, and groups.
A user belongs to and logs into a realm.
Realms are isolated from one another and can only manage and authenticate the users they control.

Traefik Hub needs to be able to view and query users and groups and manage clients.
No further permissions are required.

Configuration¶

First, select Auth settings in the left navigation menu to get to the ID provider overview page in the UI.

Now, on the IdP overview page, select Keycloak on the external IdP provider.

In the next step, configure the Keycloak integration:

Field	Description	Required
`URL`	The URL of your Keycloak instance.	Yes
`Realm`	Name of the Keycloak realm you want to use.	Yes
`Login`	Realm management account. The account must have the rights to manage OIDC clients, users, and groups in the realm.	Yes
`Password`	Password of the Keycloak realm management account.	Yes

Dialog box about the Keycloak configuration — Keycloak configuration

Once you're done, you can test your configuration by selecting Test connection.

Dialog showing that the configuration works — Successfully connection

If the connection is working, save your configuration by selecting Save.

In the last step, you have to confirm the configuration changes.

Please make sure to read the displayed message carefully and follow the needed steps for confirmation!

If you already have users and groups configured, these accounts and all related user data, including tokens, will be deleted from Traefik Hub.

Hub IdP sync — Successfully configuration

Traefik Hub will sync with your Keycloak realm immediately after confirming your configuration.

Please do not try to change your configuration during the synchronization process!

From then on, Traefik Hub is configured to use Keycloak as its IdP.

The user overview page in the dashboard will not automatically show all users.
Users will only be listed after a successful login into an API Portal.

Synchronization¶

Traefik Hub will automatically sync every 60 minutes with your Keycloak realm.
After a first successful synchronization, you can initiate a sync at any time by selecting the Synchronize button.

What's next¶

Learn how to validate JWT with Keycloak.