1. Installation#

You can install the Keycloak app like any other app with Univention App Center. The App Center only allows to install Keycloak on a UCS system with system role Primary Directory Node or Backup Directory Node. For more information, see Primary Directory Node in UCS 5.0 Manual [2].

UCS offers two different ways for app installation:

  • With the web browser in the UCS management system

  • With the command-line

For general information about Univention App Center and how to use it for software installation, see Univention App Center in UCS 5.0 Manual [2].

1.1. Installation with the web browser#

To install Keycloak from the UCS management system, use the following steps:

  1. Use a web browser and sign in to the UCS management system.

  2. Open the App Center.

  3. Select or search for Keycloak and open the app with a click.

  4. To install Keycloak, click Install.

  5. Leave the App settings in their defaults or adjust them to your preferences. For a reference, see Settings.

  6. To start the installation, click Start Installation.

Note

To install apps, the user account you choose for login to the UCS management system must have domain administration rights, for example the username Administrator. User accounts with domain administration rights belong to the user group Domain Admins.

For more information, see Delegated administration for UMC modules in UCS 5.0 Manual [2].

1.2. Installation with command-line#

To install the Keycloak app from the command-line, use the following steps:

  1. Sign in to a terminal or remote shell with a username with administration rights, for example root.

  2. Choose between default and custom settings and run the appropriate installation command.

    For installation with default settings, run:

    $ univention-app install keycloak

    To pass customized settings to the app during installation, run the following command:

    $ univention-app install --set $SETTING_KEY=$SETTING_VALUE keycloak

    Caution

    Some settings don’t allow changes after installation. To overwrite their default values, set them before the installation. For a reference, see Settings.

    Example: To define a different administration user in Keycloak, run:

    $ univention-app install --set keycloak/admin/user="Administrator" keycloak

1.3. Initial Keycloak configuration#

The first installation of the Keycloak app in the UCS domain creates an initial configuration.

To not overwrite custom settings, subsequent installations of the Keycloak app on additional UCS systems in the domain don’t create the initial configuration.

Factory reset of the configuration

For a factory reset of the configuration, delete the realm UCS in the Keycloak Admin Console.

Warning

Beware, your installation looses all custom configuration settings, custom services providers and other changes to the realm UCS.

After you deleted the realm UCS, create the initial configuration with the following command:

$ univention-keycloak init

1.4. Sign in to Keycloak Admin Console#

After a successful installation, signed in domain administrator users see the tile Keycloak on the UCS Portal, that directs them to the Keycloak Admin Console.

The URL has the following scheme: https://ucs-sso-ng.$domainname/admin/. The $domainname is your UCS domain name.

Example:

https://ucs-sso-ng.example.com/admin/

The username for login is the name of the initial admin user defined during installation and saved in the UCR variable keycloak/admin/user.

Note

All users in the Domain Admins, for example the domain user Administrator, can also sign in to the Keycloak Admin Console.

1.5. Fetch metadata for service provider configuration#

OIDC and SAML both offer machine readable information to the services that want to use the authentication services in Keycloak. This information is the metadata discovery documents.

In the Keycloak Admin Console you can find them at realm settings ‣ UCS ‣ Endpoints. At the endpoints you see OpenID Endpoint Configuration and SAML 2.0 Identity Provider Metadata. To view the metadata discovery documents, click the endpoint entries.

With the following commands you can obtain the URLs to the metadata information. Some services comfortably take the URL and configure the authentication automatically.

To download the metadata information for OIDC, run the following command:

$ wget "https://ucs-sso-ng.$(hostname -d)/keycloak/realms/ucs/.well-known/openid-configuration"

To download the metadata information for SAML, run the following command:

$ wget "https://ucs-sso-ng.$(hostname -d)/keycloak/realms/ucs/protocol/saml/descriptor"