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

By default the 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:

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

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.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 22.0 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/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#

This is a setting for the PostgreSQL database, the default database for Keycloak on the UCS system. The setting specifies the IP addresses from which the database can receive connections. The default value is 0.0.0.0, meaning that every IP address can connect to the database.

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. You find the available values at Configuring the database [9].

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

'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

'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 [10].

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.10. Customize the appearance#

The Keycloak app uses the same web theme as UCS, so that the UCR variable ucs/web/theme applies to Keycloak, as well. To adjust the web theme, follow the steps outlined in Creating a custom theme/Adjusting the design of UCS web interfaces in the UCS 5.0 Manual [2].

Administrators can change the values of the following CSS variables to customize the appearance of the web theme for the sign-in form provided by Keycloak. These CSS variables are specifically relevant to Keycloak. They take their default values from UMC and expect CSS background values.

  • --login-background

  • --login-box-background

  • --login-logo

Keycloak also uses /usr/share/univention-management-console-login/css/custom.css and loads from the URL /univention/login/css/custom.css. The CSS file gives more control than just the theme.

Caution

You may need to adjust your customizations in the CSS file custom.css after updates for UCS or the Keycloak app, because CSS selectors may change on updates.

See also

background - CSS: Cascading Style Sheets | MDN

for more information about the syntax for background values.

3.10.1. 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.11. 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.12. 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.13. 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.

Important

Univention doesn’t support nested groups in the group mapper between UCS and Keycloak. The reason is that Keycloak doesn’t support groups as members of groups.

3.13.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.6 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 [11].

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

Listing 3.7 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.13.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.

  1. In Keycloak Admin Console go to UCS realm ‣ User Federation ‣ ldap-provider ‣ Mappers ‣ Add mapper.

  2. Choose the Name of the mapper freely.

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

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

  1. Select YOUR_CLIENT ‣ Roles ‣ Create role.

  2. Enter name for the role univentionClientAccess.

  3. 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 [12].

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

  1. Select YOUR_GROUP ‣ Role mapping ‣ Assign role ‣ Filter by clients.

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

  3. Click Assign.

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

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