After installing Himmelblau and configuring himmelblau.conf, you need to wire the PAM and NSS modules into your Linux authentication stack.
Only modify PAM configuration if you understand the syntax. Mistakes can prevent all users — including local admins — from logging in. Test in a VM first, and keep a root shell open while making changes.
NSS configuration
NSS (Name Service Switch) allows getent passwd, getent group, and other tools to resolve Entra ID users.
Copy the default nsswitch.conf
On openSUSE/SUSE, copy the packaged default:sudo cp /usr/etc/nsswitch.conf /etc/nsswitch.conf
/etc/nsswitch.conf. Add himmelblau to passwd, group, and shadow
Edit /etc/nsswitch.conf and add himmelblau to the passwd, group, and shadow lines:passwd: compat systemd himmelblau
group: compat systemd himmelblau
shadow: compat systemd himmelblau
Test user resolution
getent passwd user@example.onmicrosoft.com
Disable nscd before using Himmelblau — it conflicts with the NSS module by caching stale entries:sudo systemctl stop nscd
sudo systemctl disable nscd
sudo systemctl mask nscd
PAM configuration
Automated setup (recommended)
The aad-tool configure-pam command automatically inserts the correct pam_himmelblau.so lines into your PAM files:
# Dry run — shows what would change without modifying anything
sudo aad-tool configure-pam
# Apply changes
sudo aad-tool configure-pam --really
try_unseal line (for unlocking secrets at login without touching other PAM stacks):
sudo aad-tool configure-pam --really --try-unseal
Manual setup
If you prefer to configure PAM manually, add the following lines to each file. The exact file names vary by distribution.
Debian / Ubuntu
Fedora / RHEL
openSUSE / SUSE
/etc/pam.d/common-authauth required pam_env.so
auth [default=1 ignore=ignore success=ok] pam_localuser.so
auth sufficient pam_himmelblau.so ignore_unknown_user set_authtok
auth sufficient pam_unix.so nullok try_first_pass
auth required pam_deny.so
/etc/pam.d/common-accountaccount [default=1 ignore=ignore success=ok] pam_localuser.so
account sufficient pam_himmelblau.so ignore_unknown_user
account sufficient pam_unix.so
account required pam_deny.so
/etc/pam.d/common-sessionsession optional pam_systemd.so
session required pam_limits.so
session optional pam_himmelblau.so
session optional pam_unix.so try_first_pass
session optional pam_umask.so
session optional pam_env.so
/etc/pam.d/common-passwordpassword sufficient pam_himmelblau.so ignore_unknown_user set_authtok
password optional pam_gnome_keyring.so use_authtok
password sufficient pam_unix.so use_authtok nullok shadow try_first_pass
password required pam_deny.so
On Fedora and RHEL, use authselect to manage PAM. Himmelblau provides an authselect profile in the himmelblau-sshd-config package. After installing, select the profile:sudo authselect select himmelblau --force
pam_himmelblau.so lines to /etc/pam.d/system-auth and /etc/pam.d/password-auth following the same pattern as the Debian/Ubuntu example above. On openSUSE/SUSE, use pam-config or copy the pre-configured fragments:sudo cp /etc/pam.d/common-password-pc /etc/pam.d/common-password
sudo cp /etc/pam.d/common-auth-pc /etc/pam.d/common-auth
sudo cp /etc/pam.d/common-account-pc /etc/pam.d/common-account
sudo cp /etc/pam.d/common-session-pc /etc/pam.d/common-session
pam_himmelblau.so options
| Option | Description |
|---|
ignore_unknown_user | Return PAM_IGNORE for users not in Entra ID, allowing the stack to fall through to pam_unix |
set_authtok | Store the authenticated token in PAM’s authtok field so downstream modules (e.g. gnome-keyring) can use it via use_authtok |
try_unseal | Attempt to unseal stored secrets at login time (optional add-on, does not affect the main auth stack) |
SSH configuration
The himmelblau-sshd-config package installs an sshd configuration snippet that enables PAM-based authentication for SSH. This allows MFA challenges to be presented over SSH sessions.
After installing the package, restart sshd:
sudo systemctl restart sshd
