Skip to main 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.
    • The Realm ID will be used in the keycloak.realm configuration field.
  2. Create an OpenID Connect client.
    • The Client ID will be used in the keycloak.client_id configuration field.
    • Enable Client authentication and Service account roles in the Capability Config.
  3. Create Confidential client credentials.
    • Use the Client Authenticator Client Id and Secret .
    • The Client secret will be used in the keycloak.client_secret configuration field.

Configuration

The section in the configuration file is called keycloak.

FieldTypeRequiredDefault valueDescription
base_urlstringyes-TCP port number where the Keycloak server can be reached
realmstringyes-The name of the default Keycloak realm, read more on Keycloak
client_idstringyes-The unique identifier for the OpenTalk client
client_secretstringyes-The secret corresponding to the specified client ID
external_id_user_attribute_namestringnoSee belowThe attribute by which Keycloak and OpenTalk users are assigned to each other. See below for more details.

For configuring user search, see the User search section.

The external_id_user_attribute_name setting is used to configure how Keycloak users resulting from a search and registered Opentalk users are assigned to each other. The following assignment strategies are available:

  • by Keycloak id (default): This is used if external_id_user_attribute_name is not set. Keycloak users are assigned to Opentalk users using Keycloak's id field.
  • by user attribute: Keycloak must provide a user attribute holding the user IDs. The name of this user attribute must be set here in external_id_user_attribute_name.

Examples

Default Setup

[keycloak]
base_url = "http://localhost:8080/auth"
realm = "MyRealm"
client_id = "Controller"
client_secret = "c64c5854-3f02-4728-a617-bbe98ec42b8f"

KeyCloak setup

KeyCloak can provide some fields in the JWT to the OpenTalk Controller. These fields differ for authentication of normal users and services.

JWT fields for user login

FieldTypeRequiredDescription
expstringyesRFC 3339 timestamp of the token's expiration date
iatstringyesRFC 3339 timestamp of the token's issuing date
issstringyesURL of the OIDC provider
substringyesUnique identifier of the user
emailstringyesE-Mail address of the user
given_namestringyesThe given name (also known as first name) of the user
family_namestringyesThe family name (also know as last name) of the user
tenant_idstringif tenant assignment is "by_external_tenant_id"Contains the identifier of the user's tenant
tariff_idstringif tariffs are usedThe external id of the tariff. See tariffs for further details
tariff_statusstringif tariffs are usedThe external id of the tariff status. See tariffs for further details
x_grpstring[]noA list of groups which the user is part of
phone_numberstringnoThe phone number of the user
nicknamestringnoNickname of the user, typically used to prefill the display name of a meeting participant
picturestringnoURL to a user picture, will replace the gravatar url generation for that user if provided

Security considerations

For the picture field, the frontend will download the images found under the provided URL. Therefore it is important to only provide URLs that are guaranteed to not inject unwanted content, but rather have a policy which ensures that only valid images are served.

JWT fields for service login

FieldTypeRequiredDescription
expstringyesRFC 3339 timestamp of the token's expiration date
iatstringyesRFC 3339 timestamp of the token's issuing date
issstringyesURL of the OIDC provider
realm_accessRealmAccessyesAn object containing realm access information

The RealmAccess object contains these fields:

FieldTypeRequiredDescription
rolesstring[]yesA list of role identifiers that the service is allowed to provide

The list of known service roles is: