Skip to content

Identity Provider (Keycloak)

The OpenTalk Controller uses Keycloak, an OpenID Connect compatible identity and access management software for single sign-on.

Configuring Keycloak for OpenTalk Controller

Note

The Keycloak user interface changed in the past and because of that it's safe to assume that it will continue to change moving forward. Instead of screenshots we describe what needs to be done, and link to the Keycloak documentation where needed. These links reference a specific version of Keycloak. If those settings are outdated, please refer to the Keycloak documentation archive and find the corresponding section there.

This manual describes the configuration for the OpenTalk Controller only, other OpenTalk components might need separate configuration.

  1. Create a realm for usage with OpenTalk if it hasn't been created yet.
  2. The Realm ID will be used in the keycloak.realm configuration field.
  3. Create an OpenID Connect client.
  4. The Client ID will be used in the keycloak.client_id configuration field.
  5. Enable Client authentication and Service account roles in the Capability Config.
  6. Create Confidential client credentials.
  7. Use the Client Authenticator Client Id and Secret .
  8. The Client secret will be used in the keycloak.client_secret configuration field.

Controller configuration

In the past, the OIDC and user search section in the configuration file was called keycloak. Starting with controller version 0.21.0, this is deprecated, support will be removed in the future. Use the separate oidc and user_search sections instead.

Token introspection

To authenticate WebAPI requests, the OpenTalk Controller must verify the access tokens it receives. It uses token introspection whenever the OIDC provider offers an introspection endpoint, and only falls back to verifying access tokens locally as JWTs when introspection is unavailable.

Introspection is preferred because it additionally reveals whether a token is still active, for example whether it has been revoked. Local JWT verification can only check the token's signature and expiration and therefore cannot detect revoked tokens.

Keycloak exposes the introspection endpoint for confidential clients out of the box. A client configured with Client authentication enabled (as described above) therefore supports introspection without further configuration. it as well.

Warning

If the identity provider supports neither token introspection nor JWT access tokens, the controller cannot verify access tokens and rejects every request. See the OIDC Authentication Flow for details.

Configuring back-channel logout

The OpenTalk Controller implements OIDC back-channel logout. To let Keycloak notify the controller when a user logs out, configure the controller's client accordingly.

  1. Open the OpenID Connect client you created for the controller.
  2. In the client's Logout settings, set the Backchannel logout URL to the controller's callback endpoint https://<controller-host>/v1/auth/logout. Replace <controller-host> with the public host (and path prefix, if any) under which the controller's API is reachable.
  3. Leave Backchannel logout session required at whatever value you prefer. The controller resolves sessions via the sub claim and ignores sid, so this setting does not affect logout on the controller side.
  4. Make sure token introspection is available for the client. The controller resolves the affected session from the access token's sub claim, so it relies on the same token verification as regular authentication.