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
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
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 sign-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:
Use your preferred web browser and open the UCS portal under the just configured FQDN.
Sign in as user through single sign-on.
After sign-in through single-sign on, the browser redirects you as user back to the UMC portal.
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 Customize web server configuration for Keycloak 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:
You configured the external DNS entry for Keycloak, for example
sso.internet.domain.You configured the external DNS entry for the UCS portal, for example
portal.internet.domain.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.
For the proper setup, you must complete the steps in the following sections in the order shown:
8.2.1.1. Configuration of the identity provider#
Apply the steps to the following systems
Each Keycloak instance in your UCS domain
To configure single sign-on on each Keycloak instance in your UCS domain, follow the steps below:
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
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.
See also
For a reference of the used UCR variables, see the following resources:
8.2.1.2. Configuration of UMC as service provider#
Apply the steps to the following systems
UCS systems in the domain, where you want to enable single sign-on for UMC.
Before you continue here, make sure you did the steps outlined in Section 8.2.1.1.
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 Univention Portal to use external fully qualified domain name#
Apply the steps to the following systems
The UCS Primary Directory Node
All UCS systems in the domain, that expose the Univention Portal to the internet
Before you continue here, make sure you did the steps outlined in Section 8.2.1.2.
As an example use case to expose the UCS portal to the internet, follow the steps below. Apply the steps on all UCS systems that expose the Univention portal to the internet and also on the UCS Primary Directory Node.
Store the certificate files for the UCS portal in the following locations on your UCS system:
Certificate:
/etc/univention/ssl/$PORTAL_FQDN/cert.pemPrivate key for the certificate:
/etc/univention/ssl/$PORTAL_FQDN/private.key
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"
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 Univention 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:
You configured the external DNS entry for Keycloak, for example
portal.example.test.You have obtained proper SSL certificates for this name, for example with the Let's Encrypt app from the App Center.
For the proper setup, you must complete the steps in the following sections in the order shown:
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#
Apply the steps to the following systems
Each Keycloak instance in your UCS domain
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.
See also
For a reference of the used UCR variables, see the following resources:
8.2.2.2. Configuration of UMC as service provider#
Apply the steps to the following systems
UCS systems in the domain, where you want to enable single sign-on for UMC.
Before you continue here, make sure you did the steps outlined in Section 8.2.2.1.
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 sign-on#
If the single sign-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 sign-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 |
|
Use certificate in Apache |
|
In this scenario the single sign-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:
$ 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 sign-on FQDN identical to Univention 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 |
|
Use certificate in Apache |
|
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.9.
$ 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