3. Configuration#

The Keycloak app offers various configuration options. Some settings don’t allow changes after installation. Therefore, you must set them carefully before installation. You find those settings marked with Only before installation in Settings. You can change all other settings at any time after the installation.

To change settings after installation, sign in to the UCS management system with a username with administration rights and go to App Center ‣ Keycloak ‣ Manage Installation ‣ App Settings. On the appearing Configure Keycloak page, you can change the settings and apply them to the app with a click on Apply Changes.

The App Center then reinitializes the Docker container for the Keycloak app. Reinitilize means the App Center throws away the running Keycloak Docker container and creates a fresh Keycloak Docker container with the just changed settings.

3.1. Use Keycloak for login to UCS Portal#

The Keycloak app can take over the role of the SAML IDP for the UCS Portal. And the portal can use Keycloak for user authentication.

Warning

The LDAP server will not recognize SAML tickets that the simpleSAMLphp based identity provider issued after you restart it. Users will experience invalidation of their existing sessions.

For more information about production use, see Installation on UCS.

To configure the UCS portal to use Keycloak for authentication, run the following steps on the system where you installed Keycloak:

Set the UCR variable umc/saml/idp-server to the URL https://ucs-sso-ng.$domainname/realms/ucs/protocol/saml/descriptor, for example https://ucs-sso-ng.example.org/realms/ucs/protocol/saml/descriptor. This step tells the portal to use Keycloak as IDP.
UMC

Sign in to the UCS management system and then go to System ‣ Univention Configuration Registry and search for the variable umc/saml/idp-server and set the value as described before.

Console
Open a shell on the UCS system as superuser root where you installed Keycloak and run the following command:
$ ucr set \ umc/saml/idp-server=\ "https://ucs-sso-ng.$(hostname -d)/realms/ucs/protocol/saml/descriptor"
Modify the portal to use SAML for login:
UMC

In the UCS management system go to Domain ‣ Portal ‣ login-saml. On the tab General in the section Advanced activate the Activated checkbox.

Console
Open a shell on the UCS system as superuser root where you installed Keycloak and run the following command:
$ udm portals/entry modify \ --dn "cn=login-saml,cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)" \ --set activated=TRUE
To activate the changes, restart the LDAP server slapd within a maintenance window.
UMC

In the UCS management system go to System ‣ System Services. Search for slapd and click to select the service. Then click Restart.

Console
Open a shell on the UCS system as superuser root where you installed Keycloak and run the following command:
$ service slapd restart

Note

If you don’t restart the LDAP server, you will see the following message in /var/log/syslog:

slapd[…]: SASL [conn=…] Failure: SAML assertion issuer https://ucs-sso-ng.$domainname/realms/ucs is unknown

By default Keycloak app creates a SAML SP (client) for every UCS Portal server. You can see the list of existing SAML SP clients with the following command:

$ univention-keycloak saml/sp get --json
[
    "https://ucs1.example.com/univention/saml/metadata",
    "https://ucs2.example.com/univention/saml/metadata",
    ...
]

If the SAML SP for a particular UCS Portal server doesn’t exist, you can create it in Keycloak with the command:

$ FQDN="the fqdn of the UCS Portal server"
$ univention-keycloak saml/sp create \
  --metadata-url="https://$FQDN/univention/saml/metadata" \
  --umc-uid-mapper

3.2. Import of user attributes from UCS to Keycloak#

Keycloak uses the LDAP directory of the UCS domain as backend for the user accounts. During the authentication process certain user attributes are imported into Keycloak. These attributes can be used later on in so called Attribute Mappers to pass additional information trough the SAML assertion or OIDC token to services (e.g. displayName).

By default the Keycloak app is configured to import the following user attributes:

LDAP attribute	Keycloak attribute
`uid`	`username`
`uid`	`uid`
`entryUUID`	`entryUUID`
`lastname`	`lastName`
`mailPrimaryAddress`	`email`
`givenName`	`firstName`
`createTimestamp`	`createTimestamp`
`modifyTimestamp`	`modifyTimestamp`

It is possible to configure the import of additional LDAP user attributes to Keycloak, for example

$ univention-keycloak user-attribute-ldap-mapper create description

to import the LDAP user attribute description to the Keycloak attribute description.

With the following command you get a list of all the currently configured Keycloak user attributes.

$ univention-keycloak user-attribute-ldap-mapper get --user-attributes

3.3. Keycloak as OpenID Connect provider#

The Keycloak app can serve as an OpenID Connect provider (OIDC Provider). The following steps explain how to configure an OIDC relying party (OIDC RP) to use Keycloak for authentication:

Keycloak Admin Console.
Navigate to UCS realm ‣ Clients ‣ Create.
Specify the client-id for the client application (OIDC RP). Use the same client-id in the configuration of the client application.
Select openid-connect in the Client Protocol drop-down list.
Enter the root URL, the endpoint URL of the client application (OIDC RP).
Click Save.
Finally, the administrator can review the URL settings and customize them, if necessary.

For more information, see Keycloak Server Administration Guide: OIDC clients [4].

New in version 19.0.1-ucs1: univention-keycloak added. For more information about the usage, see the --help option.

As an alternative the app Keycloak offers a command line tool. For usage, see the following example:

$ univention-keycloak oidc/op/cert get \
--as-pem \
--output "$SOMEFILENAME"
$ univention-keycloak oidc/rp create \
--app-url="https://$(hostname -f)/${MYAPP_URL}/" "${MYAPP_CLIENT_ID}"

The option group oidc/rp offers additional options like --client-secret.

Note

If the administrator chooses Confidential as Access Type on the client configuration page, Keycloak offers an additional Credentials tab with the credentials.

3.4. Keycloak as SAML Identity Provider#

New in version 19.0.1-ucs1: univention-keycloak added. For more information about the usage, see the --help option.

The Keycloak app can serve as an SAML IDP.

For apps that want to act as a SAML SP, you need to add a client configuration in Keycloak through the Keycloak Admin Console. For more information about how to create a SAML client configuration, see Keycloak Server Administration Guide: Creating a SAML client [5].

As an alternative the app Keycloak offers a command line tool. For usage, see the following example:

$ univention-keycloak saml/idp/cert get \
--as-pem --output "$SOMEFILENAME"
$ univention-keycloak saml/sp create \
--metadata-url "https://$(hostname -f)/$METADATA-URL-OF-THE-APP"

The option group saml/sp offers additional options like --client-signature-required.

Note

If the administrator chooses Confidential as Access Type on the client configuration page, Keycloak offers an additional Credentials tab with the credentials.

3.5. Backup and restore#

Administrators can create a backup of the Keycloak app data. The data comprises information for example about the realm, clients, groups, and roles. To create a backup, run the export action as in the following steps:

$ univention-app shell keycloak /opt/keycloak/bin/kc.sh export \
--dir /var/lib/univention-appcenter/apps/keycloak/data/myexport

In this example myexport is a freely chosen directory name.

To restore the backup into the app Keycloak, run the import action as in the following step:

$ univention-app shell keycloak /opt/keycloak/bin/kc.sh import \
--dir /var/lib/univention-appcenter/apps/keycloak/data/myexport

Warning

Keycloak defines the scope of exported data and may not contain every configuration option the program offers.

3.6. MariaDB as database#

The Keycloak app uses PostgreSQL as default database back end. This section explains how to configure the app Keycloak to connect and use a MariaDB database back end. The setup requires a configuration through Settings. Administrators can select the database back end either during initial app installation of Keycloak or change it later after installation.

The following examples for the database configuration assume that a user account with the appropriate permissions for MariaDB exists. They use the database user account keycloak and the password database-password.

Note

The database user needs the following minimum privileges to work in a single machine setup. Use the GRANT command:

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, REFERENCES, INDEX, DROP
ON `<database>`.* TO `<user>`@`<host>`;

Initial installation

To specify a MariaDB database during installation, run

$ univention-app install \
--set kc/db/url="jdbc:mariadb://${database_hostname}:3306/keycloak" \
--set kc/db/password="database-password"

After installation

UMC

To specify a MariaDB database after installation in UMC:

Sign in to the UCS management system.
Go to App Center ‣ Keycloak ‣ Manage Installation ‣ App Settings.
Search for the variable Database URI. Set the value to your MariaDB endpoint, for example jdbc:mariadb://$database_hostname:3306/keycloak and click Apply Changes.

Console

To specify a MariaDB database after installation on the command line:

$ univention-app configure keycloak \
--set kc/db/url "jdbc:mariadb://${database_hostname}:3306/keycloak" \
--set kc/db/password "database-password"

And to persist this change also in LDAP, use the following commands:

$ univention-install jq
$ new_json=$(univention-ldapsearch -LLL \
'(&(cn=keycloak)(univentionObjectType=settings/data))' \
| sed -n 's/^univentionData:: //p' | base64 -d | bzip2 --decompress \
| jq '.uri = "jdbc:mariadb://${database_hostname}:3306/keycloak"')
$ udm settings/data modify \
--dn "cn=keycloak,cn=data,cn=univention,$(ucr get ldap/base)" \
--set data=$(echo "$new_json" | bzip2 -c | base64 -w0)

3.7. Multiple installations in the domain#

Administrators can install the app Keycloak on several nodes in a UCS domain to increase availability and provide failover using the default DNS name ucs-sso-ng.$(hostname -d). The default installations in the domain don’t require any interaction from the administrator. This will also provide session synchronization between all Keycloak installations on the domain.

Note

If the Keycloak app is installed on multiple systems in the domain and updates are available, make sure to update the app on all systems so that all instances of the app in the domain are on the same version.

3.8. Two-factor authentication for Keycloak#

Warning

The two-factor capability is a built-in Keycloak feature that is not integrated into the UCS identity management or user lifecycle. More sophisticated integration needs to be added individually.

New in version 19.0.1-ucs1:

Added functionality to enable 2FA to univention-keycloak. For more information about the usage, see the --help option.

The app Keycloak offers a 2FA option. 2FA is an authentication method that grants users access to a service after they sign in with a password and a OTP randomly generated by a third-party OTP password generator like FreeOTP or Google Authenticator.

2FA increases the protection for user data, because users need to provide two pieces: knowledge (password) and something in the users’ possession (the OTP). It also increase the security of the system by avoiding account locking on known accounts because of malicious attacks. For more information, see Wikipedia: Multi-factor authentication.

After you activate 2FA for a group of users, Keycloak asks those users for their OTP on each login. To simplify the configuration process, you can use a command-line tool to enable 2FA.

To activate or deactivate 2FA for a user group, follow the instructions in the next sections.

3.8.1. Activate two-factor authentication for domain administrators#

Open a shell on the UCS system as superuser root where you installed Keycloak and run the following command:
```
$ univention-keycloak 2fa enable --group-2fa "Domain Admins"
```
The next time a user belonging to the Domain Admins group tries to sign in, Keycloak forces them to configure the 2FA following the instructions given during the login.

3.8.2. Deactivate two-factor authentication for domain administrators#

Sign in to Keycloak Admin Console.
Navigate to UCS realm ‣ Groups.
Select Domain Admins in the list and click Edit.
Navigate to Role Mappings on the tabs.
Remove 2FA role from Assigned roles.

3.9. Keycloak ad hoc federation#

Warning

The ad hoc federation is a built-in Keycloak feature that is not integrated into the UCS identity management or user lifecycle. More sophisticated integration needs to be added individually.

New in version 19.0.1-ucs2.

Keycloak SPI extension for ad hoc federation added. Keycloak offers identity brokering to delegate authentication to one or more identity providers for OpenID Connect or SAML 2.0.

See also

For more information about identity brokering and first login flow, see Keycloak Server Administration Guide: Identity Broker First Login [6].

The app Keycloak provides ad hoc federation to enable identity brokering and add user accounts to UCS as so-called shadow accounts. It supports the design decision about not having user accounts in Keycloak.

The app Keycloak installs the univention-authenticator SPI plugin. The plugin creates the local shadow copy of the user account in the OpenLDAP directory services through the REST API of UDM. Ad hoc federation is useful when administrators want to keep track of all users in UCS.

See also

For more information on SPI, see Keycloak Server Development Guide: Authentication SPI [7].

3.9.1. Import external CA certificates#

Federation involves other, for example external, server systems and requires trust. Certificates are a way to implement trust. To tell your Keycloak system to trust another system for the ad-hoc federation, you need to import the CA certificate for that system. Keycloak needs the CA certificate to verify the encrypted connection with the other system.

Use the following steps to add the CA certificate of the other system:

$ docker cp /path/to/externalCA.pem keycloak:/externalCA.pem
$ univention-app shell keycloak \
keytool -cacerts -import -alias ucsCA -file /externalCA.pem -storepass "changeit" -noprompt

Repeat this procedure when any CA certificate expires. In case of any CA related TLS error, restart the container:

$ docker restart keycloak

3.9.2. Create custom authentication flow#

First, you as administrator need to create a custom authentication flow to use univention-authenticator SPI:

Sign in to Keycloak Admin Console.
Navigate to UCS realm ‣ Authentication.
Select First Broker Login in the list and click Copy.
Give a name to the authentication flow and click OK.
In the Review Profile (review profile config) click Actions and select Config.
Select Off in the list, click Save and navigate back to the authentication flow.
Click Add execution to get to the Create Authenticator Execution page.
Select Univention Authenticator in the list and click Save.
On the Flows tab in the Authentication section, change the Univention Authenticator in the displayed table to Required.
To finish the configuration, click Actions in the Univention Authenticator and select Config.
Fill in the following configuration options for the Univention Authenticator:

Alias

Name of the configuration.

UDM REST API endpoint

The API endpoint of UDM where UCS stores the shadow copy of the user.

Username

Username of a user account that can write to UDM.

Password

Password of the user account that can write to UDM.
Click Save.

3.9.3. Create an identity provider for Microsoft Active Directory#

After you created the custom authentication flow, Keycloak can use ad hoc federation on any configured federated login. In this section, you learn how to set up a federated login using a Microsoft Active Directory Federation Services.

To create an identity provider for Active Directory that uses the ad hoc federation follow the next steps:

Sign in to Keycloak Admin Console.
Navigate to UCS realm ‣ Identity Providers.
Click Add provider… and select SAML v2.0.
Fill in the fields Alias and Display Name. You can’t change the field Alias later.
Select your authentication flow with the Univention Authenticator on the First Login Flow.
Fill in the field Service Provider Entity ID with the EntityID from the Relying Party on the Active Directory Federation Services.
Set the Single Sign-On Service URL to the single sign-on URL from the Relying Party.
In Principal Type select Unspecified in the fields NameID Policy Format, Attribute [Name].

In Principal Attribute select sAMAccountName.
Enable the following properties:
- Allow Create
- HTTP-POST Binding Response
- HTTP-POST Binding for AuthnRequest
- Want AuthnRequests Signed
For the field Signature Algorithm select RSA_SHA256

For the field SAML Signature Key Name select CERT_SUBJECT.
Enable Validate Signature and add the certificate to Validating x509 Certificates.
Click Save

3.9.4. Mappers for the identity provider#

The identity provider needs the following mapper configuration to work properly with Univention Corporate Server:

To create a mapper in the identity provider configuration navigate to UCS realm ‣ Identity Provider ‣ Your Identity Provider ‣ Mappers.
Click Create
Configure the mapper for the email address with the following properties:

Name

Name of the mapper

Sync Mode Override

import

Type of mapper

Attribute Importer

Attribute Name

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

User Attribute Name

email
Configure the mapper for the first name with the following properties:

Name

Name of the mapper

Sync Mode Override

import

Type of mapper

Attribute Importer

Attribute Name

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

User Attribute Name

firstName
Configure the mapper for the last name with the following properties:

Name

Name of the mapper

Sync Mode Override

import

Type of mapper

Attribute Importer

Attribute Name

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

User Attribute Name

lastName
Configure the mapper for univentionObjectIdentifier with the following properties:

Name

Name of the mapper

Sync Mode Override

import

Type of mapper

Attribute Importer

User attribute

objectGuid

User attribute Name

univentionObjectIdentifier
Configure the mapper for univentionSourceIAM with the following properties:

Name

Name of the mapper

Sync Mode Override

import

Type of mapper

Hardcoded attribute

User attribute

univentionSourceIAM

User attribute value

Identifier of the identity provider.
Configure the mapper for external-${ALIAS}-${ATTRIBUTE.sAMAccountName} with the following properties:

Name

Name of the mapper

Sync Mode Override

import

Type of mapper

Username Template Importer

User attribute

external-${ALIAS}-${ATTRIBUTE.sAMAccountName}

Target

LOCAL

3.9.5. Configure Active Directory Federation services for ad hoc federation#

To configure the Active Directory Federation Services to properly work with ad hoc federation you need to configure it with the following steps:

Sign in as Administrator in Active Directory Federation Services.
Open Relying Party Trust and click Add Relying Party Trust.
Select Claim aware and click Start.
On the Select Data Source page, select Import data about the relying party published online or on a local network.
In the field Federation metadata address insert the metadata URL: https://ucs-sso-ng.$(ucr get domainname)/auth/realms/ucs/broker/SAML IDP name/endpoint/descriptor.
Specify a Display Name. Click Next.
Select your wanted Access Control Policy. Click Next.
Review your final configuration and click Next.
Click Close.
Add the claims to the ticket.
objectGUID
1. Click Add rule and select Send LDAP Attributes as Claims.
2. Add a claim for objectGUID to the ticket:
  
  Claim Rule name
  
  Name of the Claim
  
  Attribute Store
  
  Active Directory
  
  LDAP attribute
  
  objectGUID
  
  Outgoing Claim Type
  
  objectGUID
sAMAccountName
1. Click Add rule and select Send LDAP Attributes as Claims.
2. Add a claim for sAMAccountName to the ticket:
  
  Claim Rule name
  
  Name of the Claim
  
  Attribute Store
  
  Active Directory
  
  LDAP attribute
  
  SAM-Account-Name
  
  Outgoing Claim Type
  
  sAMAccountName
Email address
1. Click Add rule and select Send LDAP Attributes as Claims.
2. Add a claim for the email address to the ticket:
  
  Claim Rule name
  
  Name of the Claim
  
  Attribute Store
  
  Active Directory
  
  LDAP attribute
  
  E-mail Addresses
  
  Outgoing Claim Type
  
  E-mail Address
Given name
1. Click Add rule and select Send LDAP Attributes as Claims.
2. Add a claim for the given name to the ticket:
  
  Claim Rule name
  
  Name of the Claim
  
  Attribute Store
  
  Active Directory
  
  LDAP attribute
  
  Given-Name
  
  Outgoing Claim Type
  
  Given Name
Surname
1. Click Add rule and select Send LDAP Attributes as Claims.
2. Add a claim for the surname to the ticket:
  
  Claim Rule name
  
  Name of the Claim
  
  Attribute Store
  
  Active Directory
  
  LDAP attribute
  
  Surname
  
  Outgoing Claim Type
  
  Surname
Apply and save the rules.

3.10. Settings#

The following references show the available settings within the Keycloak app. Univention recommends to keep the default values.

Keycloak has a lot more possibilities for configuration and customization. For more information, consult Keycloak 21.1 Documentation [1].

keycloak/log/level#

Configures the verbosity of log messages in Keycloak.

Possible values: ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARN.

For a detailed description of the log level values, see Keycloak documentation: Configuring logging [8].

Required	Default value	Set
Yes	`INFO`	Installation and app configuration

keycloak/java/opts#

Defines the options that the Keycloak app appends to the java command.

Required	Default value	Set
Yes	`-server -Xms1024m -Xmx1024m`	Installation and app configuration

keycloak/theme#

Defines the theme that Keycloak uses for the login interface. A CSS file with the same name must exist in the directory /usr/share/univention-web/themes/. The setting value only uses the basename of the file without the extension css.

Possible values

dark and light

If you provide custom CSS files with other names, they add to the possible values.

Possible values

true and false.

Required	Default value	Set
No	Same value as UCR variable `ucs/web/theme`.	Installation and app configuration

keycloak/server/sso/fqdn#

Defines the FQDN to the identity provider in your environment’s UCS domain. Defaults to ucs-sso-ng.$domainname.

Required	Default value	Set
No	`ucs-sso-ng.$domainname`	Installation and app configuration

keycloak/server/sso/autoregistration#

If set to true (default), the UCS system with the Keycloak app installed registers its IP address at the hostname of the identity provider defined in keycloak/server/sso/fqdn.

Possible values:: true or false

Required	Default value	Set
Yes	`true`	Installation and app configuration

keycloak/server/sso/virtualhost#

If set to true (default) the UCS system will create a dedicated apache virtual host configuration for the Keycloak server FQDN.

Possible values:: true or false

Required	Default value	Set
Yes	`true`	Installation and app configuration

keycloak/apache/config#

If set to true (default) the UCS system will create an apache configuration for Keycloak.

Possible values:: true or false

Required	Default value	Set
Yes	`true`	Installation and app configuration

keycloak/federation/remote/identifier#

This property stores the name of the UDM property that stores the unique identifier of the remote IAM objects. It is only used for ad hoc federation.

Required	Default value	Set
No	`univentionObjectIdentifier`	Installation and app configuration

keycloak/federation/source/identifier#

This property stores the name of the UDM property that stores the remote source of an IAM objects. It is only used for ad hoc federation.

Required	Default value	Set
No	`univentionSourceIAM`	Installation and app configuration

keycloak/database/connection#

Specifies the IP addresses from which the default PostgreSQL database can receive connections.

Required	Default value	Set
No	None	Installation and app configuration

kc/db/url#

Specifies the database JDBC URL (for example jdbc:postgresql://dbhost/keycloak) to connect Keycloak. Defaults to jdbc:postgresql://fqdn:5432/keycloak.

Required	Default value	Set
No	`jdbc:postgresql://fqdn:5432/keycloak`	Installation and app configuration

kc/db/username#

Specifies the database username. Defaults to keycloak.

Required	Default value	Set
No	`keycloak`	Installation and app configuration

kc/db/kind#

Specifies the kind of database. Defaults to postgres.

Required	Default value	Set
No	`postgres`	Installation and app configuration

kc/db/password#

Specifies the password to connect to the database.

Required	Default value	Set
No	None	Installation and app configuration

ucs/self/registration/check_email_verification#

Controls if the login is denied for unverified, self registered user accounts. For more information, see Account verification in the UCS 5.0 Manual [2].

Required	Default value	Set
No	False	Installation and app configuration

keycloak/login/messages/en/accountNotVerifiedMsg#

English error message for a self-registered user account that isn’t verified yet. The error message supports HTML format.

Required	Default value	Set
No	See default value in Listing 3.1 after the table.	Installation and app configuration

Listing 3.1 Default value for keycloak/login/messages/en/accountNotVerifiedMsg#

'Your account is not verified.<br>You must <a id="loginSelfServiceLink" href="https://${hostname}.${domainname}/univention/selfservice/#/selfservice/verifyaccount" target="_blank">verify your account</a> before you can login.<br/>'

keycloak/login/messages/de/accountNotVerifiedMsg#

German error message for a self-registered user account that isn’t verified yet. The error message supports HTML format.

Required	Default value	Set
No	See default value in Listing 3.2 after the table.	Installation and app configuration

Listing 3.2 Default value for keycloak/login/messages/de/accountNotVerifiedMsg#

'Konto nicht verifiziert.<br>Sie m\\u00FCssen Ihr <a id="loginSelfServiceLink" href="https://${hostname}.${domainname}/univention/selfservice/#/selfservice/verifyaccount" target="_blank">Konto verifizieren</a>, bevor Sie sich einloggen k\\u00F6nnen.<br/>'

keycloak/csp/frame-ancestors#

Additional entries to the frame-ancestors directive of the Keycloak virtual host. The space separated list of sources can have multiple values can be used. For example, https://portal.external.com https://*.remote.de. For more information, see CSP: frame-ancestors in Mozilla Foundation [9].

Required	Default value	Set
No	None	Installation and app configuration

keycloak/apache2/ssl/certificate#

Sets the absolute path to the SSL certificate file for the Apache web server module mod_ssl of the Keycloak virtual host. The web server needs the certificate in the PEM format.

The web server uses the UCS certificate from /etc/univention/ssl/ucs-sso-ng.$domainname/cert.pem, if the UCR variable has no value.

Required	Default value	Set
No	`/etc/univention/ssl/ucs-sso-ng.$domainname/cert.pem`	Installation and app configuration

keycloak/apache2/ssl/key#

Sets the absolute path to the private RSA/DSA key of the SSL certificate file for the Apache web server module mod_ssl of the Keycloak virtual host. The web server needs the certificate in the PEM format.

The web server uses the UCS private key from /etc/univention/ssl/ucs-sso-ng.$domainname/private.key, if the UCR variable has no value.

Required	Default value	Set
No	`/etc/univention/ssl/ucs-sso-ng.$domainname/private.key`	Installation and app configuration

keycloak/apache2/ssl/ca#

Sets the absolute path to the certificate of the certificate authority (CA) for the Apache web server module mod_ssl of the Keycloak virtual host. The web server needs the certificate in the PEM format.

The web server uses the UCS CA from /etc/univention/ssl/ucsCA/CAcert.pem, if the UCR variable has no value.

Required	Default value	Set
No	`/etc/univention/ssl/ucsCA/CAcert.pem`	Installation and app configuration

keycloak/cookies/samesite#

This setting sets the SameSite attribute in all the cookies of Keycloak. Possible values are Lax, Strict and the default value None.

Required	Default value	Set
No	`None`	Installation and app configuration

3.11. Adjusting texts on the Keycloak login page#

The Keycloak app lets Administrators overwrite any messages on the Keycloak login page. Each text variable value in this login template can be overwritten by using a UCR variable of the form

keycloak/login/messages/[de/en]/key=value

This make use of the Keycloak message bundles that are documented here: https://www.keycloak.org/docs/latest/server_development/#messages

For example, the login title in the Keycloak login dialogue can be adjusted like this:

$ ucr set \
keycloak/login/messages/en/loginTitleHtml=\
'Login at Domainname'

After setting one of these variables, this command has to be run to make the change visible in Keycloak login page:

$ univention-app configure keycloak

Warning

These settings are local settings. The UCR variables have to be set on each host running Keycloak.

3.12. Adjusting the Keycloak apache configuration#

The Keycloak app ships an apache configuration in /etc/apache2/sites-available/univention-keycloak.conf. This file is created by the app and will be overwritten during updates.

This configuration can be customized by creating the file /var/lib/univention-appcenter/apps/keycloak/data/local-univention-keycloak.conf.

For example, an Administrator may want to restrict the access to the Keycloak administration console to a specific IP subnet by putting this in the local-univention-keycloak.conf.

<LocationMatch "^(/admin/|/realms/master/)">
              deny from all
              allow from 10.207.0.0/16
</LocationMatch>

3.13. Activating Kerberos authentication#

In the default configuration, the Keycloak app evaluates Kerberos tickets during the authentication process. If you have a UCS domain with client workstations that obtain Kerberos tickets during the user login process, users can configure their web browsers to send this ticket to Keycloak for authentication to enable a passwordless login, for example in the UCS portal.

To enable the web browser to send the Kerberos tickets, you must change the following settings:

Mozilla Firefox: Open a new tab and enter about:config in the address bar to open the Firefox configuration. Search for network.negotiate-auth.trusted-uris and add the FQDN of your Keycloak server, which is ucs-sso-ng.[Domain name] by default.
Microsoft Edge: For Microsoft Edge on Windows, you need to configure Kerberos authentication in the general settings of the operating system. Open the Control Panel and move to Security ‣ Local Intranet ‣ Sites ‣ Advanced. Add the FQDN of your Keycloak server, ucs-sso-ng.[Domain name] by default, to the list of Websites.

If you install the Active Directory-compatible Domain Controller app after installing Keycloak, you need to run the following command on the Primary Directory Node. It ensures that the Kerberos authentication also works with the Active Directory-compatible Domain Controller:

$ eval "$(ucr shell keycloak/server/sso/fqdn)"
$ samba-tool spn add "HTTP/$keycloak_server_sso_fqdn" "krbkeycloak"

Per default, Keycloak tries to use Kerberos. If no Kerberos ticket is available, Keycloak falls back to username and password authentication. You can deactivate this behavior in the Keycloak Admin Console with the following steps:

Select the realm UCS.
On the sidebar, click User federation and choose ldap-provider.
Go to the section Kerberos integration and deactivate Allow Kerberos authentication.

3.14. Restrict access to applications#

New in version 21.1.2-ucs2.

With the UCS simpleSAMLphp integration, you can restrict access of groups and users to specific SAML service providers through the UDM SAML settings.

The configuration steps in the following sections restrict access to certain SAML service providers and OIDC Relying parties through group membership in a similar way with Keycloak.

Attention

Application access restriction isn’t yet integrated into the UDM UMC module yet.

If you already need the application access restriction for groups at this time, read on and follow the steps outlined below. Note that you may need to perform manual migration steps after the integration is complete.

If you don’t have an immediate need, it’s recommended that you wait until the integration is complete in a future version of the Keycloak app.

This configuration differs from the one provided by simpleSAMLphp in the following ways:

Only the group membership restricts the access to applications. It isn’t possible to restrict the access for an individual user directly.
You must configure group access restrictions for SAML SP and OIDC RP directly in the Keycloak Admin Console, although you manage users and their group memberships in UDM.
By default, Keycloak allows access to all users. Only when you specifically configure the SAML SP or OIDC RP to use app authorization will Keycloak evaluate the access restriction to applications.

3.14.1. Create authentication flow#

Keycloak version 21.1.2-ucs2 provides an authenticator extension called Univention App authenticator, which performs the authorization validation on the user during the sign-in.

To use this authenticator, you need to create a Keycloak authentication flow that includes this authenticator. Use the command univention-keycloak as follows. The command doesn’t give any output:

Listing 3.3 Create a Keycloak authentication flow#

$ univention-keycloak legacy-authentication-flow create

See also

For more information on authentication flows, see Keycloak Server Administration Guide: Authentication flows [10].

3.14.2. Assign authentication flow#

Keycloak calls the SAML SP and the OIDC RP Client. By default, neither SAML SP nor OIDC RP use the created authentication flow.

To restrict application access, you must assign the created authentication flow to each Keycloak Client. Otherwise, the Keycloak Client still allows access to all users. To assign a specific flow to an existing Keycloak Client, use the following command in Listing 3.4.

Listing 3.4 Assign authentication flow to a Keycloak Client#

$ univention-keycloak client-auth-flow \
  --clientid "REPLACE_WITH_YOUR_CLIENT_ID" \
  --auth-flow "browser flow with legacy app authorization"

Note

You can also pass the option --auth-browser-flow when you create a SAML SP or OIDC RP as a Keycloak Client. See section Keycloak as SAML Identity Provider on how to create a Keycloak Client.

3.14.3. Map UDM groups to Keycloak#

To restrict access to certain Keycloak Clients by group membership, you must map the necessary groups to Keycloak. Use the Keycloak Admin Console to create an appropriate LDAP mapper.

In Keycloak Admin Console go to UCS realm ‣ User Federation ‣ ldap-provider ‣ Mappers ‣ Add mapper.
Choose the Name of the mapper freely.
Select the Mapper type group-ldap-mapper to extend the form. Fill in the fields as following:

LDAP Groups DN

Set to the value of the base LDAP DN of your domain, for example dc=example,dc=local.

Group Object Classes

univentionGroup

Ignore Missing Groups

On

Membership LDAP Attribute

memberUid

Membership Attribute Type

UID

Drop non-existing groups during sync

On

Important

It’s strongly recommended to set an LDAP Filter in the group mapper so that Keycloak only maps strictly necessary groups. If you don’t specify an LDAP filter, Keycloak synchronizes all groups from the LDAP directory service. Depending on the size of the groups, it may impact the performance of Keycloak.

Example
To filter groups by their name and only allow Keycloak to synchronize the mentioned groups, use (|(cn=umcAccess)(cn=nextcloudAccess))
Scroll down and click Save.

To trigger the synchronization of the groups immediately, click the name of the mapper you just created to open it and select Sync LDAP groups to Keycloak from the Action drop-down.

3.14.4. Create client roles#

3.14.5. Create Keycloak client roles#

The authenticator extension Univention App authenticator restricts access by evaluating the roles of a user in Keycloak. It specifically checks for a client specific role named univentionClientAccess. If this client specific role exists, the authenticator extension restricts access of all users that don’t have this role.

For each Keycloak Client that you want to check access restrictions, you need to create the role univentionClientAccess. In Keycloak Admin Console go to UCS realm ‣ Clients. For each client of interest, run the following steps:

Select YOUR_CLIENT ‣ Roles ‣ Create role.
Enter name for the role univentionClientAccess.
Click Save.

Important

Follow the next section Attach the client specific role to groups immediately, because saving the client role enforces the sign-in restriction for the Keycloak Client.

See also

For more information on roles in Keycloak, see Keycloak Server Administration Guide: Assigning permissions using roles and groups [11].

3.14.6. Attach the client specific role to groups#

To grant access permission to group members of a group so that they can sign in to an app, you need to attach the Keycloak Client role to the groups. All group members then inherit the client role.

In Keycloak Admin Console go to UCS realm ‣ Groups. For each group of interest, run the following steps:

Select YOUR_GROUP ‣ Role mapping ‣ Assign role ‣ Filter by clients.
Find and select the app you intend to control with univentionClientAccess.

Warning

Keycloak doesn’t evaluate nested group memberships. Only direct group membership of a user give the user the necessary client role.
Click Assign.

From now on, only the users that inherited the Keycloak Client specific role univentionClientAccess have access to the respective applications.

3.14.7. Customize the authorization error page#

Keycloak shows an error page, if a user doesn’t have access to an application because the access restriction applies to them.

You can configure the error page through the following App settings:

German: keycloak/login/messages/de/accessDeniedMsg
English: keycloak/login/messages/en/accessDeniedMsg

You can include HTML format with links in this setting to customize the error page.

The default message shows the client ID of the Keycloak Client that forbids access to the user. If you need a human readable name, you can set the attribute Name of the Keycloak Client in the Keycloak Admin Console. With the attribute set, Keycloak shows the Name instead of the client ID.

Important

The app setting only applies to the local Keycloak instance. You can use different values on the different Keycloak installations, for example, to show a link to the local portal.

For more information, refer to Adjusting texts on the Keycloak login page.

Keycloak app 21.1.2

Configuration

Contents

3. Configuration#

3.2. Import of user attributes from UCS to Keycloak#

3.3. Keycloak as OpenID Connect provider#

3.4. Keycloak as SAML Identity Provider#

3.5. Backup and restore#

3.6. MariaDB as database#

3.7. Multiple installations in the domain#

3.8. Two-factor authentication for Keycloak#

3.8.1. Activate two-factor authentication for domain administrators#

3.8.2. Deactivate two-factor authentication for domain administrators#

3.9. Keycloak ad hoc federation#

3.9.1. Import external CA certificates#

3.9.2. Create custom authentication flow#

3.9.3. Create an identity provider for Microsoft Active Directory#

3.9.4. Mappers for the identity provider#

3.9.5. Configure Active Directory Federation services for ad hoc federation#

3.10. Settings#

3.12. Adjusting the Keycloak apache configuration#

3.13. Activating Kerberos authentication#

3.14. Restrict access to applications#

3.14.1. Create authentication flow#

3.14.2. Assign authentication flow#

3.14.3. Map UDM groups to Keycloak#

3.14.4. Create client roles#

3.14.5. Create Keycloak client roles#

3.14.6. Attach the client specific role to groups#

3.14.7. Customize the authorization error page#