Navigating the Keycloak Admin Console with Nubus: A Step-by-Step Introduction

Keycloak makes managing user access in Nubus straightforward with a centralized Single Sign-On (SSO) solution. Once logged in to the Keycloak Identity Provider (IdP), end users can seamlessly access all connected web applications. This article covers the main features of the Keycloak Admin Console to help you get started with centralized authentication management.

Thanks to Web Single Sign-On (SSO), users only need to log in once to the Identity Provider (IdP) and can then access all connected apps without any extra logins—saving time and cutting down on frustration. For you as an admin, standardized protocols handle secure authentication and authorization, keeping passwords safe and sound in your own identity management system.

That’s where Keycloak comes in. It’s an Open Source Identity and Access Management (IAM) solution that simplifies centralized user management and secure login processes. In our previous article, Univention-App-Highlights: Secure and Centralized Authentication with Keycloak, we walked you through installing the Keycloak app in your Nubus environment and setting up the basics. You’ll also find a step-by-step guide and helpful tips for migrating from SimpleSAMLphp and Kopano Konnect, which have been the default IdPs in UCS up until now. Whether your Nubus is running on a traditional UCS or is set to move into a Kubernetes cluster, the Keycloak app has you covered.

In this article, I’d like to walk you through the Keycloak Admin Console. At first glance, it might seem a bit overwhelming—especially if you’re used to SAML and aren’t yet familiar with the OAuth/OIDC lingo. But don’t worry, we’ll break down the key features and menu options step-by-step, making sure you get comfortable with it in no time.

After logging in through the Keycloak tile in the portal, you’ll first enter the standard realm. This area contains all the general settings and configurations for Keycloak. But as an admin, the most important realm for you is the ucs realm—a dedicated space tailored specifically for Univention Corporate Server. To switch over, just select it from the small drop-down menu at the top left.

Selecting the UCS-specific Configuration Area

Through the left navigation bar, you’ll find your way to the realm settings. This is where you configure everything specific to the Nubus integration in your Keycloak setup. Right on the first tab, General, you’ll see two important links under Endpoints:

• URL to fetch XML metadata for the Keycloak SAML IdP: This metadata contains the unique ID of the IdP (Entity ID), endpoints for authentication or logout requests, and the certificates used to encrypt and sign SAML communications between the IdP and SP.
• Standardized .well-known URI with the OpenID Connect Provider configuration: This is where you’ll find configuration details for clients, like endpoints for authentication, token exchange, supported scopes, and cryptographic keys.

You’ll need these URLs to connect your services as a SAML Service Provider or OpenID Connect Relying Party to Keycloak. The trust between an IdP and its connected services is established by exchanging and storing this metadata in the configuration of each party involved. Depending on your needs, share these links with the corresponding service to complete the setup.

One essential configuration area in the Keycloak Admin Console is the User Federation section, where you set up the identity sources for your environment. You’ll see that the UCS directory service is already connected and acts as the backend for user accounts, with Keycloak delegating the authentication process to it.

If Keycloak needs to share specific user attributes with connected services, these attributes must be configured within Keycloak itself. Out of the box, standard attributes like first name, last name, and email are already included. Should your services require additional fields, you can easily add them through the Mappers tab. Just click Add Mapper, select user-attribute-ldap-mapper as the type, and complete the form to extend the attribute set with the fields your services need.

Mapping an LDAP Attribute in Keycloak

The Clients section is likely where you’ll spend a good deal of your time. It provides an overview of all the connected applications, whether they’re SAML Service Providers or OpenID Connect Relying Parties. A single click on any entry will take you directly to the configuration page of the respective client.

To connect a new application, simply click Create Client and complete the form. You can also import XML or JSON metadata—making it quick and easy to set up new clients without a lot of manual configuration. Existing client configurations can be exported here as well, either for backup purposes or to transfer them to another environment.

Our Keycloak app already comes with pre-configured SAML client entries for all portal servers in your UCS domain. A join script ensures that the Keycloak IdP metadata needed for portal logins is stored in the filesystem. With just a few clicks or commands, you can switch the UCS portal configuration to use the new IdP.

If you encounter any issues or need more information on SAML assertions, take a look at the log file located at /var/log/syslog (also see the “Troubleshooting and Best Practices” section).

Right below the Clients section, you’ll find Client Scopes, where you can set permissions and access rights for clients in your UCS realm. In the OAuth and OIDC world, a “scope” is basically a collection of related claims (attributes) that are typically bundled together. For example, the email scope usually includes two claims: the user’s email address and a flag indicating if the email has been verified. By grouping claims this way, scopes help control which attributes can be requested or shared with a client.

You’ll also notice a column called Assigned Type in the list of available scopes. This setting controls if a scope is handed out by default to all clients (Default), never issued at all (None), or only sent when specifically requested by a client (Optional). It’s a powerful way to fine-tune how Keycloak shares user information with different applications, helping you keep data exposure in check.

But that’s not all—Keycloak lets you assign specific scopes to individual clients. Once you’ve defined a scope and set its global default behavior under Client Scopes, you can tailor those settings for each client. Just go to Clients, pick the application you want to configure, and switch to the Client Scopes tab. There, you’ll see a list of all globally defined scopes, and you can choose which ones should be enabled for that specific client.

Quick heads-up: You might come across some UCR variables starting with keycloak or kc. But don’t go changing those just yet—they’re used by the UCS system outside the container. For any configurations inside the Keycloak container, stick with the command-line tools we’ll cover here. There are two main tools you’ll use to manage the Keycloak app: univention-app configure keycloak and univention-keycloak.

The univention-app configure keycloak command lets you adjust global settings for the Docker container and the Keycloak process running inside it. Want to see which configurations are currently active? Just run: univention-app configure keycloak --list And voilà—you’ll get a list of all active settings.

Need to set the log level to DEBUG for troubleshooting? No problem:

univention-app configure keycloak --set keycloak/log/level=DEBUG

Remember, any changes you make here will restart the container, meaning Keycloak will be temporarily unavailable while it comes back online. So, plan your timing accordingly!

The second tool, univention-keycloak, is your go-to for all things related to the actual Keycloak configuration. It works through Keycloak’s REST API, making it perfect for adding new clients, managing user attributes, or setting up custom configurations. Let’s say you want to add a new OIDC client. Just run:

univention-keycloak oidc/rp create \
--client-secret "***" \
--description "My OIDC-Compatible Application" \
--name "My App" \
--app-url https://app.example.org \
--redirect-uri https://app.example.org/callback \
app.example.org

Make sure to replace the values for --app-url and --redirect-uri with the details provided by the application’s operator.

Need a certificate for your SAML client setup? You can get it with:

univention-keycloak saml/idp/cert get

And if you want it saved as a PEM file:

univention-keycloak saml/idp/cert get --as-pem --output keycloak-idp-cert.pem

With univention-keycloak, you can do so much more—sync user attributes, enable two-factor authentication, or add links to the login page. It’s even script-friendly, allowing you to automate batch tasks like importing a large number of clients.

Looking for more detailed instructions or other examples? Check out our documentation for an in-depth guide on using these tools.

Keycloak offers several features that make it easy to keep an eye on what’s happening in your environment and spot potential issues early on. For example, in the Sessions menu, you’ll find a list of all active logins to your Identity Provider.

Overview of Active Sessions at the Keycloak IdP

You can filter the information using the search bar at the top of the screen. The Events menu, on the other hand, shows you who logged into which service, when, and from which IP address. The displayed usernames are pseudonyms generated by Keycloak. Click on any entry to get a detailed view of the events.

If you encounter issues with Single Sign-On, it’s best to check both sides: Keycloak and the affected clients. Pro tip: Try using different browsers or profiles and remember to clear old cookies and cache regularly—this can often resolve hidden issues. Also, make sure to examine the log files closely. Look into the logs for Keycloak, the client application, and OpenLDAP. To see what requests Keycloak is sending to the OpenLDAP slapd process, temporarily increase the log level without interrupting the running system:

printf 'dn: cn=config\nchangetype: modify\nreplace: olcLogLevel\nolcLogLevel: %s\n\n' stats | ldapmodify -xH ldapi:///

Next, analyze the entries in /var/log/syslog to get more details.

Typical pitfalls often include misconfigured certificates, missing private keys for SAML communication, or connectivity issues with the endpoints defined in the configuration. If you have a load balancer or proxy between Keycloak and the application, that could also be a potential cause of trouble.

If access fails not at the initial login to the IdP but only when trying to access a protected web resource, take a closer look at the expected vs. actual attributes or claims being sent. Keycloak offers a handy tool for this: under Client Scopes for each configured client, there’s a tab called Evaluate. Enter the affected user’s credentials here, and you can see the tokens that Keycloak would generate for this client and user. This makes it easy to spot discrepancies between what’s expected and what’s actually being transmitted, so you can quickly identify and fix the issue.

Keycloak has proven to be a powerful and flexible solution for centralized authentication and authorization within a UCS environment. With its extensive features—ranging from client management and scope configuration to advanced monitoring and debugging tools—Keycloak provides UCS admins with all the tools they need to enhance security and optimize workflows.

Have you already implemented Keycloak successfully in your environment? We’d love to hear about your experiences! If you’re still in the process of migrating to Keycloak, don’t hesitate to reach out with any questions or connect with other admins in the forum.