Skip to content


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


You can use Keycloak (external IdP) for Single Sign-On (SSO) 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!


Traefik Hub uses Keycloak to integrate with popular authentication providers (external IdPs).

Keycloak is an open-source identity and access management solution that provides authentication, authorization, and single sign-on capabilities for applications and services.

Portal access tokens are stored in Traefik Hub.


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.

Realm permissions

Realm permissions overview


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

IdP overview

Select ID providers

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

IdP selection dialog

IdP selection

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.
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.


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.

Initiate Keycloak synchronization

Initiate Keycloak synchronization