Skip to main content

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 the IdP or as an identity broker for Traefik Hub.

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

Once Keycloak is enabled and successful configured in the dashboard, Traefik Hub will synchronize user and groups from Keycloak into Traefik Hub.

After the first initial sync, Traefik Hub will sync once an hour with Keycloak.

When authenticating to the API Portal, the user is matched against the latest known synchronization point in the Traefik Hub database.

Traefik Hub will not list automatically all users after synchronization. Users will be only listed after a first successful login into Traefik Hub.

Shared Data Between Traefik Hub and Keycloak

The following data is shared between Traefik Hub and Keycloak:

  • URL: The URL of your Keycloak instance.
  • Realm: Name of the Keycloak realm you want to use.
  • Username: Username of the realm management account.
  • Password: Password of the Keycloak realm management account (encrypted).
  • Users and Groups: Configured in the realm settings.

Before You Begin

warning

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!


Permissions

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

info

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.

Configuration

First, select Auth settings in the left navigation menu to get to the IdP overview, then select the toggle on the external IdP.

In the next step, configure the Keycloak integration:

FieldDescriptionRequired
URLThe URL of your Keycloak instance.Yes
RealmName of the Keycloak realm you want to use.Yes
LoginRealm management account. The account must have the rights to manage OIDC clients, users, and groups in the realm.Yes
PasswordPassword of the Keycloak realm management account.Yes

Dialog box about the Keycloak configuration.

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

Dialog showing that the configuration works.

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

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

warning

Please make sure to read the displayed message 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.

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

warning

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.

Initiate Keycloak synchronization.


  • Learn how to use JWT for API requests in the API Portal.