Univention Keycloak App

https://docs.software-univention.de/keycloak-app/latest/
Admin
The Univention Keycloak app installs Keycloak, an open-source software for single sign-on with...
Tokens:40,239
Snippets:172
Trust Score:5.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### 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=<username>
      The username for binding to the Keycloak administration interface.
      Example: --binduser=admin

    --bindpwdfile=<filepath>
      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
<SingleSignOnService
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
    Location="https://ad.example.com/adfs/ls/"/>
```

--------------------------------

### 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
<SingleSignOnService
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
    Location="https://ad.example.com/adfs/ls/"/>
```

--------------------------------

### 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 <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 `<database>`.* TO `<user>`@`<host>`;
```

--------------------------------

### 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 <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
<LocationMatch "^(/admin/|/realms/master/)">
              deny from all
              allow from 10.207.0.0/16
</LocationMatch>

# 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 <filepath>
  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 <url_to_sp_metadata>
  [--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 <filepath>
  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_application_url>
  [--client-secret]
  <client_id>
  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.
    <client_id>: 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 <language> <position> <label> <url>`
    -   `<language>`: The language code for the link (e.g., 'en', 'de').
    -   `<position>`: The display order of the link (1-12).
    -   `<label>`: The text displayed for the link.
    -   `<url>`: The URL the link points to.
    Example:
    `$ univention-keycloak login-links set en 1 "Link 1" "https://example.com/link1"`
    `$ univention-keycloak login-links set de 1 "Link 1" "https://example.com/link1"`

2.  **Modify Link**
    Syntax:
    `univention-keycloak login-links set <language> <position> <new_label> <new_url>`
    -   Updates an existing link at the specified position and language.
    Example:
    `$ univention-keycloak login-links set en 1 "Link 1 New" "https://example.com/link1_updated"`

3.  **Delete Link**
    Syntax:
    `univention-keycloak login-links delete <language> <position>`
    -   Removes a link at the specified position and language.
    Example:
    `$ univention-keycloak login-links delete en 2`

4.  **Get Configured Links**
    Syntax:
    `univention-keycloak login-links get <language>`
    -   Retrieves and displays all configured links for the given language.
    Example:
    `$ univention-keycloak login-links get en`

Note:
Up to 12 links can be managed. Changes are applied immediately.
```

--------------------------------

### Configure Keycloak App

Source: https://docs.software-univention.de/keycloak-app/latest/_sources/configuration

Command to manually configure the Keycloak application, which also triggers the import of CA certificates placed in the designated directory.

```console
univention-app configure keycloak
```

--------------------------------

### Keycloak LDAP Federation Configuration

Source: https://docs.software-univention.de/keycloak-app/latest/_sources/changelog

Details configuration options for LDAP federation within Keycloak, including connection pooling and StartTLS settings. Notes restrictions on combined usage.

```APIDOC
LDAP Federation Configuration:
  connectionPooling:
    - Description: Controls connection pooling for LDAP federation.
    - Allowed values: true, false
    - Default in UCS (when startTLS=true): false
  startTLS:
    - Description: Enables StartTLS for LDAP connections.
    - Allowed values: true, false
    - Default in UCS: true
  Note: connectionPooling=true is no longer allowed with startTLS=true.
```

--------------------------------

### Re-configure Keycloak Instance

Source: https://docs.software-univention.de/keycloak-app/latest/database

This command is used to apply pending configuration changes to an existing Keycloak instance after the domain-wide settings have been updated. It ensures that the Keycloak application uses the newly configured database connection details.

```bash
$ univention-app configure keycloak

```

--------------------------------

### Create Keycloak Authentication Flow

Source: https://docs.software-univention.de/keycloak-app/latest/configuration

Creates a new Keycloak authentication flow that includes the 'Univention App authenticator'. This authenticator performs authorization validation during user sign-in. The command does not produce any output upon successful execution.

```bash
$ univention-keycloak legacy-authentication-flow create

```

--------------------------------

### Create Keycloak Authentication Flow

Source: https://docs.software-univention.de/keycloak-app/latest/_sources/configuration

Creates a Keycloak authentication flow by copying an existing flow and replacing the Kerberos authenticator with a Keycloak sub flow that evaluates the client's IP address. The command copies the browser flow by default.

```console
$ univention-keycloak conditional-krb-authentication-flow create \
  --flow=REPLACE_WITH_THE_ORIGINAL_FLOW --name=REPLACE_WITH_THE_NEW_KERBEROS_FLOW_NAME \
  --allowed-ip=REPLACE_WITH_IPCIDRv4 --allowed-ip=REPLACE_WITH_IPCIDRv6
```

--------------------------------

### Configure Keycloak SSO FQDN and Path

Source: https://docs.software-univention.de/keycloak-app/latest/_sources/use-cases

Sets Univention Configuration Registry (UCR) variables for the Keycloak single sign-on (SSO) Fully Qualified Domain Name (FQDN) and path. It also configures the Keycloak application based on these settings.

```console
$ 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
```

--------------------------------

### Keycloak Apache Configuration

Source: https://docs.software-univention.de/keycloak-app/latest/configuration

Controls whether the UCS system creates an Apache configuration for Keycloak. Accepts 'true' or 'false' and is a required setting.

```APIDOC
keycloak/apache/config:
  Description: If set to 'true' (default) the UCS system will create an apache configuration for Keycloak.
  Possible values: true or false
  Required: Yes
  Default value: true
  Set: Installation and app configuration
```

--------------------------------

### Run Univention Join Scripts

Source: https://docs.software-univention.de/keycloak-app/latest/use-cases

Executes specific Univention join scripts, particularly for the management console web server, to apply configuration changes after updating UCR variables. The --force and --run-scripts flags ensure the script is applied.

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

```

--------------------------------

### Keycloak Docker Container Logs

Source: https://docs.software-univention.de/keycloak-app/latest/troubleshooting

Command to view log information from the Keycloak Docker container. This is useful for diagnosing issues specific to the Keycloak application running within its containerized environment.

```bash
$ univention-app logs keycloak
```

--------------------------------

### Configure UMC SAML IDP Server

Source: https://docs.software-univention.de/keycloak-app/latest/use-cases

Configures the UMC (Univention Management Console) to use the specified Keycloak instance as its SAML Identity Provider server. Requires restarting the LDAP server (slapd) for changes to take effect.

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

```
Tokens:
Raw