/etc/himmelblau/himmelblau.conf. The file uses INI-style syntax. All options described on this page belong to the [global] section, which applies system-wide. You can override domain-specific options (marked domain-specific below) in a per-domain section such as [domain.example.com].
File location
Format
Full example
Core settings
The primary Azure Entra ID domain name used for authentication. This value should match the domain portion that users enter when signing in (for example, the domain part of their UPN).In most cases this is the primary domain of your Entra ID tenant. If your organization uses multiple verified domains or aliases, choose the one your users actually sign in with.If not specified, the domain is extracted from the UPN of the first user to authenticate and looked up in Entra ID.Default: extracted from the first user’s UPN.Example:
domain = example.comThe 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.In the Azure Portal for the application corresponding to app_id, ensure that the redirect URI himmelblau://Himmelblau.EntraId.BrokerPlugin is enabled under Mobile and desktop applications in the Authentication section.Default: none (domain-specific).Example: app_id = d023f7aa-d214-4b59-911d-6074de623765Specifies whether the system should join or register with Microsoft Entra ID.Accepted values:
join, register.Example: join_type = registerA comma-separated list of Entra ID users and groups permitted to access the system. Users should be specified by UPN. Groups must be specified using their Object ID GUID — group names are not guaranteed to be unique in Entra ID and cannot be used.If not set, all Entra ID users are permitted to authenticate. Domain-specific.Default: all users permitted.Example:
pam_allow_groups = f3c9a7e4-7d5a-47e8-832f-3d2d92abcd12,admin@example.comUser and group mapping
The path prefix used when constructing user home directories. Domain-specific.Example:
home_prefix = /home/entra/The attribute used to name the user’s home directory. Domain-specific.Accepted values:
uuid— directory is named by the user’s Entra ID object UUIDspn— directory is named by the user’s Service Principal Name (UPN)cn— directory is named by the user’s Common Name
home_attr = uuidThe attribute used to create a symlinked alias pointing to the user’s home directory. Domain-specific.Accepted values:
uuid, spn, cn.Example: home_alias = spnThe default login shell assigned to users at sign-in. Domain-specific.Example:
shell = /bin/zshSpecifies how UID and GID values are derived for Entra ID users and groups.Accepted values:
name— map by object name (recommended for most deployments)uuid— map by object UUIDrfc2307— useuidNumber/gidNumberattributes synchronized from an on-premises Active Directory instance (recommended when on-prem sync is in use)
id_attr_map = nameThe range of UID and GID values to allocate for Entra ID users and groups. Format:
low-high. Domain-specific.When you change this value, run sudo aad-tool cache-clear --full to clear stale cached ID mappings, then restart himmelblaud.Example: idmap_range = 10000000-10999999The range of subordinate UIDs and GIDs (
subuid/subgid) allocated for container support (Podman, rootless containers, and similar tools).Himmelblau automatically adds entries to /etc/subuid and /etc/subgid for each user at login. Each user receives a 65536-ID slice from this range, allocated deterministically based on a hash of their username.Example: subid_range = 2100000000-4200000000Allows users to enter the short form of their username (for example,
dave) instead of the full UPN.Example: cn_name_mapping = falsePath to an executable script used to map custom names to UPN names. The script must accept a single argument (the mapped name) and print the corresponding UPN to stdout. If the name is not recognized, the script must return the input unchanged.This is useful in environments where direct UPN-to-CN mappings are impractical or where custom name transformations are required.Default: none.Example:
name_mapping_script = /etc/himmelblau/map-names.shPath to a file that maps local user accounts to Entra ID user accounts, allowing local users to authenticate using Entra ID credentials.Each line must follow the format Example:
local_username:name@domain. Blank lines and lines beginning with # are ignored.Example file contents:user_map_file = /etc/himmelblau/user-mapWhen
id_attr_map = rfc2307 is set, specifies the fallback method for mapping a group GID when no gidNumber attribute is found in the directory. If not set, groups without a gidNumber will not be visible to NSS.Only applicable when id_attr_map = rfc2307.Accepted values: name, uuid.Default: none.Example: rfc2307_group_fallback_map = nameAuthentication
Enables or disables user enrollment in Windows Hello authentication. When disabled, users must complete MFA at every login.For OIDC providers (when
oidc_issuer_url is set), Hello enrollment requires the client application to allow refresh tokens and include the offline_access scope.Example: enable_hello = falseControls whether passwordless authentication (Microsoft Authenticator app approval without a password) is offered during Entra ID authentication. When enabled, Himmelblau includes the passwordless option in authentication requests. When disabled, users are prompted for a password followed by MFA.Example:
enable_passwordless = falseEnables local Time-based One-Time Password (TOTP) authentication in combination with Windows Hello. When enabled, users must authenticate with both their Hello PIN and a TOTP generated by a standard authenticator app.The TOTP secret is enrolled and enforced locally on the host, independent of any cloud-based MFA. Users who have not yet enrolled a TOTP secret will be prompted to do so.When Hello TOTP is enabled, Hello + TOTP is accepted for remote services (SSH and similar). Without it, remote logins bypass Hello and require cloud MFA.Example:
enable_hello_totp = trueThe minimum number of characters required for a Hello PIN. Must be between 6 and 32.Example:
hello_pin_min_length = 8The number of invalid Hello PIN attempts permitted before the user must complete MFA. After successful MFA, the user is prompted to set a new PIN.Example:
hello_pin_retry_count = 5The prompt text shown when requesting the user’s Hello PIN.Example:
hello_pin_prompt = Enter your device unlock PINAllows Windows Hello PIN authentication for remote services without requiring Hello TOTP. When enabled, remote logins (SSH and similar) may use Hello PIN alone, restoring legacy behavior.Example:
allow_remote_hello = trueDetermines whether password-only (single-factor) authentication is permitted when MFA is unavailable.Example:
enable_sfa_fallback = trueEnables the experimental MFA flow, which permits Hello authentication. This flow may encounter failures in certain edge cases. When disabled, Himmelblau enforces the Device Authorization Grant (DAG) flow for MFA, which is more robust but does not support Hello.Example:
enable_experimental_mfa = falseEnables the experimental passwordless FIDO flow for Entra ID authentication. When enabled, Himmelblau attempts to authenticate using a FIDO2 security key without requiring a password.Example:
enable_experimental_passwordless_fido = trueThe number of seconds to wait for the user to insert and activate their FIDO2/passkey security key.Example:
fido_timeout = 60The message displayed to the user when FIDO/passkey authentication is initiated and they need to insert their security key.Example:
fido_prompt = Please insert your security key.The message displayed to the user when FIDO/passkey authentication requires a user-presence gesture (touching the security key).Example:
fido_presence_prompt = Please touch your security key.A preferred MFA method to use during authentication. When set, Himmelblau attempts to use this method instead of the default configured in the user’s Entra ID profile. If not set or if the specified method is unavailable, the default MFA method is used.Accepted values:
PhoneAppNotification— Authenticator app push notificationCompanionAppsNotification— MFA via Outlook app or Authenticator LitePhoneAppOTP— Authenticator app verification codeOneWaySMS— Text message codeTwoWayVoiceMobile— Phone call to mobileTwoWayVoiceAlternateMobile— Phone call to alternate mobile numberTwoWayVoiceOffice— Phone call to officeConsolidatedTelephony— Call or text message
mfa_method = TwoWayVoiceMobileGroups and permissions
A comma-separated list of local groups that every Entra ID user should be a member of.Default: none.Example:
local_groups = sudo,adminA comma-separated list of Entra ID group Object ID GUIDs whose members should be granted
sudo access on this system. If local_sudo_group is not defined, the local group sudo is used. Domain-specific.Default: none.Example: sudo_groups = f3c9a7e4-7d5a-47e8-832f-3d2d92abcd12,5ba4ef1d-e454-4f43-ba7c-6fe6f1601915The local group assigned to users who are members of any group listed in
sudo_groups. Only has an effect when sudo_groups is set. Membership is removed automatically if the user leaves the specified Entra ID group.Example: local_sudo_group = wheelNetwork and timeouts
The timeout in seconds for connections to the authentication server.Example:
connection_timeout = 5The timeout in seconds for cached authentication data.Example:
cache_timeout = 10The hostname used for Microsoft authentication. Change this for sovereign cloud deployments (for example,
login.microsoftonline.us for Azure US Government). Domain-specific.Example: authority_host = login.microsoftonline.usThe OpenID Connect (OIDC) issuer URL used by Himmelblau to discover OIDC provider metadata and endpoints. Setting this option enables generic OIDC authentication, allowing Himmelblau to authenticate against any standards-compliant OIDC provider rather than using the built-in Entra ID defaults.When set,
app_id is required and is used as the OIDC client identifier. If enable_hello = true (the default), the client application must allow refresh tokens and include the offline_access scope.The issuer URL must exactly match the issuer value advertised by the provider, including any required path components.Default: none (Himmelblau uses its native Entra ID authentication flow).Example: oidc_issuer_url = https://login.microsoftonline.com/0656e57d-a8fc-4aa4-8366-8045787115ca/v2.0Security
Specifies how Himmelblau handles secure key storage.Accepted values:Run
tpm_bound_soft_if_possible— uses a software-based HSM that encrypts key material locally, but binds the parent AuthCode to the TPM if available (recommended default)tpm— uses a hardware TPM exclusively for storing and binding cryptographic keystpm_if_possible— attempts to use a hardware TPM if available; falls back to software HSM otherwise (will not fall back if the TPM has previously been used for key storage)
The old
soft value has been deprecated. Environments enrolled with soft are automatically migrated to tpm_bound_soft_if_possible.sudo aad-tool tpm to confirm whether Himmelblau is using the hardware TPM.Example: hsm_type = tpmThe filesystem path where the HSM PIN is stored. This PIN protects sensitive cryptographic operations. Can also be set via the
HIMMELBLAU_HSM_PIN_PATH environment variable.Example: hsm_pin_path = /etc/himmelblau/hsm-pinThe TCTI (Trusted Computing Technology Interface) string used when communicating with a TPM. Only relevant when
hsm_type is tpm or tpm_if_possible.device:/dev/tpmrm0 uses the kernel TPM resource manager device, which is the recommended default for most Linux systems.Example: tpm_tcti_name = device:/dev/tpm0Whether SELinux security labels are applied to users’ home directories.Example:
selinux = falseLogging and debug
Enables debug-level logging. When set to
true, debug messages are written to the system journal.Example: debug = truePaths
The filesystem path to the cache database, which stores cached authentication data and device state.Example:
db_path = /var/cache/himmelblau/himmelblau.cache.dbThe path to the Unix socket used for communication between the PAM/NSS modules and the Himmelblau daemon.Example:
socket_path = /tmp/himmelblaud.sockThe path to the Unix socket used for communication with the tasks daemon.Example:
task_socket_path = /tmp/task.sockThe path to the Unix socket used for communication with the broker DBus service.Example:
broker_socket_path = /tmp/broker.sockAdvanced
Enables the application and enforcement of Intune device compliance policies during non-OIDC authentication. When enabled (the default), non-compliant devices may be denied authentication according to configured policies. This setting does not affect OIDC-based authentication flows.Example:
apply_policy = falsePath to a script that executes every time a user logs on. The script receives two environment variables:
USERNAME— the authenticated user’s nameACCESS_TOKEN— an MS Graph access token (empty during offline logon)
0— success1— soft failure (authentication proceeds)2— hard failure (authentication is denied)
logon_token_scopes to specify the scopes requested for ACCESS_TOKEN.Default: none.Example: logon_script = /etc/himmelblau/logon.shAn alternate Entra ID application (client) ID used exclusively for acquiring
ACCESS_TOKEN values during logon script execution. If not set, app_id is used instead.This allows a separate application registration with the specific API permissions required by logon scripts.In the Azure Portal for this application, ensure the redirect URI https://login.microsoftonline.com/common/oauth2/nativeclient is enabled under Mobile and desktop applications. Domain-specific.Default: none.Example: logon_token_app_id = 544e695f-5d78-442e-b14e-e114e95e640cA comma-separated list of OAuth scopes requested for
ACCESS_TOKEN during logon. These scopes must correspond to the API permissions assigned to the Entra ID application specified by app_id.Default: none.Example: logon_token_scopes = user.read,mail.readThe prompt text shown when requesting the user’s Entra ID password.Example:
entra_id_password_prompt = Enter your Microsoft 365 passwordA comma-separated list of PAM service names that always require MFA, regardless of the
allow_console_password_only setting. These are typically remote access services where password-only authentication must never be permitted.The PAM service name is the name passed by the application when calling pam_start() (for example, sshd, login, gdm-password). Entries are matched as substrings, so ssh matches ssh, sshd, openssh, and so on.Example: password_only_remote_services_deny_list = ssh,telnet,vnc,xrdpEnables password-only (single-factor) authentication for local console logins (TTY, GDM, SDDM, LightDM). When enabled, Himmelblau attempts to authenticate using only the user’s password for local sessions. If Entra ID requires MFA via Conditional Access, the user is prompted for MFA automatically.This setting does not affect remote authentication (SSH and similar), which always requires MFA unless the user has Hello + TOTP configured or
allow_remote_hello is enabled.Remote connections are detected using:PAM_RHOST— if the remote host is set to a non-localhost valuePAM_SERVICE— if the service name matches an entry inpassword_only_remote_services_deny_listPAM_TTY— if the terminal name containsssh(fallback)
false to require MFA for all logins including local console.Example: allow_console_password_only = falseWhen set to
true, Himmelblau copies the contents of /etc/skel into newly created user home directories.Example: use_etc_skel = true