HIMMELBLAU.CONF(5)

📦 version 2.3.14+git0.e23b4c54, in opensuse-leap 16.0

💅 HIMMELBLAU.CONF(5) — File Formats ✨

okay so bestie, welcome to himmelblau.conf(5) — the file formats page for the config file that makes Azure Entra ID authentication happen on Linux. grab a strawberry drink 🍓 and let's get into it.

🌸 NAME

himmelblau.conf — the configuration file for Himmelblau, the thing that enables Azure Entra ID authentication on Linux. literally its whole personality. 💖

🦋 SYNOPSIS

/etc/himmelblau/himmelblau.conf

that's it. that's the path. iconic.

✨ HOW CONFIGURATION CHANGES ARE APPLIED

okay so this is important and a lot of people get got by it 😭 — changes to the config file /etc/himmelblau/himmelblau.conf only take effect after restarting the Himmelblau daemons. and yes, that means both of them: the himmelblaud daemon (which handles authentication) and the himmelblaud-tasks daemon (which processes related tasks).

🔄 Restarting the Daemons

to actually apply your changes, restart the Himmelblau services with these systemd commands:

sudo systemctl restart himmelblaud

sudo systemctl restart himmelblaud-tasks
ngl bestie, if you edit the file and nothing happens — this is why. restart the daemons. every time. 💀

👑 DESCRIPTION

the himmelblau.conf file is the primary configuration file for the Himmelblau authentication module. it defines the global and optional settings that are required for Azure Entra ID-based authentication and device management. main character file fr fr. 🎀

🎀 FILE FORMAT

the file is made of sections, each one headed by a name wrapped in square brackets. each section contains parameters and their values, in this format:

parameter = value

and lines that begin with a # are comments — the parser just ignores them, no cap. 🙈

💜 PARAMETERS

🌈 [global]

this section holds the settings that apply globally to, like, all operations of Himmelblau. the big ones. ✨

  • domain — the primary Azure Entra ID domain name used for authentication. this value SHOULD match the domain name that users actually type in when signing in (for example, the domain portion of their UPN).

in most cases this is gonna be the primary domain of your Azure Entra ID tenant. if your org uses multiple verified domains or aliases, pick the one your users actually sign in with, bestie. 🫶

this parameter is REQUIRED for successful authentication. and like, for real — if it's not specified, no users will be permitted to authenticate. at all. zero. 💀

domain = example.com
  • debug — a boolean option that turns on debug-level logging. when it's set to true, debug messages get output to the system journal. very "let me see what's going on" of it. 🔥
debug = true
  • pam_allow_groups — a comma-separated list of Entra Id Users and Groups that are permitted to access the system. Users should be specified by UPN. Groups MUST be specified using their Object ID GUID. group names may not be used, because those names are not guaranteed to be unique in Entra Id. 🚫

this restriction is enforced during PAM account management: a user who isn't permitted causes pam_himmelblau to return PAM_AUTH_ERR from its account phase. and here's the tea ☕ — a PAM stack that discards that result (like, for example, an account line whose control maps every non-success return to ignore) will silently admit users that the allow list is meant to reject, because a later module such as pam_unix then succeeds for any resolvable user. so when you're composing an account stack by hand, make sure the denial is terminal. 🙏

pam_allow_groups = f3c9a7e4-7d5a-47e8-832f-3d2d92abcd12,5ba4ef1d-e454-4f43-ba7c-6fe6f1601915,admin@himmelblau-idm.org
  • id_attr_map — specify whether to map uid/gid based on the object name, the object uuid, or based on the rfc2307 schema extension attributes synchronized from an on-prem Active Directory instance. mapping by name or by rfc2307 is recommended. mapping by name is the default. 🌟
id_attr_map = <name|uuid|rfc2307>
  • rfc2307_group_fallback_map — specify whether to map group IDs (GIDs) based on the object name or object UUID when there's no gidNumber attribute found in an on-prem Active Directory instance synchronized to Azure Entra ID. this option is only applicable if id_attr_map is set to rfc2307. so if id_attr_map = rfc2307 and a group doesn't have a gidNumber defined in the directory, this setting determines the fallback method for mapping the group ID. and if this option isn't set at all? groups without a gidNumber will not be available to NSS. 😭
rfc2307_group_fallback_map = <name|uuid>
  • enable_hello — enables or disables user enrollment in Windows Hello authentication. if it's disabled, users will need to provide MFA for each login. every single one. 😮‍💨
enable_hello = false
  • hello_pin_min_length — the minimum length of the PIN for Windows Hello authentication. the value must be between 6 and 32 characters. no three-digit PINs bestie, we're better than that. 🔐
hello_pin_min_length = 8
  • hello_pin_retry_count — the number of invalid Hello PIN attempts allowed before the user is required to perform MFA. after successful MFA, the user will be prompted to set a new PIN. the value must be a non-negative integer. ⭐
hello_pin_retry_count = 3
  • hello_pin_prompt — customizes the prompt text shown when requesting the user's Linux Hello PIN. if it's not set, the default prompt is:
Use the Linux Hello PIN for this device.
hello_pin_prompt = Enter your device unlock PIN
  • entra_id_password_prompt — customizes the prompt text shown when requesting the user's Entra ID password. if it's not set, the default prompt is:
Use the password for your Office 365 or Microsoft online login.
entra_id_password_prompt = Enter your Microsoft 365 password
  • enable_sfa_fallback — determines whether password-only (single-factor) authentication is permitted when MFA is unavailable. disabled by default. 🚨
enable_sfa_fallback = true
  • cn_name_mapping — allows users to enter the short form of their username (e.g., 'dave') instead of the full UPN. so convenient honestly. 🎀
cn_name_mapping = true
  • local_groups — a comma-separated list of local groups that every Entra ID user should be a member of. for example, maybe you want all Entra ID users to be a member of the sudo group. WARNING: this setting will not REMOVE group member entries when groups are removed from this list. you must remove them manually. the way this setting only adds and never takes away… 🙈
local_groups = sudo,admin
  • sudo_groups — a comma-separated list of Azure Entra ID group object IDs whose members should be granted sudo access on this system. if local_sudo_group is not defined, the local group sudo will be used. 👑
sudo_groups = f3c9a7e4-7d5a-47e8-832f-3d2d92abcd12,5ba4ef1d-e454-4f43-ba7c-6fe6f1601915
  • local_sudo_group — the local group that should be given to users in any of the groups specified in sudo_groups. it only has an effect if sudo_groups is set. it removes the group from the user if they are no longer a member of the specified entra group. she cleans up after herself, we love to see it. 🧚
  • logon_script — a script that executes every time a user logs on. two environment variables get set: USERNAME and ACCESS_TOKEN. the ACCESS_TOKEN environment variable is an access token for the MS Graph. the token scope config option sets the comma-separated scopes that should be requested for the ACCESS_TOKEN. ACCESS_TOKEN will be empty during offline logon. the return code of the script determines how authentication proceeds: 0 is success, 1 is a soft failure and authentication will proceed, while 2 is a hard failure causing authentication to fail. so like, choose your return codes wisely. 💀
logon_script = /etc/himmelblau/logon.sh
  • logon_token_scopes — a comma-separated list of the scopes to be requested for the ACCESS_TOKEN during logon. these scopes MUST correspond to the API permissions assigned to the Entra Id Application specified by the app_id option. 🔑
logon_token_scopes = user.read,mail.read
  • app_id — specifies the Azure Entra ID application (client) ID used by Himmelblau for directory operations such as reading extended attributes (for example, the gidNumber attribute used in RFC 2307 idmapping).

if logon_token_app_id is not set, this application ID is also used when requesting access tokens for the user logon script.

Note: in the Azure Portal, for the application corresponding to app_id, make sure that the redirect URI himmelblau://Himmelblau.EntraId.BrokerPlugin is enabled under "Mobile and desktop applications" in the Authentication section. this allows Himmelblau to correctly handle interactive token redirection. don't skip this step bestie, it's giving "required". 🎯

app_id = d023f7aa-d214-4b59-911d-6074de623765
  • logon_token_app_id — specifies an alternate Azure Entra ID application (client) ID to be used exclusively for acquiring ACCESS_TOKEN values on behalf of the user during logon script execution. if it's not set, the value of app_id will be used instead. 🔄

this option lets you use a separate application registration that carries the specific API permissions required by logon scripts.

Note: in the Azure Portal, for the application corresponding to logon_token_app_id, make sure that the redirect URI https://login.microsoftonline.com/common/oauth2/nativeclient is enabled under "Mobile and desktop applications" in the Authentication section. this is required for Himmelblau to obtain tokens via the public client flow. ⭐

logon_token_app_id = 544e695f-5d78-442e-b14e-e114e95e640c
  • enable_experimental_mfa — a boolean option that enables the experimental multi-factor authentication (MFA) flow, which permits Hello authentication. this experimental flow may encounter failures in certain edge cases. if it's disabled, the system enforces the Device Authorization Grant (DAG) flow for MFA, which is more robust but does not support Hello authentication. by default, this option is enabled. 🧪✨
enable_experimental_mfa = true
  • enable_experimental_passwordless_fido — a boolean option that enables the experimental passwordless FIDO flow for Azure Entra ID authentication. when enabled, Himmelblau will attempt to authenticate with Entra ID using a FIDO2 security key without requiring a password. by default, this option is disabled. 🔑🦋
enable_experimental_passwordless_fido = true
  • name_mapping_script — specifies the path to an executable script used for mapping custom names to UPN names. the script MUST accept a single argument, which will always be a mapped name. the script MUST print the corresponding UPN (User Principal Name) to stdout. if the script doesn't recognize the input name, it MUST simply return the input name unchanged. this option is particularly useful in environments where direct UPN-to-CN mappings are impractical or where custom transformations are required. 🧚‍♀️

the script must handle the input gracefully and return the correct UPN — or the input name if it's unrecognized. errors must be handled, to avoid authentication failures.

name_mapping_script = /path/to/mapping_script.sh

Example Script:

#!/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
  • apply_policy — a boolean option that enables the application and enforcement of Intune policies to the authenticated user. 📋

by default, this option is disabled.

apply_policy = false
  • authority_host — specifies the hostname for Microsoft authentication. the default value is login.microsoftonline.com. 🌐
authority_host = login.microsoftonline.com

okay that's the [global] section handled bestie, but don't go anywhere — there's more coming 💖

  • db_path — where the cache database lives, bestie. This file stores cached auth data and device state, so like… it matters.
db_path = /var/cache/himmelblau/himmelblau.cache.db
  • hsm_type — how Himmelblau handles secure key storage. It decides whether you get a TPM-bound software HSM, an actual TPM, or the hybrid thing. The options are:
    • tpm_bound_soft_if_possible — software-based HSM that encrypts key material locally on the system, but binds the parent AuthCode to the TPM if available. 🫶
    • tpm — hardware TPM only, exclusively, for storing and binding cryptographic keys. No fallback, no plan B.
    • tpm_if_possible — try the hardware TPM if it's there; if not, fall back to the software HSM. Important: if the TPM has previously been used for key storage, the system will not fall back to the software HSM.

Default is tpm_bound_soft_if_possible.

Heads up: the old soft option is deprecated. Environments currently enrolled using soft get automatically migrated to tpm_bound_soft_if_possible, so nobody's left hanging 💅

Want to validate whether Himmelblau is actually using the hardware TPM? Run sudo aad-tool tpm for a status report. Iconic.

hsm_type = tpm_bound_soft_if_possible
  • tpm_tcti_name — the TCTI (Trusted Computing Technology Interface) to use when talking to a TPM for secure key ops. Only relevant when hsm_type is tpm or tpm_if_possible, iykyk.

Common values:

  • device:/dev/tpmrm0 — uses the kernel TPM resource manager device, which is the recommended default for most Linux systems ✨

Other TCTI strings may be needed depending on your system's TPM driver or config. This option gives you advanced control over how Himmelblau connects to the TPM for crypto operations.

tpm_tcti_name = device:/dev/tpmrm0
  • hsm_pin_path — where the HSM (Hardware Security Module) PIN is stored. That PIN protects sensitive cryptographic operations, so like… treat it with respect 🎀
hsm_pin_path = /var/lib/himmelblaud/hsm-pin
  • socket_path — path to the socket file the pam and nss modules use to talk to the Himmelblau daemon.
socket_path = /var/run/himmelblaud/socket
  • task_socket_path — path to the socket file for communication with the task daemon.
task_socket_path = /var/run/himmelblaud/task_sock
  • broker_socket_path — path to the socket file for communication with the broker DBus service.
broker_socket_path = /var/run/himmelblaud/broker_sock
  • home_prefix — the prefix used for user home directories.
home_prefix = /home/
  • home_attr — the attribute used to create a home directory for a user. Options are:
    • UUID (default)
    • SPN
    • CN
home_attr = UUID
  • home_alias — the symlinked alias for the user's home directory. Options are:
    • UUID
    • SPN (default)
    • CN
home_alias = SPN
  • shell — the default shell for users. Assigned when the user logs in.
shell = /bin/bash
  • idmap_range — the range of IDs used for user and group mappings.
🚨 When this option is modified, you SHOULD run: sudo aad-tool cache-clear --full That clears out old cached ID mappings so you don't get potential UID overlaps from stale cache data. Afterwards, restart himmelblaud.
idmap_range = 5000000-5999999
  • connection_timeout — timeout for connections to the authentication server. Default is 2 seconds.
connection_timeout = 5
  • cache_timeout — timeout for caching authentication data. Default is 300 seconds (5 minutes).
cache_timeout = 10
  • use_etc_skel — if true, Himmelblau uses the contents of /etc/skel when creating new user directories.
use_etc_skel = false
  • selinux — whether SELinux security labels get applied to users' home directories. Set to true to enable.
selinux = true
  • join_type — whether the system should join or register with Microsoft Entra ID.
join_type = register
  • user_map_file — path to a user-mapping file that maps local user accounts to Azure Entra ID user accounts so they can authenticate with Entra ID credentials. Each line must contain a single mapping entry in this format:
local_username:name@domain

Blank lines and lines beginning with # are ignored. If this option isn't set, the default path /etc/himmelblau/user-map is used.

user_map_file = /path/to/user_map
# Example user-map file entries:
# local_username:samaccountname@domain
alice:alice@contoso.com
bob:bob.smith@example.org
svcuser:service.account@tenant.local

🔐 OFFLINE BREAKGLASS CONFIGURATION

The [offline_breakglass] section configures Himmelblau's emergency offline authentication mechanism, used when Azure Entra ID is unreachable 😭

Offline breakglass lets Entra ID users who normally require multi-factor authentication (MFA) authenticate with their cached password when the host is offline. It's a controlled fallback for MFA-only users who would otherwise be completely locked out during an outage.

Single-factor authentication (SFA-only) users and Hello-PIN users already have offline sign-in capability and are unaffected by this setting. This option exists solely to extend limited offline access to MFA-enabled users when network connectivity to Entra ID can't be established.

🧚 [offline_breakglass]

This section controls whether and how Himmelblau may perform offline password authentication for MFA-enabled users in emergency conditions.

enabled

Boolean specifying whether offline breakglass mode is permitted.

When true, Himmelblau caches secure, salted password verifiers for MFA-enabled Entra ID users who successfully authenticate online. Those verifiers can then authenticate the same users when Entra ID is unreachable — so MFA users can log in with their cached password ✨

If false (the default), Himmelblau keeps caching password verifiers only for SFA-only users, and MFA-enabled users won't be able to authenticate when offline. The aad-tool(1) command aad-tool offline-breakglass will also have no effect.

⏰ Admins must enable this well in advance of an outage — password verifiers for MFA users are only stored following a successful online authentication. It's too late to enable this once Entra ID is already unreachable. No cap.
💀 Enabling offline breakglass carries significant risk. If a device is stolen or compromised and network access to Entra ID is blocked, attackers could effectively disable MFA protection by forcing the system into a simple password-only (SFA) auth state. Only enable this after careful consideration of your org's security posture and offline access requirements.

Also: this feature does not apply to passwordless accounts. If an MFA user signs in with a passwordless method, no password hash exists to cache, and offline breakglass can't function for that user. Periodt.

[offline_breakglass]
enabled = true
ttl = 2h
# Allow MFA users to authenticate offline for up to 2 hours

ttl

How long breakglass mode stays active once triggered. The value may include a suffix for the unit: m for minutes, h for hours, or d for days. No suffix? Then it's interpreted as seconds. After that period, offline breakglass mode automatically expires and normal authentication resumes 🌸

[offline_breakglass]
enabled = true
ttl = 1d
# Permit offline MFA logins for up to 24 hours after activation

🦋 SEE ALSO

himmelblaud(8), himmelblaud-tasks(8)

okay that's the whole page bestie, you ate that 💅 and for the record, this masterpiece is the Himmelblau Configuration man page, dated November 2024, and it's HIMMELBLAU.CONF(5) — go forth and configure responsibly 🎀✨

📦 where this page comes from