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:

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

    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.

    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"

  2. Modify the portal to use SAML for login:

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

    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

  3. To activate the changes, restart the LDAP server slapd within a maintenance window.

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

    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

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

  1. Sign in to Keycloak Admin Console.

  2. Navigate to UCS realm ‣ Clients ‣ Create.

  3. Specify the client-id for the client application (OIDC RP). Use the same client-id in the configuration of the client application.

  4. Select openid-connect in the Client Protocol drop-down list.

  5. Enter the root URL, the endpoint URL of the client application (OIDC RP).

  6. Click Save.

  7. 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.3. 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.4. 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.5. 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>`;

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"

To specify a MariaDB database after installation in UMC:

  1. Sign in to the UCS management system.

  2. Go to App Center ‣ Keycloak ‣ Manage Installation ‣ App Settings.

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

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.6. 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.7. Two-factor authentication for Keycloak#

Warning

The two-factor capability isn’t supported. Usage isn’t recommended in production environments.

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.7.1. Activate two-factor authentication for domain administrators#

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

  2. 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.7.2. Deactivate two-factor authentication for domain administrators#

  1. Sign in to Keycloak Admin Console.

  2. Navigate to UCS realm ‣ Groups.

  3. Select Domain Admins in the list and click Edit.

  4. Navigate to Role Mappings on the tabs.

  5. Remove 2FA role from Assigned roles.

3.8. Keycloak ad hoc federation#

Warning

Keycloak ad hoc federation isn’t supported. Usage isn’t recommended in production environments.

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.8.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.8.2. Create custom authentication flow#

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

  1. Sign in to Keycloak Admin Console.

  2. Navigate to UCS realm ‣ Authentication.

  3. Select First Broker Login in the list and click Copy.

  4. Give a name to the authentication flow and click OK.

  5. In the Review Profile (review profile config) click Actions and select Config.

  6. Select Off in the list, click Save and navigate back to the authentication flow.

  7. Click Add execution to get to the Create Authenticator Execution page.

  8. Select Univention Authenticator in the list and click Save.

  9. On the Flows tab in the Authentication section, change the Univention Authenticator in the displayed table to Required.

  10. To finish the configuration, click Actions in the Univention Authenticator and select Config.

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

  12. Click Save.

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

  1. Sign in to Keycloak Admin Console.

  2. Navigate to UCS realm ‣ Identity Providers.

  3. Click Add provider… and select SAML v2.0.

  4. Fill in the fields Alias and Display Name. You can’t change the field Alias later.

  5. Select your authentication flow with the Univention Authenticator on the First Login Flow.

  6. Fill in the field Service Provider Entity ID with the EntityID from the Relying Party on the Active Directory Federation Services.

  7. Set the Single Sign-On Service URL to the single sign-on URL from the Relying Party.

  8. In Principal Type select Unspecified in the fields NameID Policy Format, Attribute [Name].

    In Principal Attribute select sAMAccountName.

  9. Enable the following properties:

    • Allow Create

    • HTTP-POST Binding Response

    • HTTP-POST Binding for AuthnRequest

    • Want AuthnRequests Signed

  10. For the field Signature Algorithm select RSA_SHA256

    For the field SAML Signature Key Name select CERT_SUBJECT.

  11. Enable Validate Signature and add the certificate to Validating x509 Certificates.

  12. Click Save

3.8.4. Mappers for the identity provider#

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

  1. To create a mapper in the identity provider configuration navigate to UCS realm ‣ Identity Provider ‣ Your Identity Provider ‣ Mappers.

  2. Click Create

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

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

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

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

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

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

  1. Sign in as Administrator in Active Directory Federation Services.

  2. Open Relying Party Trust and click Add Relying Party Trust.

  3. Select Claim aware and click Start.

  4. On the Select Data Source page, select Import data about the relying party published online or on a local network.

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

  6. Specify a Display Name. Click Next.

  7. Select your wanted Access Control Policy. Click Next.

  8. Review your final configuration and click Next.

  9. Click Close.

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

  11. Apply and save the rules.

3.9. 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 19.0.0 Documentation [1].

keycloak/admin/user#

Defines the name of the first user with administration rights in Keycloak. The file /etc/keycloak.secret stores this user’s password on the system you installed the app.

Required

Default value

Set

Yes

admin

Only before installation
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/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/>'