### Install Keycloak with Custom Database Settings Source: https://docs.software-univention.de/keycloak-app/latest/_sources/database Demonstrates how to install the Keycloak application using the command line, specifying custom database connection details. This allows integration with alternative database backends like MariaDB during the initial setup. ```console $ univention-app install keycloak --set \ kc/db/url="jdbc:mariadb://database-server:3306/database-name" \ kc/db/password="database-password" \ kc/db/username="database-username" ``` -------------------------------- ### Install Keycloak with Custom Database (CLI) Source: https://docs.software-univention.de/keycloak-app/latest/database This command installs the Keycloak app with custom database settings during the initial setup. It uses command-line arguments to specify the database URL, username, and password, allowing integration with external databases like MariaDB. ```bash $ univention-app install keycloak --set \ kc/db/url="jdbc:mariadb://database-server:3306/database-name" \ kc/db/password="database-password" \ kc/db/username="database-username" ``` -------------------------------- ### Install Keycloak App (Custom Settings) Source: https://docs.software-univention.de/keycloak-app/latest/installation Installs the Keycloak application on UCS, allowing custom settings to be passed during the installation process. Settings are provided in the format $SETTING_KEY=$SETTING_VALUE. Some settings cannot be changed after installation, so they should be configured beforehand. ```shell $ univention-app install --set $SETTING_KEY=$SETTING_VALUE keycloak ``` -------------------------------- ### Install Keycloak App (Default Settings) Source: https://docs.software-univention.de/keycloak-app/latest/installation Installs the Keycloak application on UCS using default configuration settings. This is the simplest method for a standard installation. ```shell $ univention-app install keycloak ``` -------------------------------- ### Install Keycloak with default settings Source: https://docs.software-univention.de/keycloak-app/latest/_sources/installation Installs the Keycloak application on a UCS system using default configuration parameters via the Univention App Center command-line interface. This is the simplest method for initial deployment. ```console $ univention-app install keycloak ``` -------------------------------- ### Install Keycloak with custom settings Source: https://docs.software-univention.de/keycloak-app/latest/_sources/installation Installs the Keycloak application on a UCS system, allowing custom settings to be applied during the installation process. Settings are passed as key-value pairs using the --set option. ```console $ univention-app install --set $SETTING_KEY=$SETTING_VALUE keycloak ``` -------------------------------- ### Initialize Keycloak Configuration Source: https://docs.software-univention.de/keycloak-app/latest/_sources/installation Initializes the Keycloak application's configuration on a UCS system. This command is used after the first installation or to re-create the initial configuration after a factory reset. It requires administrative credentials. ```APIDOC univention-keycloak init Initializes the Keycloak application configuration. This command is used to create the initial administrative user and realm for Keycloak. It should be run after the first installation or after a factory reset. Prerequisites: - The Keycloak application must be installed on the UCS system. - Administrative credentials for Keycloak must be available (e.g., from /etc/keycloak.secret). Parameters: --binduser= The username for binding to the Keycloak administration interface. Example: --binduser=admin --bindpwdfile= The path to a file containing the password for the bind user. Example: --bindpwdfile=/etc/keycloak.secret Usage Example: $ univention-keycloak --binduser=admin --bindpwdfile=/etc/keycloak.secret init Returns: Upon successful initialization, Keycloak is configured with a default 'UCS' realm and an 'admin' user. Error Conditions: - If the Keycloak application is not running or not installed. - If the specified bind user or password file is invalid or inaccessible. - If the initial configuration already exists and is not being reset. ``` -------------------------------- ### Keycloak Database Configuration Options Source: https://docs.software-univention.de/keycloak-app/latest/database Details the settings available for configuring the database backend for the Keycloak app. These settings dictate how Keycloak connects to the database, not the database setup itself. ```APIDOC KeycloakAppDatabaseSettings: # Settings for configuring the database backend for the Keycloak app. # These settings only tell Keycloak where and how to connect to the database. # Ensure that you first perform the needed changes on the database itself. # Example settings (actual names may vary based on app configuration interface): # DB_VENDOR: "postgresql" # DB_HOST: "your_db_host" # DB_PORT: "5432" # DB_DATABASE: "keycloakdb" # DB_USERNAME: "keycloak_user" # DB_PASSWORD: "your_secure_password" # Supported databases are listed in the official Keycloak documentation. # Note: The custom Keycloak App image does not contain drivers for Oracle Database. # Using Oracle Database as a backend for Keycloak is not supported by this app. # Related Information: # - Refer to the [Settings](configuration.html#app-settings) section for available app settings. # - Consult [Supported databases](https://www.keycloak.org/server/db) in official Keycloak documentation for compatibility. # - For database replication and failover, a database cluster setup is required. ``` -------------------------------- ### Ad Hoc Provisioning Configuration Steps Source: https://docs.software-univention.de/keycloak-app/latest/_sources/ad-hoc-provisioning This section outlines the sequence of steps required to configure Keycloak for ad hoc provisioning and federation with external IAM systems. The steps are presented in a specific order to ensure proper setup and integration. ```APIDOC Federation Setup Steps: 1. Import external CA certificates for trust establishment. 2. Sign in to the Keycloak Admin Console. 3. Create a custom authentication flow. 4. Configure the external IAM system (e.g., ADFS). 5. Create an Identity Provider (IdP) in Keycloak. 6. Configure mappers for user attribute synchronization. ``` -------------------------------- ### Manage Keycloak Login Links Source: https://docs.software-univention.de/keycloak-app/latest/_sources/configuration Provides examples of using the `univention-keycloak` command-line tool to add, modify, and delete links displayed below the Keycloak login dialog. Supports multiple languages. ```console $ univention-keycloak login-links set en 1 "Link 1" "Link 1 description" $ univention-keycloak login-links set en 2 "Link 2" "Link 2 description" $ univention-keycloak login-links set de 1 "Link 1" "Beschreibung von 1" $ univention-keycloak login-links set de 2 "Link 2" "Beschreibung von 2" ``` ```console $ univention-keycloak login-links set en 1 "Link 1 new" "Link 1 new description" $ univention-keycloak login-links delete en 2 ``` ```console $ univention-keycloak login-links get en ``` -------------------------------- ### Keycloak Java Options Configuration Source: https://docs.software-univention.de/keycloak-app/latest/configuration Defines the options that the Keycloak app appends to the 'java' command. This is a required setting for installation and app configuration. ```APIDOC keycloak/java/opts: Description: Defines the options that the Keycloak app appends to the *java* command. Required: Yes Default value: -server -Xms1024m -Xmx1024m Set: Installation and app configuration ``` -------------------------------- ### Get Keycloak SAML SP Clients (Console) Source: https://docs.software-univention.de/keycloak-app/latest/_sources/configuration Retrieves a JSON list of all configured Keycloak SAML Service Providers (SP) associated with Univention Portal servers. This command helps in verifying existing SP registrations. ```console $ univention-keycloak saml/sp get --json ``` -------------------------------- ### SAML Metadata Single Sign-On Service URL Example Source: https://docs.software-univention.de/keycloak-app/latest/_sources/ad-hoc-provisioning Example XML snippet showing the SingleSignOnService element within SAML metadata. This is used to configure the Single Sign-On Service URL for the identity provider. ```xml ``` -------------------------------- ### Download OIDC Metadata Configuration Source: https://docs.software-univention.de/keycloak-app/latest/_sources/installation Retrieves the OpenID Endpoint Configuration document for Keycloak. This URL can be used by services to automatically configure OIDC authentication. ```shell $ wget "$(univention-keycloak get-keycloak-base-url)/realms/ucs/.well-known/openid-configuration" ``` -------------------------------- ### Download SAML 2.0 Identity Provider Metadata Source: https://docs.software-univention.de/keycloak-app/latest/_sources/installation Retrieves the SAML 2.0 Identity Provider Metadata document for Keycloak. This URL can be used by services to automatically configure SAML authentication. ```shell $ wget "$(univention-keycloak get-keycloak-base-url)/realms/ucs/protocol/saml/descriptor" ``` -------------------------------- ### SAML Metadata Example for Single Sign-On Service URL Source: https://docs.software-univention.de/keycloak-app/latest/ad-hoc-provisioning This XML snippet illustrates the SingleSignOnService element found within SAML metadata. It specifies the binding type (HTTP-Redirect) and the location of the Single Sign-On service URL, crucial for establishing federated login between Keycloak and Active Directory Federation Services. ```xml ``` -------------------------------- ### External FQDN Configuration Steps Source: https://docs.software-univention.de/keycloak-app/latest/use-cases Outlines the sequence of configuration steps required for setting up an external FQDN for single sign-on in UCS, involving the identity provider, UMC as a service provider, and the Univention Portal. ```APIDOC External FQDN Configuration Workflow: 1. Configuration of the identity provider (Section 9.2.1.1) 2. Configuration of UMC as service provider (Section 9.2.1.2) 3. Configuration of Univention Portal to use external fully qualified domain name (Section 9.2.1.3) ``` -------------------------------- ### Create Keycloak SAML SP Client (Console) Source: https://docs.software-univention.de/keycloak-app/latest/_sources/configuration Creates a new Keycloak SAML Service Provider (SP) client for a specific Univention Portal server. It requires the server's FQDN to construct the metadata URL and uses `--umc-uid-mapper` for user attribute mapping. ```console $ FQDN="the fqdn of the Univention Portal server" $ univention-keycloak saml/sp create \ --metadata-url="https://$FQDN/univention/saml/metadata" \ --umc-uid-mapper ``` -------------------------------- ### Initialize Keycloak Configuration (Factory Reset) Source: https://docs.software-univention.de/keycloak-app/latest/installation Creates the initial configuration for the Keycloak app or performs a factory reset by deleting the 'UCS' realm and re-initializing. This command requires administrative credentials and the path to the secret file. ```shell $ univention-keycloak --binduser=admin --bindpwdfile=/etc/keycloak.secret init ``` -------------------------------- ### Keycloak Log Level Configuration Source: https://docs.software-univention.de/keycloak-app/latest/configuration Configures the verbosity of log messages in Keycloak. It accepts predefined log levels and is a required setting for installation and app configuration. ```APIDOC keycloak/log/level: Description: Configures the verbosity of log messages in Keycloak. Possible values: ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARN. Required: Yes Default value: INFO Set: Installation and app configuration ``` -------------------------------- ### Manage Keycloak SAML Service Providers (SP) Source: https://docs.software-univention.de/keycloak-app/latest/configuration Provides commands for interacting with Keycloak's SAML Service Provider (SP) configurations for Univention Portal servers. It allows listing existing SPs and creating new ones, ensuring each portal instance is registered with Keycloak. ```APIDOC univention-keycloak saml/sp get --json - Description: Retrieves a JSON array of all registered SAML SP metadata URLs for Univention Portal instances. - Returns: A JSON array of strings, where each string is a metadata URL. univention-keycloak saml/sp create --metadata-url [--umc-uid-mapper] - Description: Creates a new SAML SP client in Keycloak for a Univention Portal server. - Parameters: - --metadata-url: The URL to the SAML metadata of the Univention Portal server. Example: "https://ucs1.example.com/univention/saml/metadata". - --umc-uid-mapper: Optional flag to enable UID mapping for user attribute import. - Example: $ FQDN="the fqdn of the Univention Portal server" $ univention-keycloak saml/sp create \ --metadata-url="https://$FQDN/univention/saml/metadata" \ --umc-uid-mapper ``` -------------------------------- ### univention-keycloak OIDC Commands Source: https://docs.software-univention.de/keycloak-app/latest/configuration Demonstrates using the univention-keycloak command-line tool for OpenID Connect (OIDC) operations. Includes fetching OIDC provider certificates and creating OIDC relying parties (RPs). ```shell $ 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}" ``` -------------------------------- ### Grant Database Privileges for Keycloak Source: https://docs.software-univention.de/keycloak-app/latest/_sources/database Specifies the minimum SQL privileges required for a database user to operate with Keycloak in a single-machine setup. This ensures the Keycloak server can perform necessary database operations. ```sql GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, REFERENCES, INDEX, DROP ON ``.* TO ``@``; ``` -------------------------------- ### univention-keycloak CLI Tool Source: https://docs.software-univention.de/keycloak-app/latest/changelog The univention-keycloak command-line program simplifies the integration of client applications with Keycloak. It allows direct creation of Keycloak Client configurations for SAML Service Providers (SPs) and OpenID Connect Relying Parties (RPs), as well as managing signing certificates and setting up Two-Factor Authentication (2FA). ```APIDOC univention-keycloak Description: A command-line utility for configuring Keycloak clients and authentication flows within the Univention Corporate Server (UCS) environment. Key Functionalities: - Client Configuration: Create and manage Keycloak client configurations for SAML SPs and OIDC RPs. - Certificate Management: Download signing certificates (e.g., PEM format) for SAML IDP and OIDC OP. - 2FA Setup: Configure Time-based One-Time Password (TOTP) for two-factor authentication for members of specific LDAP groups. Usage Examples: # Configure a SAML SP client univention-keycloak saml create-sp --realm myrealm --clientid my-saml-sp --entityid http://localhost:8080/simplesaml/saml2/sp/metadata.php # Download SAML IDP signing certificate univention-keycloak saml idp-cert --realm myrealm --output cert.pem # Configure OIDC RP client univention-keycloak oidc create-rp --realm myrealm --clientid my-oidc-rp --redirecturis http://localhost:3000/callback # Setup 2FA for a group univention-keycloak 2fa setup-group --group "2FA-Users" --realm myrealm Parameters: The tool supports various subcommands and options for detailed configuration. Specific parameters include: - realm: The Keycloak realm to operate on. - clientid: The identifier for the client. - entityid: The SAML Entity ID for the SP. - redirecturis: Allowed redirect URIs for OIDC RPs. - group: The LDAP group name for 2FA configuration. - output: Path to save downloaded certificates. Related Commands: - univention-keycloak saml create-sp: Creates a SAML Service Provider client. - univention-keycloak saml idp-cert: Downloads the SAML Identity Provider signing certificate. - univention-keycloak oidc create-rp: Creates an OpenID Connect Relying Party client. - univention-keycloak 2fa setup-group: Configures TOTP 2FA for members of a specified LDAP group. Notes: - The exact command syntax and available options may vary slightly between versions. - Refer to the official Keycloak and Univention documentation for comprehensive details and advanced configurations. ``` -------------------------------- ### Configure Keycloak Domain Database Settings Source: https://docs.software-univention.de/keycloak-app/latest/_sources/database This command updates the domain-wide database configuration for the Keycloak app. It requires specifying the database username, URI, password, driver class, and a ping data type. These settings are used by subsequent installations. ```console $ univention-keycloak domain-config \ --set username="database-username" \ --set uri="jdbc:mariadb://database-server:3306/database-name" \ --set password="database-password" \ --set driver="org.mariadb.jdbc.Driver" \ --set ping_datatype="VARBINARY(255)" ``` -------------------------------- ### Keycloak SAML Commands Source: https://docs.software-univention.de/keycloak-app/latest/_sources/configuration Provides commands for managing Keycloak SAML Service Providers (SP) within the Univention ecosystem. This includes retrieving existing SP configurations and creating new ones for Univention Portal servers. ```APIDOC univention-keycloak saml/sp get --json - Retrieves a JSON array of SAML SP metadata URLs. - Use case: Verify existing SP configurations. univention-keycloak saml/sp create --metadata-url [--umc-uid-mapper] - Creates a new SAML SP client in Keycloak. - Parameters: --metadata-url: The URL to the SAML metadata of the SP. --umc-uid-mapper: Optional flag to enable UMC user ID mapping. - Use case: Register a new Univention Portal server with Keycloak. ``` -------------------------------- ### Configure SAML IDP Server (Console) Source: https://docs.software-univention.de/keycloak-app/latest/_sources/configuration Sets the Univention Configuration Registry variable `umc/saml/idp-server` to point the Univention Portal to the Keycloak SAML descriptor URL. This is a prerequisite for enabling SAML authentication. The command dynamically includes the domain name. ```console $ ucr set \ umc/saml/idp-server=\"https://ucs-sso-ng.$(hostname -d)/realms/ucs/protocol/saml/descriptor\" ``` -------------------------------- ### Add Kerberos SPN for Keycloak Source: https://docs.software-univention.de/keycloak-app/latest/_sources/configuration These commands are used to ensure Kerberos authentication works correctly with the Active Directory-compatible Domain Controller app, especially when Keycloak is installed after the DC. It adds the necessary Service Principal Name (SPN) for the Keycloak server. ```console eval "$(ucr shell keycloak/server/sso/fqdn)" samba-tool spn add "HTTP/$keycloak_server_sso_fqdn" "krbkeycloak" ``` ```console fqdn="$(ucr get ucs/server/sso/uri | sed -e 's,https://,,' -e 's,/.*,,')" samba-tool spn add "HTTP/$fqdn" "krbkeycloak" ``` -------------------------------- ### Fetch OIDC Metadata using wget Source: https://docs.software-univention.de/keycloak-app/latest/installation Downloads the OpenID Connect (OIDC) metadata discovery document for the Keycloak realm. This command requires the 'wget' utility and the base URL of the Keycloak instance. The output is the OIDC configuration file, which can be used by services to automatically configure OIDC authentication. ```shell wget "$(univention-keycloak get-keycloak-base-url)/realms/ucs/.well-known/openid-configuration" ``` -------------------------------- ### Univention Keycloak CLI for Client Configuration Source: https://docs.software-univention.de/keycloak-app/latest/_sources/changelog The univention-keycloak command-line program simplifies the creation of Keycloak client configurations for SAML Service Providers (SP) and OpenID Connect Relying Parties (RP). It also supports downloading signing certificates. ```APIDOC univention-keycloak Description: Command line program to configure Keycloak clients for SAML SP and OIDC RP. Features: - Create Keycloak Client configurations for SAML Service Providers (SAML SP). - Create Keycloak Client configurations for OpenID Connect Relying Parties (OIDC RP). - Download signing certificates (e.g., as PEM file). - Supports setup of 2FA authentication flow for specific LDAP groups using TOTP. Usage Examples: # Example for SAML SP configuration (details not provided in source) univention-keycloak saml/idp/cert # Example for OIDC RP configuration (details not provided in source) univention-keycloak oidc/op/cert Related Commands/Features: - SAML SP integration - OIDC Provider integration - TOTP 2FA setup ``` -------------------------------- ### Customize Keycloak Web Server Configuration Source: https://docs.software-univention.de/keycloak-app/latest/configuration This snippet shows how to customize the Apache HTTP web server configuration for Keycloak by creating a local configuration file. It provides an example of restricting access to the Keycloak Admin Console to specific IP subnets and the commands to validate and reload the Apache configuration. ```shell deny from all allow from 10.207.0.0/16 # To activate the configuration: # 1. Validate configuration: $ apachectl configtest Syntax OK # 2. Restart Apache to apply changes: $ service apache2 restart ``` -------------------------------- ### univention-keycloak SAML Commands Source: https://docs.software-univention.de/keycloak-app/latest/configuration Illustrates using the univention-keycloak command-line tool for Security Assertion Markup Language (SAML) operations. Covers retrieving SAML IDP certificates and creating SAML service providers (SPs). ```shell $ 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" ``` -------------------------------- ### Run Univention Join Script Source: https://docs.software-univention.de/keycloak-app/latest/_sources/use-cases Executes a specific Univention join script to update the web server configuration. This script is essential for applying certain system-level changes. ```console $ univention-run-join-scripts \ --force \ --run-scripts 92univention-management-console-web-server.inst ``` -------------------------------- ### Keycloak SPI Plugin for Univention Source: https://docs.software-univention.de/keycloak-app/latest/_sources/ad-hoc-provisioning The Keycloak application installs the 'univention-authenticator' Service Provider Interface (SPI) plugin. This plugin facilitates ad hoc provisioning by automatically creating user accounts in the OpenLDAP directory through the REST API of |UDM| when users authenticate from external IAM systems. ```APIDOC univention-authenticator SPI Plugin: Purpose: Facilitates ad hoc user provisioning in Keycloak. Functionality: Automatically creates user accounts in OpenLDAP via UDM REST API for federated users. Context: Used in UCS appliance and Nubus for Kubernetes deployments. Dependencies: Keycloak app, UDM REST API. ``` -------------------------------- ### Fetch SAML Metadata using wget Source: https://docs.software-univention.de/keycloak-app/latest/installation Downloads the SAML 2.0 Identity Provider Metadata descriptor for the Keycloak realm. This command requires the 'wget' utility and the base URL of the Keycloak instance. The output is the SAML metadata file, which can be used by services to automatically configure SAML authentication. ```shell wget "$(univention-keycloak get-keycloak-base-url)/realms/ucs/protocol/saml/descriptor" ``` -------------------------------- ### Keycloak Application Backup and Restore Source: https://docs.software-univention.de/keycloak-app/latest/_sources/configuration Commands for performing backup and restore operations for the Keycloak application data, including realms, clients, groups, and roles. The export action creates a backup, and the import action restores it. ```console $ univention-app shell keycloak /opt/keycloak/bin/kc.sh export \ --db=$(ucr get kc/db/kind) \ --db-driver=$(ucr get kc/db/driver) \ --transaction-xa-enabled=$(ucr get kc/db/xa) \ --dir /var/lib/univention-appcenter/apps/keycloak/data/myexport # Creates a backup of Keycloak data into the specified directory 'myexport'. ``` ```console $ univention-app shell keycloak /opt/keycloak/bin/kc.sh import \ --db=$(ucr get kc/db/kind) \ --db-driver=$(ucr get kc/db/driver) \ --transaction-xa-enabled=$(ucr get kc/db/xa) \ --dir /var/lib/univention-appcenter/apps/keycloak/data/myexport # Restores Keycloak data from the specified directory 'myexport'. ``` -------------------------------- ### Keycloak Backup and Restore Source: https://docs.software-univention.de/keycloak-app/latest/configuration Provides commands for backing up and restoring Keycloak application data, including realms, clients, groups, and roles. Uses the kc.sh script for export and import operations. ```shell $ univention-app shell keycloak /opt/keycloak/bin/kc.sh export \ --db=$(ucr get kc/db/kind) \ --db-driver=$(ucr get kc/db/driver) \ --transaction-xa-enabled=$(ucr get kc/db/xa) \ --dir /var/lib/univention-appcenter/apps/keycloak/data/myexport $ univention-app shell keycloak /opt/keycloak/bin/kc.sh import \ --db=$(ucr get kc/db/kind) \ --db-driver=$(ucr get kc/db/driver) \ --transaction-xa-enabled=$(ucr get kc/db/xa) \ --dir /var/lib/univention-appcenter/apps/keycloak/data/myexport ``` -------------------------------- ### Configure Keycloak App Source: https://docs.software-univention.de/keycloak-app/latest/configuration This command initiates the configuration process for the Keycloak application. During this process, any CA certificates placed in the designated directory will be automatically imported into Keycloak's trust store. ```bash $ univention-app configure keycloak ``` -------------------------------- ### List PEM Certificates in CA Directory Source: https://docs.software-univention.de/keycloak-app/latest/configuration This command demonstrates how to verify that CA certificate files are correctly placed in the designated directory. It uses the 'file' utility to inspect the content of all files ending with '.pem' within the specified path. ```bash $ file /var/lib/univention-appcenter/apps/keycloak/conf/ca-certificates/*.pem .../keycloak/conf/ca-certificates/cert1.pem: PEM certificate .../keycloak/conf/ca-certificates/cert2.pem: PEM certificate ``` -------------------------------- ### Enable SAML Login for Univention Portal Source: https://docs.software-univention.de/keycloak-app/latest/configuration Configures the Univention Portal to use SAML for user authentication. This involves enabling the `login-saml` entry in the portal configuration. The change can be applied through the UMC interface or by using the `udm` command-line tool. ```UMC In the UCS management system, go to Domain ‣ Portal ‣ login-saml. On the *General* tab, under the *Advanced* section, activate the `Activated` checkbox. ``` ```Console $ udm portals/entry modify \ --dn \"cn=login-saml,cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)\" \ --set activated=TRUE ``` -------------------------------- ### Configure Keycloak SSO FQDN and SSL Source: https://docs.software-univention.de/keycloak-app/latest/_sources/use-cases Sets the Keycloak SSO FQDN, disables autoregistration, configures SSL certificate paths for Apache2, and updates the Content Security Policy (CSP) frame-ancestors. It also applies the configuration changes. ```console $ 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 ``` -------------------------------- ### Configure Keycloak Apache SSL with Let's Encrypt Source: https://docs.software-univention.de/keycloak-app/latest/_sources/use-cases Sets UCR variables for Keycloak's Apache virtual host to use Let's Encrypt certificates. It defines paths for the certificate and key files and reloads the Apache service to apply changes. ```console $ 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 ``` -------------------------------- ### Validate and Restart Apache Web Server Source: https://docs.software-univention.de/keycloak-app/latest/_sources/configuration These commands are used to validate the Apache web server configuration for syntax errors and then restart the service to apply any custom changes. The validation step is crucial as Apache may terminate without clear error messages on configuration issues. ```console $ apachectl configtest Syntax OK ``` ```console $ service apache2 restart ``` -------------------------------- ### Assign Let's Encrypt Certificates to Global Apache Config Source: https://docs.software-univention.de/keycloak-app/latest/_sources/use-cases Assigns Let's Encrypt certificates to the global Apache web server configuration. It sets UCR variables for the certificate and key file paths and reloads Apache to activate the new configuration. ```console $ 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 ``` -------------------------------- ### Keycloak Cookie and Server Path Settings Source: https://docs.software-univention.de/keycloak-app/latest/configuration Configuration parameters related to Keycloak's cookie handling and server path settings. This includes the SameSite attribute for cookies and the path used to access Keycloak. ```APIDOC keycloak/cookies/samesite: Description: This setting sets the SameSite attribute in all the cookies of Keycloak. Possible values are Lax, Strict and the default value None. Default value: `None` Required: No Set: Installation and app configuration keycloak/server/sso/path: Description: This setting sets the path used to access Keycloak at the end of the Keycloak URL. If this setting deviates from the default, you need to set this setting via UCR on all UCS servers in the domain, so that these servers can connect to Keycloak. Default value: `/` Required: No Set: Installation and app configuration ``` -------------------------------- ### Configure Keycloak Domain Database Settings Source: https://docs.software-univention.de/keycloak-app/latest/database This command updates the domain-wide database configuration for existing Keycloak instances. It allows setting the database username, URI, password, JDBC driver, and a ping datatype, which are crucial for Keycloak's database connectivity. ```bash $ univention-keycloak domain-config \ --set username="database-username" \ --set uri="jdbc:mariadb://database-server:3306/database-name" \ --set password="database-password" \ --set driver="org.mariadb.jdbc.Driver" \ --set ping_datatype="VARBINARY(255)" ``` -------------------------------- ### Univention Keycloak CLI for Client Configuration Source: https://docs.software-univention.de/keycloak-app/latest/_sources/limitations The 'univention-keycloak' command-line tool allows administrators to create SAML or OIDC clients. It provides flexibility to adjust generic client configurations or use the Keycloak Admin Console for specific settings. ```APIDOC univention-keycloak Description: Command-line tool for managing Keycloak clients. Functionality: - Create SAML clients - Create OIDC clients - Adjust generic client configurations Usage: Administrators can use this tool to programmatically configure clients. For specific or advanced configurations, the Keycloak Admin Console is also available. Related: - Keycloak Admin Console ``` -------------------------------- ### Configure Keycloak as SAML Identity Provider (SAML SP) Source: https://docs.software-univention.de/keycloak-app/latest/_sources/configuration Instructions and commands for configuring Keycloak to act as a SAML Identity Provider (IDP) and setting up a Service Provider (SP) client. This includes retrieving SAML IDP certificates and creating SAML SP client configurations. ```APIDOC univention-keycloak saml/idp/cert get --as-pem --output Description: Retrieves the SAML Identity Provider's signing certificate. Parameters: --as-pem: Output the certificate in PEM format. --output: Specifies the file path to save the certificate. Example: $ univention-keycloak saml/idp/cert get \ --as-pem --output "$SOMEFILENAME" univention-keycloak saml/sp create --metadata-url [--client-signature-required] Description: Creates a new client configuration for a SAML Service Provider (SP). Parameters: --metadata-url: The URL pointing to the Service Provider's metadata. --client-signature-required: (Optional) Specifies if client signature is required. Example: $ univention-keycloak saml/sp create \ --metadata-url "https://$(hostname -f)/$METADATA-URL-OF-THE-APP" ``` -------------------------------- ### Configure Keycloak as OpenID Connect Provider (OIDC RP) Source: https://docs.software-univention.de/keycloak-app/latest/_sources/configuration Instructions and commands for configuring Keycloak to act as an OpenID Connect provider and setting up a relying party (RP) client. This involves retrieving OIDC provider certificates and creating client configurations. ```APIDOC univention-keycloak oidc/op/cert get --as-pem --output Description: Retrieves the OpenID Connect provider's public certificate. Parameters: --as-pem: Output the certificate in PEM format. --output: Specifies the file path to save the certificate. Example: $ univention-keycloak oidc/op/cert get \ --as-pem \ --output "$SOMEFILENAME" univention-keycloak oidc/rp create --app-url [--client-secret] Description: Creates a new client configuration for an OpenID Connect Relying Party (RP). Parameters: --app-url: The root URL of the client application (OIDC RP). --client-secret: (Optional) The client secret for confidential clients. : The unique identifier for the client application. Example: $ univention-keycloak oidc/rp create \ --app-url="https://$(hostname -f)/${MYAPP_URL}/" "${MYAPP_CLIENT_ID}" ``` -------------------------------- ### Configure UCS Portal FQDN and Certificates Source: https://docs.software-univention.de/keycloak-app/latest/_sources/use-cases Configures UCR variables for the UCS portal's FQDN and associates it with the correct SSL certificate and private key files. This step is crucial for exposing the UCS portal securely over the internet with a custom domain. ```console $ 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" ``` -------------------------------- ### Enable SAML Login for Portal (Console) Source: https://docs.software-univention.de/keycloak-app/latest/_sources/configuration Modifies the Univention Portal configuration to use SAML for login by setting the `activated` attribute to `TRUE`. This command targets the `login-saml` entry in the LDAP directory. It requires root privileges. ```console $ udm portals/entry modify \ --dn \"cn=login-saml,cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)\" \ --set activated=TRUE ``` -------------------------------- ### Configure Keycloak SSO FQDN and SSL Source: https://docs.software-univention.de/keycloak-app/latest/use-cases Sets the single sign-on FQDN for Keycloak, configures autoregistration, specifies SSL certificate and key paths, and updates the Content Security Policy (CSP) frame-ancestors. It also applies the Keycloak app configuration. ```shell $ 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 ``` -------------------------------- ### Keycloak Debugging Configuration Source: https://docs.software-univention.de/keycloak-app/latest/troubleshooting Instructions on how to increase the log level for the Keycloak app to gather more detailed debugging information. This involves setting an environment variable for the Docker container. ```text To increase the log level for more log information for the **Keycloak** app, see [`keycloak/log/level`](configuration.html#envvar-keycloak-log-level). This log level only affects the log information that Keycloak itself generates and writes to the Docker logs. The App Center sets the Docker container’s `KEYCLOAK_LOGLEVEL` environment variable to the value of [`keycloak/log/level`](configuration.html#envvar-keycloak-log-level). ``` -------------------------------- ### Manage Keycloak Login Page Links Source: https://docs.software-univention.de/keycloak-app/latest/configuration This API documentation covers the `univention-keycloak login-links` command for managing additional links displayed below the login dialog. It includes operations for setting new links, modifying existing ones, deleting links, and retrieving configured links for a specific language. ```APIDOC univention-keycloak login-links Description: Manages additional links displayed below the Keycloak login dialog. Commands: 1. **Set/Add Link** Syntax: `univention-keycloak login-links set