Skip to main content
This guide walks you through installing and configuring Himmelblau on a Linux system. By the end, your system will resolve Entra ID users through NSS and authenticate them through PAM.
1

Install packages

On openSUSE Tumbleweed, refresh repositories and install all packages:
sudo zypper ref && sudo zypper in himmelblau nss-himmelblau pam-himmelblau himmelblau-sso
For other distributions (Fedora, RHEL, Debian, Ubuntu, NixOS), see the Installation guide.
2

Configure your domain

Edit /etc/himmelblau/himmelblau.conf and set your Entra ID domain and the groups allowed to log in:
[global]
domain = example.com
pam_allow_groups = <entra-group-guid-or-name>
Replace example.com with your primary Entra ID verified domain or tenant.onmicrosoft.com address. Set pam_allow_groups to one or more Entra ID group Object IDs (GUIDs) or group names, separated by commas. Only members of these groups will be permitted to authenticate.
The domain option is required. Without it, no users will be able to authenticate.
3

Start the services

Enable and start both daemons:
sudo systemctl enable --now himmelblaud himmelblaud-tasks
Check the systemd journal for errors if something doesn’t start:
sudo journalctl -u himmelblaud -u himmelblaud-tasks --no-pager
4

Disable nscd

Himmelblau manages its own identity cache. The legacy nscd daemon conflicts with it and must be disabled:
sudo systemctl stop nscd
sudo systemctl disable nscd
sudo systemctl mask nscd
5

Configure NSS

Copy the system NSS configuration and add himmelblau to the passwd, group, and shadow lines:
sudo cp /usr/etc/nsswitch.conf /etc/nsswitch.conf
Then edit /etc/nsswitch.conf so the relevant lines read:
passwd:     compat systemd himmelblau
group:      compat systemd himmelblau
shadow:     compat systemd himmelblau
6

Configure PAM

The easiest way to configure PAM is to use the aad-tool helper:
sudo aad-tool configure-pam --really
Only modify your PAM configuration if you are confident you understand the syntax. Removing PAM modules from your stack may prevent you from authenticating to the host. The manual setup below is provided as a reference. Always keep a root shell open while modifying PAM so you can recover if something goes wrong.
If you prefer to configure PAM manually, copy the pre-built configuration files and update each file as shown below.First, back up and replace the existing files:
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
Then set the content of each file:/etc/pam.d/common-auth
auth        required      pam_env.so
auth        [default=1 ignore=ignore success=ok] pam_localuser.so
auth        sufficient    pam_himmelblau.so
auth        sufficient    pam_unix.so nullok try_first_pass
auth        required      pam_deny.so
/etc/pam.d/common-account
account    [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-session
session 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-password
password    sufficient    pam_himmelblau.so ignore_unknown_user
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
7

Test your setup

Verify that NSS can resolve an Entra ID user:
getent passwd user@example.com
Test authentication end-to-end through the daemon:
aad-tool auth-test --name user@example.com
Check that the daemon is running and connected:
aad-tool status

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us