Univention Keycloak app manual 23.0.7

Download PDF

Use cases

8. Use cases#

This section describes some uses cases for the app Keycloak to give a deeper insight of the app’s capability.

8.1. Expired password and change password on next sign-in#

In some situations, administrators create a user account with a temporary password that requires the account owner to change their password during their first sign-in. The procedure can be company policy or just considered a good practice. Also, if for any other reason like a lost or compromised user password, the account owner can contact the administrator and request a password change.

See also

User management module - Account tab

For user account expire and set password upon first login, refer to UCS 5.0 Manual [2].

To enable these capabilities with Keycloak, the app offers the following extensions. The extensions only provide the capabilities in the UCS realm with the Keycloak app installed.

Univention LDAP mapper

In Keycloak Admin Console follow UCS realm ‣ User Federation ‣ ldap-provider ‣ Mappers

The LDAP mapper reads necessary attributes from the LDAP directory and triggers a password update when needed.

Univention update password

In Keycloak Admin Console follow UCS realm ‣ Authentication ‣ Required Actions

Univention update password provides dialogs and forms in the Keycloak login flow.

8.2. Single sign-on through external public domain name#

The typical single sign-on configuration in UCS uses a shared DNS record to provide a failover for the sign-in. The SAML IDP is available at ucs-sso-ng.$domainname. The administrator chose the environment’s $domainname during UCS installation.

See also

Domain settings during UCS installation

for information about domain modes, settings and naming conventions in the UCS 5.0 Manual [2].

Administrators often choose the UCS domain name for an intranet scenario and adapt the service configuration to match the target domain and hostnames. The term FQDN identifies the combination of hostname and domain used to uniquely identify a service. For more information, see Wikipedia contributors [12].

The use case single sign-on through external, public domain name addresses administrators who want single sign-on availability from the internet. Administrators find the steps to reconfigure the FQDN for the single sing-on and the UCS portal in this section. The configuration for this scenario recommends two UCS servers or more for serving the different FQDNs. If you encounter problems during the steps below, see Configuration of single sign-on through external public domain.

Validate configuration success

Administrators can validate the success of their configuration with the following steps:

  1. Use your preferred web browser and open the UCS portal under the just configured FQDN.

  2. Sign in as user through single sign-on.

  3. After sign-in through single-sign on, the browser redirects you as user back to the UMC portal.

  4. If you encounter problems during the validation, see Configuration of single sign-on through external public domain.

Note

The following aspects faced by administrators encounter in this use case are beyond the scope of this document:

  • Configuration of an external DNS to point to the UCS system.

  • Configuration of network components to route the connection from the internet to the UCS system.

  • Obtaining a valid certificate from a CA.

Warning

The Keycloak admin interface as well as the Keycloak REST API are also publicly available if the Keycloak app was configured to be available externally. For security reasons, this should be restricted. Please see Adjusting the Keycloak apache configuration for an exemplary configuration.

8.2.1. External FQDN different from internal UCS name#

New in version 21.0.1-ucs2.

A common scenario is to have the UCS portal available at one FQDN, such as portal.internet.domain, and single sign-on available at another different FQDN, such as sso.internet.domain.

Before starting with the configuration of this use case, consider the following aspects:

Pre-conditions:

For the scenario described below, it’s important to have the following setup in place, before you proceed:

  1. You configured the external DNS entry for Keycloak, for example sso.internet.domain.

  2. You configured the external DNS entry for the UCS portal, for example portal.internet.domain.

  3. You have obtained proper SSL certificates for Keycloak and the UCS portal new FQDN.

The following steps require a working network access from the UCS system to the external identity provider FQDN.

8.2.1.1. Configuration of the identity provider#

To configure single sign-on on each Keycloak instance in your UCS domain, follow the steps below:

  1. Configure the single sign-on FQDN to a custom value. Set the following UCR variables:

    $ SSO_FQDN=sso.internet.domain
$ ucr set keycloak/server/sso/fqdn="${SSO_FQDN}"
$ ucr set keycloak/server/sso/autoregistration=false
$ ucr set keycloak/apache2/ssl/certificate="/path/to/${SSO_FQDN}/cert.pem"
$ ucr set keycloak/apache2/ssl/key='/path/certificate/${SSO_FQDN}/private.key'
# Add the new public domain of the portal to the frame-ancestor to the CSP
$ ucr set keycloak/csp/frame-ancestors='https://*.internet.domain'

$ univention-app configure keycloak

  2. Adjust the standard Keycloak portal entry in the UCS domain after changing the single sign-on FQDN:

    $ udm portals/entry modify \
  --dn "cn=keycloak,cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)" \
  --set link='"en_US "https://sso.internet.domain/admin/"'

Warning

After changing the configuration of the identity provider with the previous steps, all services can’t use that identity provider until proper configuration.

8.2.1.2. Configuration of UMC as service provider#

To re-configure single sign-on for UMC on all UCS systems in the domain, run the following commands:

$ ucr set umc/saml/idp-server="https://${SSO_FQDN}/realms/ucs/protocol/saml/descriptor"
$ service slapd restart

For UCS systems joining the domain, configure a UCR policy and assign it the UCS systems before you install them. The UCR policy must set umc/saml/idp-server to your custom FQDN.

8.2.1.3. Configuration of UCS Portal to use external fully qualified domain name#

As an example use case to expose the UCS portal to the internet, follow the steps below. Apply the steps only to the UCS system that exposes the UCS portal to the internet.

  1. Store the certificate files for the UCS portal in the following locations on your UCS system:

    • Certificate: /etc/univention/ssl/$PORTAL_FQDN/cert.pem

    • Private key for the certificate: /etc/univention/ssl/$PORTAL_FQDN/private.key

  2. Configure the UCR variables to use the custom FQDN and the certificates:

    $ SSO_FQDN=sso.internet.domain
$ PORTAL_FQDN=portal.internet.domain
$ ucr set umc/saml/sp-server="${PORTAL_FQDN}"
$ ucr set umc/saml/idp-server="https://${SSO_FQDN}/realms/ucs/protocol/saml/descriptor"

  3. Run the join script to update the web server configuration:

    $ univention-run-join-scripts \
--force \
--run-scripts 92univention-management-console-web-server.inst

8.2.2. External FQDN identical to internal UCS name#

New in version 21.1.0-ucs1.

In this scenario the FQDN of the UCS system and the external name for accessing the UCS Portal are identical. Furthermore, the name for the single sign-on endpoint uses the same FQDN. To achieve this use a different URL path for the single sign-on endpoint, for example:

Internal name:

portal.example.test

External name:

portal.example.test

Single sign-on URL:

portal.example.test/auth

Pre-conditions:

For this scenario, it’s important to have the following setup in place, before you proceed:

  1. You configured the external DNS entry for Keycloak, for example portal.example.test.

  2. You have obtained proper SSL certificates for this name, for example with the Let's Encrypt app from the App Center.

Warning

In this scenario the new Keycloak URL path must not be / to not override the global configuration of the web server.

8.2.2.1. Configuration of the identity provider#

To configure this scenario run the following steps on each Keycloak instance in your UCS domain.

$ FQDN="portal.example.test"
$ SSO_PATH="/auth"
$ ucr set keycloak/server/sso/fqdn="$FQDN"
$ ucr set keycloak/server/sso/path="$SSO_PATH"
$ ucr set keycloak/server/sso/virtualhost=false
$ ucr set keycloak/server/sso/autoregistration=false

$ univention-app configure keycloak

Warning

After changing the configuration of the identity provider with the previous steps, all services can’t use that identity provider until proper configuration.

8.2.2.2. Configuration of UMC as service provider#

To re-configure single sign-on for UMC on all UCS systems in the domain, run the following commands:

$ FQDN="portal.example.test"
$ SSO_PATH="/auth"
$ ucr set \
  umc/saml/idp-server="https://${FQDN}${SSO_PATH}/realms/ucs/protocol/saml/descriptor"
$ service slapd restart

For UCS systems joining the domain, configure a UCR policy and assign it the UCS systems before you install them. The UCR policy must set umc/saml/idp-server to your custom SAML IDP URL.

8.2.3. Official (Let's Encrypt) certificates for single sing-on#

If the single sing-on endpoint is exposed to the internet, usually an official certificate for the server is required. This can be achieved with the Let's Encrypt app (but it is not required to use this app to create the official certificate).

Note

The examples below assume the Let's Encrypt was used to create the certificate. The actual filenames of the certificate and key can differ depending on which mechanism was used to create the certificate.

8.2.3.1. Dedicated FQDN for single sing-on endpoint#

In case you use the Let's Encrypt app, you have to configure Let's Encrypt to acquire a certificate for both names, the UCS portal and Keycloak. Apply the following app settings for the Let's Encrypt app:

App setting

Value

Domain(s) to obtain a certificate for, separated by space

portal.extern.com auth.extern.com

Use certificate in Apache

yes

In this scenario the single sing-on endpoint has its own web server configuration, as web server virtual host. To configure the certificate files for Keycloak, set the following UCR variables:

Listing 8.1 Set UCR variables to use the Let’s Encrypt certificate#
$ cert_file="/etc/univention/letsencrypt/signed_chain.crt"
$ key_file="/etc/univention/letsencrypt/domain.key"
$ ucr set keycloak/apache2/ssl/certificate="$cert_file"
$ ucr set keycloak/apache2/ssl/key="$key_file"
$ systemctl reload apache2.service

8.2.3.2. Single sing-on FQDN identical to UCS Portal FQDN (or internal name)#

If you use the Let's Encrypt app to generate the certificates, you need the following app settings for Let's Encrypt:

App Setting

Value

Domain(s) to obtain a certificate for, separated by space

portal.extern.com

Use certificate in Apache

yes

In this use case, the Keycloak app uses the global web server configuration. You can therefore use the standard UCR variables for the Apache certificate files as outlined in Listing 8.2.

Listing 8.2 Assign certificates to web server configuration#
$ cert_file="/etc/univention/letsencrypt/signed_chain.crt"
$ key_file="/etc/univention/letsencrypt/domain.key"
$ ucr set apache2/ssl/certificate="$cert_file"
$ ucr set apache2/ssl/key="$key_file"
$ systemctl reload apache2.service
On this page