Himmelblau is distributed as DEB packages for Debian and Ubuntu. Download them from the Himmelblau downloads page and install locally with apt.
Supported versions
| Distribution | Version |
|---|
| Debian | 12 (Bookworm), 13 |
| Ubuntu | 22.04 (Jammy Jellyfish), 24.04 (Noble Numbat) |
Installation
Download the DEB packages for your distribution from the downloads page, then install them with apt:
sudo apt install \
./himmelblau_<version>.deb \
./himmelblau-sshd-config_<version>.deb \
./himmelblau-sso_<version>.deb \
./nss-himmelblau_<version>.deb \
./pam-himmelblau_<version>.deb
<version> with the version string from the downloaded filenames.
Post-installation setup
Debian/Ubuntu-specific configuration
Debian and Ubuntu require some additional defaults in /etc/himmelblau/himmelblau.conf. The pam-himmelblau package installs an example at /etc/himmelblau/himmelblau.conf.example. At minimum, add the following to your configuration:
[global]
local_groups = users
home_attr = CN
home_alias = CN
use_etc_skel = true
Disable nscd
The Name Service Cache Daemon (nscd) conflicts with Himmelblau’s NSS module. Stop and mask it:
sudo systemctl stop nscd
sudo systemctl disable nscd
sudo systemctl mask nscd
/etc/nsswitch.conf and add himmelblau to the passwd, group, and shadow databases:
passwd: files systemd himmelblau
group: files systemd himmelblau
shadow: files himmelblau
getent passwd user@your-tenant.onmicrosoft.com
pam-auth-update. The pam-himmelblau package installs a PAM profile fragment, which pam-auth-update uses to configure common-auth, common-account, common-session, and common-password automatically.
Run pam-auth-update to enable the Himmelblau profile interactively, or apply it non-interactively:
sudo pam-auth-update --enable himmelblau
| Stack | Entry |
|---|
common-auth | [success=end default=ignore] pam_himmelblau.so ignore_unknown_user set_authtok |
common-account | [success=end default=ignore] pam_himmelblau.so ignore_unknown_user |
common-password | [success=end ignore=ignore default=die] pam_himmelblau.so ignore_unknown_user set_authtok |
common-session | optional pam_himmelblau.so |
# /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
Only modify PAM configuration files directly if you understand the syntax. An incorrect PAM stack can prevent all users from logging in. Test changes in a separate session before closing your current one.
AppArmor
Himmelblau ships AppArmor local profiles for Debian and Ubuntu systems. These are installed by the pam-himmelblau package and extend existing system profiles to grant the Himmelblau daemon and helper binaries the access they need.
Two local profile fragments are installed:
/etc/apparmor.d/local/fusermount3 — grants himmelblaud read access to its config, cache, and socket./etc/apparmor.d/local/unix-chkpwd — grants unix-chkpwd the capabilities and file access required for Himmelblau’s PAM module.
These profiles are loaded automatically when AppArmor is active. If you see AppArmor denials in your system journal after installation, reload the affected profiles:
sudo apparmor_parser -r /etc/apparmor.d/usr.bin.fusermount3
sudo apparmor_parser -r /etc/apparmor.d/usr.sbin.unix-chkpwd
