Keycloak Authentication for Ubuntu 24.04 Login - New User Creation

Question

I'm using Keycloak (version 26.1.0) as my identity provider for web applications and want to extend this to authenticate users logging into Ubuntu 24.04 workstations. I've successfully configured zhaow-de/pam-keycloak-oidc and datajoint-company/pam-oauth2 to connect to my Keycloak server.

However, I've hit a roadblock. Keycloak authentication only succeeds if a local user account with the same username already exists on the Ubuntu system. If the local account doesn't exist, the login fails, even though Keycloak itself authenticates the user. This is true for both pam-keycloak-oidc and pam-oauth2.

I've discovered that creating a local user (with any password) before attempting the Keycloak login resolves the issue. This suggests the PAM modules are checking for a local user before even attempting to establish a session.

My goal is to have home directories and user accounts dynamically created for Keycloak-authenticated users on their first login. I've attempted to use pam_mkhomedir.so in /etc/pam.d/common-auth to achieve this, but my analysis indicates that authentication fails before the session initialization stage where pam_mkhomedir.so would be invoked.

I'm dubtful about modifying PAM config in the file /etc/pam.d/common-auth? Is that the correct file, or should I instead be configuring PAM in /etc/pam.d/sshd (or another file)? Any guidance on the correct PAM configuration to allow dynamic user creation for Keycloak-authenticated users would be greatly appreciated. I'm particularly interested in the proper order of PAM modules and how to ensure 1st user logins from IdP and automatic creation of their home directories.

EDIT

Adding relevant lines of nsswitch.conf:

passwd:            files systemd sss
group:             files systemd sss
shadow:            files systemd sss
gshadow:           files systemd

Answer 1

According to nsswitch.conf your system gets user information from local files, systemd (normally for root, nobody and container users only), and sssd if it's configured.

Have you configured sssd to access whatever user database is used by your Keycloak server?

If not, that explains the issue: then there is no way to map Keycloak-only usernames/groups to UID/GID numbers and vice versa. And when there is no UID/GID numbers to associate with a user/group, then that user/group is not really usable system-wide: it cannot own files or processes, for example.

With such a configuration, the login process will fail as soon as it attempts to look up a UID for the logging-in user and no such mapping can be found. Some classic Unix programs might react to this situation with an error message: You don't exist, go away!

Background

Basically, there are two elements that must be in place for users defined in external databases/directories to work system-wide:

• a libnss_*.so library (selected by nsswitch.conf, and effectively an extension of the system's C standard library) that provides the username <-> UID and/or groupname <-> GID lookup services for users defined in the external database/directory. Once this is in place and working, the external users can "exist" on the system: they can own files and processes, and privileged processes can run other processes "as" external users. libnss_sss.so can be used with Active Directory, FreeIPA or generic LDAP user directories. It works with the sssd service process.

• a PAM authentication library that provides at least an authentication service that allows the user's password to be checked against the external user database. Having other PAM services like accounting, session management and password change services associated with the external user database/directory is, strictly speaking, optional - but can be quite useful. When using external user databases, it is also common to add the pam_mkhomedir.so PAM module, so that when a new user is created in the external user database, a Unix-style home directory for it can be automatically created on first login.

If you need Keycloak only with a particular app or a web service, whose concept of "users" does not require those users to own files or processes on the system, then and only then using only the PAM element can be meaningful - but then you should configure the Keycloak PAM module in the respective /etc/pam.d/<name of application or service> only, not in a file with system-wide effect like /etc/pam.d/common-auth.

It seems to me that you've only configured the PAM side of things, and assumed it's all that is needed to make externally-defined users work at the system level. Unfortunately, this assumption is not correct.