Himmelblau

https://himmelblau-idm.org/docs/
Admin
Himmelblau is an open-source authentication framework for Linux that provides native Microsoft Entra...
Tokens:61,096
Snippets:630
Trust Score:6.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Himmelblau with bootstrap installer

Source: https://himmelblau-idm.org/docs.html

Run this bootstrap installer to install Himmelblau. It detects your distribution, offers supported package sources, adds the trusted repository when needed, and installs packages with apt, dnf, or zypper. It prompts for Microsoft Entra ID or generic OIDC settings, configures PAM and NSS, and starts the himmelblaud and himmelblaud-tasks services.

```shell
curl -fsSL https://himmelblau-idm.org/install | sh
```

--------------------------------

### Start mitmweb

Source: https://himmelblau-idm.org/docs/troubleshooting/Testing-Himmelblau-Developer-Builds-with-Packet-Capture

Start mitmweb after downloading and extracting mitmproxy. It launches a web interface at http://127.0.0.1:8081/.

```bash
./mitmweb
```

--------------------------------

### Restart GDM after installing himmelblau-qr-greeter

Source: https://himmelblau-idm.org/docs/advanced/Enabling-the-Himmelblau-QR-Greeter-gnome%E2%80%90shell-Extension

Restart GDM after installing the himmelblau-qr-greeter package so the QR login option appears on the login and lock screens. Run this command once after installation; otherwise the extension may not show on first use.

```bash
sudo systemctl restart gdm3

```

--------------------------------

### PAM account stack example: /etc/pam.d/common-account

Source: https://himmelblau-idm.org/docs/configuration

Example /etc/pam.d/common-account file. Follows the same ordering guidelines: pam_himmelblau.so after pam_localuser.so and before pam_unix.so, with ignore_unknown_user and pam_deny.so last.

```text
account     [default=1 ignore=ignore success=ok] pam_localuser.so
account     sufficient    pam_unix.so
account     sufficient    pam_himmelblau.so ignore_unknown_user
account     required      pam_deny.so

```

--------------------------------

### Install TPM tools on openSUSE

Source: https://himmelblau-idm.org/docs/advanced/Configuring-a-Hardware-TPM-for-Secure-Key-Storage

Installs TPM tools on openSUSE for further inspection of the TPM.

```bash
sudo zypper install tpm2.0-tools
```

--------------------------------

### PAM auth stack example: /etc/pam.d/common-auth

Source: https://himmelblau-idm.org/docs/configuration

Example /etc/pam.d/common-auth file. Place pam_himmelblau.so after pam_localuser.so and before pam_unix.so, include ignore_unknown_user, and keep pam_deny.so last. Keeping pam_himmelblau.so above pam_unix.so in the auth stack avoids fallback password prompts.

```text
auth        required      pam_env.so
auth        [default=1 ignore=ignore success=ok] pam_localuser.so
auth        sufficient    pam_himmelblau.so ignore_unknown_user
auth        sufficient    pam_unix.so nullok try_first_pass
auth        required      pam_deny.so

```

--------------------------------

### Start himmelblaud-tasks daemon

Source: https://himmelblau-idm.org/docs/reference/himmelblaud_tasks

Starts the himmelblaud-tasks daemon. Must be run as root; otherwise it fails with an error.

```bash
# systemctl start himmelblaud-tasks

```

--------------------------------

### PAM session stack example: /etc/pam.d/common-session

Source: https://himmelblau-idm.org/docs/configuration

Example /etc/pam.d/common-session file. Includes pam_himmelblau.so as an optional session module, placed after pam_unix.so and before pam_env.so.

```text
session optional    pam_systemd.so
session required    pam_limits.so
session optional    pam_unix.so try_first_pass
session optional    pam_umask.so 
session optional    pam_himmelblau.so
session optional    pam_env.so

```

--------------------------------

### Start himmelblaud daemon with systemctl

Source: https://himmelblau-idm.org/docs/reference/himmelblaud

Starts the himmelblaud daemon as a systemd service. Run as root or with appropriate privileges.

```bash
# systemctl start himmelblaud

```

--------------------------------

### Start mitmweb with the ./mitmweb command

Source: https://himmelblau-idm.org/docs/troubleshooting/Capturing-authentication-traffic-using-cirrus%E2%80%90scope

Starts the mitmweb web interface for monitoring HTTP and HTTPS traffic. This command must be run from the directory where mitmproxy was extracted, and it opens a web-based dashboard.

```bash
./mitmweb

```

--------------------------------

### Build and install Himmelblau from source

Source: https://himmelblau-idm.org/docs/installation

Build Himmelblau from source using the included Makefile. The build system auto-detects the host distribution and uses Podman or Docker for reproducible container builds. Run 'make help' for the full list of available targets. The final command installs the locally built packages using the native package manager.

```bash
git clone https://github.com/himmelblau-idm/himmelblau
cd himmelblau
```

```bash
make               # auto-detects host distro and builds matching packages
```

```bash
make ubuntu24.04   # or debian13, rocky9, sle16, etc.
```

```bash
sudo make install
```

--------------------------------

### Install TPM tools on Debian/Ubuntu

Source: https://himmelblau-idm.org/docs/advanced/Configuring-a-Hardware-TPM-for-Secure-Key-Storage

Installs TPM tools on Debian/Ubuntu for further inspection of the TPM.

```bash
sudo apt install tpm2-tools
```

--------------------------------

### PAM password stack example: /etc/pam.d/common-password

Source: https://himmelblau-idm.org/docs/configuration

Example /etc/pam.d/common-password file. Uses pam_himmelblau.so as sufficient with ignore_unknown_user, followed by pam_unix.so and pam_deny.so last.

```text
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

```

--------------------------------

### Start Himmelblau services

Source: https://himmelblau-idm.org/docs/introduction

Start the two services himmelblaud and himmelblaud-tasks and activate them permanently. Only after this can the first login be performed.

```text
systemctl enable --now himmelblaud himmelblaud-tasks
```

--------------------------------

### Enable and restart Himmelblau daemons

Source: https://himmelblau-idm.org/docs.html

If you edit configuration manually, restart the daemons. The installer normally enables and starts them for you.

```shell
sudo systemctl enable himmelblaud himmelblaud-tasks
sudo systemctl restart himmelblaud himmelblaud-tasks
```

--------------------------------

### PAM password stack for common-password

Source: https://himmelblau-idm.org/docs/reference/pam_himmelblau

Example configuration for /etc/pam.d/common-password. Set pam_himmelblau.so as sufficient in the password stack.

```text
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

```

--------------------------------

### PAM account stack for common-account

Source: https://himmelblau-idm.org/docs/reference/pam_himmelblau

Example configuration for /etc/pam.d/common-account. Configure it in a similar manner to the auth stack, using the ignore_unknown_user option.

```text
account    [success=ok auth_err=die default=ignore] pam_himmelblau.so ignore_unknown_user
account    sufficient    pam_unix.so
account    required    pam_deny.so

```

--------------------------------

### Updated [Service] section with ReadWritePaths

Source: https://himmelblau-idm.org/docs/troubleshooting/Write-Permissions-for-the-%60logon_script%60-Parameter-in-Himmelblau

Add the paths that need write access for the logon_script. Example includes /home, /var/run/himmelblaud, and /var/log.

```ini
[Service]
ReadWritePaths=/home /var/run/himmelblaud /var/log

```

--------------------------------

### Keycloak Client ID Example

Source: https://himmelblau-idm.org/docs/advanced/keycloak

Example client ID value to use when creating the Keycloak client. This value must match the app_id configured in Himmelblau.

```text
himmelblau-login

```

--------------------------------

### Himmelblau configuration example: /etc/himmelblau/himmelblau.conf

Source: https://himmelblau-idm.org/docs/architecture

Configuration file for Himmelblau, defining global settings such as the Entra ID domain, allowed PAM groups, POSIX home attribute, and whether to use /etc/skel. Refer to the himmelblau.conf man page for detailed options.

```ini
[global]
domain = example.com
pam_allow_groups = 00000000-1111-2222-3333-444444444444
home_attr = CN
use_etc_skel = true

```

--------------------------------

### Open mitmweb Interface in web browser

Source: https://himmelblau-idm.org/docs/troubleshooting/Capturing-authentication-traffic-using-cirrus%E2%80%90scope

Replace the placeholder URL with the actual address shown in the terminal. The command is an example of how to open the dashboard.

```bash
http://127.0.0.1:8081/

```

--------------------------------

### Example klist output for cloud TGT

Source: https://himmelblau-idm.org/docs/advanced/Cloud-Kerberos-Trust-for-Linux

Example output from klist showing a valid cloud TGT in a keyring credential cache. Himmelblau only supports keyring caches; file-based caches like FILE:/tmp/krb5cc_<uid> are not supported.

```text
Ticket cache: KEYRING:persistent:<uid>
Default principal: user@KERBEROS.MICROSOFTONLINE.COM

Valid starting       Expires              Service principal
...                  ...                  krbtgt/KERBEROS.MICROSOFTONLINE.COM@KERBEROS.MICROSOFTONLINE.COM

```

--------------------------------

### Install mitmproxy CA certificate on openSUSE Leap

Source: https://himmelblau-idm.org/docs/troubleshooting/Capturing-authentication-traffic-using-cirrus%E2%80%90scope

This copies the mitmproxy CA certificate to the openSUSE Leap trust anchors directory and then updates the certificate store. Requires sudo

```bash
sudo cp $HOME/.mitmproxy/mitmproxy-ca-cert.pem /usr/share/pki/trust/anchors/mitmproxy.crt
sudo update-ca-certificates

```

--------------------------------

### Configure PAM on openSUSE/SLE with pam-config

Source: https://himmelblau-idm.org/docs.html

On openSUSE or SUSE Linux Enterprise, run this command to configure PAM manually if it was not configured automatically during installation.

```shell
sudo pam-config --add --himmelblau
```

--------------------------------

### name_mapping_script example

Source: https://himmelblau-idm.org/docs/reference/himmelblau-conf

Example script for name_mapping_script. It accepts a single argument (a mapped name), prints the corresponding UPN to stdout, or returns the input name unchanged if unrecognized. Must handle errors gracefully to avoid authentication failures.

```bash
#!/bin/bash
    # Convert CN to UPN, or return the input name if unrecognized
    if [[ "$1" =~ ^[a-zA-Z0-9._-]+$ ]]; then
        echo "$1@example.com"
    else
        echo "$1"
    fi
```

--------------------------------

### Install mitmproxy CA certificate on Ubuntu

Source: https://himmelblau-idm.org/docs/troubleshooting/Capturing-authentication-traffic-using-cirrus%E2%80%90scope

This two-command sequence copies the mitmproxy CA certificate to the system trust store on Ubuntu, then updates the CA certificates. Requires sudo

```bash
sudo cp $HOME/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy.crt
sudo update-ca-certificates

```

--------------------------------

### Install mitmproxy CA certificate on Fedora

Source: https://himmelblau-idm.org/docs/troubleshooting/Capturing-authentication-traffic-using-cirrus%E2%80%90scope

Copies the mitmproxy CA certificate to the Fedora trust store anchors directory, then updates the trust. Requires sudo

```bash
sudo cp $HOME/.mitmproxy/mitmproxy-ca-cert.pem /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

```

--------------------------------

### Set local user home attributes (home_attr, home_alias, use_etc_skel)

Source: https://himmelblau-idm.org/docs/introduction

Configuration attributes for local user home directory creation on Debian and Ubuntu systems. Set home_attr and home_alias to CN, and enable use_etc_skel to copy files from /etc/skel. These values are always entered during package installation.

```plaintext
home_attr = CN
home_alias = CN
use_etc_skel = true
```

--------------------------------

### Enable Azure authentication on Ubuntu/Debian

Source: https://himmelblau-idm.org/docs/reference/pam_himmelblau

Runs the PAM configuration tool on Ubuntu/Debian to enable Azure authentication. After running, enable the 'Azure authentication' option and verify the PAM files.

```bash
sudo pam-auth-update

```

--------------------------------

### Install AzureADHybridAuthenticationManagement module

Source: https://himmelblau-idm.org/docs/advanced/Cloud-Kerberos-Trust-for-Linux

Installs the AzureADHybridAuthenticationManagement PowerShell module, which is required for creating and managing the Entra Kerberos server object.

```powershell
Install-Module -Name AzureADHybridAuthenticationManagement -AllowClobber

```

--------------------------------

### Install mitmproxy CA certificate

Source: https://himmelblau-idm.org/docs/troubleshooting/Testing-Himmelblau-Developer-Builds-with-Packet-Capture

Install the mitmproxy CA certificate on Ubuntu/Debian, Fedora/RHEL, or openSUSE. Choose the command block that matches your distribution.

```bash
sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy.crt
sudo update-ca-certificates
```

```bash
sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust
```

```bash
sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/share/pki/trust/anchors/mitmproxy.crt
sudo update-ca-certificates
```

--------------------------------

### Local login via su -l (working as expected)

Source: https://himmelblau-idm.org/docs/troubleshooting/OpenSSH-Bug-2876-%E2%80%90--Unable-to-use-MFA-over-SSH-%E2%80%90-Workaround

Shows the expected local login flow via su -l, where the password prompt and MFA number prompt appear in sequence without delay.

```text
admin@dev01:~$ su -l user@domain.onmicrosoft.com
Password:
Open your Authenticator app, and enter the number '73' to sign in.
user@domain.onmicrosoft.com@dev01:~$ whoami
user@domain.onmicrosoft.com

```

--------------------------------

### PAM auth stack for common-auth

Source: https://himmelblau-idm.org/docs/reference/pam_himmelblau

Recommended PAM auth stack for /etc/pam.d/common-auth. Place pam_himmelblau.so after other authentication methods, include ignore_unknown_user, and ensure pam_deny.so is last so unknown users are not implicitly allowed. Do not set other modules to required, and place pam_himmelblau.so before pam_unix.so when using Hello or Passwordless authentication.

```text
auth required pam_env.so
auth [default=1 ignore=ignore success=ok] pam_localuser.so
auth sufficient pam_unix.so nullok try_first_pass
auth sufficient pam_himmelblau.so ignore_unknown_user
auth required pam_deny.so

```

--------------------------------

### Set up a client certificate with aad-tool

Source: https://himmelblau-idm.org/docs/advanced/Creating-an-Entra-ID-Application-for-Himmelblau-GroupMember.Read.All-and-User.Read.All-Permissions

Use this command to generate a client certificate valid for 365 days and output it to /tmp/my-cert.crt. The private key never leaves your TPM or software HSM. Upload the certificate in the Entra ID portal.

```bash
aad-tool cred cert --client-id <CLIENT_ID> --domain <DOMAIN> --valid-days 365 --cert-out /tmp/my-cert.crt

```

--------------------------------

### Set home_prefix

Source: https://himmelblau-idm.org/docs/reference/himmelblau-conf

Sets the prefix for user home directories. Default is /home/.

```ini
home_prefix = /home/entra/
```

--------------------------------

### Enable apply_policy

Source: https://himmelblau-idm.org/docs/reference/himmelblau-conf

Enables application and enforcement of Intune policies for authenticated users. Default is false.

```ini
apply_policy = true
```

--------------------------------

### Enable Intune policy processing in himmelblau.conf and restart services

Source: https://himmelblau-idm.org/docs/intune

Enable Intune policy processing in the [global] section of /etc/himmelblau/himmelblau.conf, then restart both Himmelblau services. Required before Linux compliance policies can be enforced on the client.

```ini
[global]
apply_policy = true

```

```bash
sudo systemctl restart himmelblaud himmelblaud-tasks

```

--------------------------------

### krb5.conf encryption types for Entra Kerberos

Source: https://himmelblau-idm.org/docs/advanced/Cloud-Kerberos-Trust-for-Linux

Example /etc/krb5.conf configuration that restricts encryption types to those supported by Microsoft Entra Kerberos. Use this when the mount fails with STATUS_MORE_PROCESSING_REQUIRED.

```ini
[libdefaults]
 default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
 default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
 permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96

```

--------------------------------

### CIFS upcall error output for missing TGT

Source: https://himmelblau-idm.org/docs/advanced/Cloud-Kerberos-Trust-for-Linux

Example error output indicating cifs.upcall did not find a usable TGT for the requested user. This failure means the mount cannot proceed with Kerberos authentication.

```text
cifs.upcall: main: valid TGT is not present in credential cache
cifs.upcall: Unable to obtain service ticket
CIFS: VFS: \\<storage-account>.file.core.windows.net failed to create a new SMB session with Kerberos: -126

```

--------------------------------

### Configure delegated authentication in himmelblau.conf

Source: https://himmelblau-idm.org/docs/advanced/Creating-an-Entra-ID-Application-for-Himmelblau-GroupMember.Read.All-and-User.Read.All-Permissions

Add your application ID to himmelblau.conf for delegated authentication. Replace the example ID with your actual Application (client) ID. This method prevents enumeration of rfc2307 attributes until after user authentication.

```ini
[example.com]
app_id = 98fa618b-e5d2-4697-b0fd-fe3ec5eecdd3

```

--------------------------------

### Set Ubuntu home_attr, home_alias, and use_etc_skel in himmelblau.conf

Source: https://himmelblau-idm.org/docs/configuration

Set Ubuntu-specific options to ensure snaps execute correctly. These settings are required on Ubuntu and are enabled by default when using the Himmelblau Debian/Ubuntu packages.

```ini
[global]
home_attr = CN
home_alias = CN
use_etc_skel = true

```

--------------------------------

### Configure PAM on other distros with aad-tool

Source: https://himmelblau-idm.org/docs.html

On all other distributions, run this manual config utility bundled with Himmelblau to configure PAM if it was not configured automatically.

```shell
sudo aad-tool configure-pam
```

--------------------------------

### Configure Entra ID domain in himmelblau.conf

Source: https://himmelblau-idm.org/docs.html

Set the primary domain of your Entra ID tenant in /etc/himmelblau/himmelblau.conf. The file uses the INI format. Edit manually only if the installer did not prompt for your identity provider settings or if you need to change them later.

```ini
[global]
domain = example.onmicrosoft.com
```

--------------------------------

### User-map file entries for local-to-Entra ID mapping

Source: https://himmelblau-idm.org/docs/reference/himmelblau-conf

Example entries for the user-map file. Each line maps a local username to an Entra ID account in the format local_username:name@domain. Blank lines and lines beginning with '#' are ignored.

```text
alice:alice@contoso.com
bob:bob.smith@example.org
svcuser:service.account@tenant.local
```

--------------------------------

### Enable use_etc_skel for user directory creation

Source: https://himmelblau-idm.org/docs/reference/himmelblau-conf

Enables using the contents of /etc/skel when creating new user directories. Default is false.

```ini
use_etc_skel = true
```

--------------------------------

### Join domain with aad-tool auth-test

Source: https://himmelblau-idm.org/docs/rfc2307-entra-id-posix-attributes

Joins the domain using a local account with aad-tool auth-test. This is required because the new attributes cannot be read during the first login; the command uses a user ID from the domain and prompts for authentication and PIN setup.

```bash
**stka@himmelblau**:**~**\$ aad-tool auth-test --name stkania  
Use the password for your Office 365 or Microsoft online login.  
Entra Id Password:   
Open your Authenticator app, and enter the number '37' to sign in.  
No push? Check your mobile device's internet connection.  
Set up a PIN  
A Hello PIN is a fast, secure way to sign in to your device, apps, and
services.  
The minimum PIN length is 6 characters.  
New PIN:   
Set up a PIN  
A Hello PIN is a fast, secure way to sign in to your device, apps, and
services.  
The minimum PIN length is 6 characters.  
Confirm PIN:   
Enrolling the Hello PIN. Please wait...

```

--------------------------------

### home_attr available options

Source: https://himmelblau-idm.org/docs/reference/himmelblau-conf

Lists the available options for the home_attr setting: UUID, SPN, and CN.

```text
- UUID

- SPN

- CN
```

--------------------------------

### First login of a new user via SSH (Listing 6)

Source: https://himmelblau-idm.org/docs/introduction

First login of a new user on a Linux client integrated into the domain. The user must log in via a browser using the URL listed in the output because two-factor authentication and a password change are still required. The code generated in the command line is required for the browser login.

```text
ssh user02@192.168.56.81
(user02@192.168.56.81) Use the password for your Office 365 or Microsoft online login. 
Entra Id Password: <initial password>
(user02@192.168.56.81) To sign in, use a web browser to open the page https/microsoft.codevicelogin and enter the code DG94ZUCB2 to authenticate. 
Press enter to continue
```

--------------------------------

### Default configuration file path

Source: https://himmelblau-idm.org/docs/troubleshooting/Troubleshooting%3A-%60The-user-%27...%27-already-exists%60-and-fake-users-listed-in-NSS

Default location of the Himmelblau configuration file.

```text
/etc/himmelblau/himmelblau.conf

```

--------------------------------

### Configure PAM with pam-config or aad-tool

Source: https://himmelblau-idm.org/docs/configuration

Use these commands to insert Himmelblau into the PAM stack on openSUSE/Tumbleweed or on all systems when manual file editing is preferred. The first command relies on pam-config; the second directly modifies PAM config files such as /etc/pam.d/common-auth and is safe as a starting point for fine-grained control.

```bash
sudo pam-config --add --himmelblau

```

```bash
sudo aad-tool configure-pam

```

--------------------------------

### enable_experimental_mfa option

Source: https://himmelblau-idm.org/docs/reference/himmelblau-conf

Enables the experimental MFA flow that permits Hello authentication. When disabled, the system enforces the Device Authorization Grant (DAG) flow, which is more robust but does not support Hello authentication. Default is true.

```ini
enable_experimental_mfa = false
```

--------------------------------

### Enable MDM Intune policy enforcement in himmelblau.conf

Source: https://himmelblau-idm.org/docs.html

Enable MDM Intune compliance enforcement by setting apply_policy to true in the [global] section of /etc/himmelblau/himmelblau.conf.

```ini
[global]
apply_policy = true
```

--------------------------------

### Restrict logins to allowed users and groups (pam_allow_groups)

Source: https://himmelblau-idm.org/docs/introduction

Insert this line into the configuration to allow only specific users or groups to log in. Users must be entered by UPN and groups by Object ID GUID, separated by commas. If a user is not explicitly entered or is not a member of an entered group, the login is canceled.

```ini
## Only the following users and groups are allowed on this client 
pam_allow_groups = user01@example.onmicrosoft.com,bb845f7f-8f6a-4101-b4c7-8db3cb94c9e6

```
Tokens:
Raw