NAME

himmelblau.conf - Configuration file for Himmelblau, enabling Azure Entra ID authentication on Linux.

SYNOPSIS

/etc/himmelblau/himmelblau.conf

HOW CONFIGURATION CHANGES ARE APPLIED

Changes to the configuration file /etc/himmelblau/himmelblau.conf only take effect after restarting the Himmelblau daemons. This includes the himmelblaud daemon, which handles authentication, and the himmelblaud-tasks daemon, which processes related tasks.

Restarting the Daemons

To apply changes, restart the Himmelblau services using the following systemd commands:

EXAMPLES

sudo systemctl restart himmelblaud 

sudo systemctl restart himmelblaud-tasks

DESCRIPTION

The himmelblau.conf file is the primary configuration file for the Himmelblau authentication module. It defines global and optional settings required for Azure Entra ID-based authentication and device management.

FILE FORMAT

The file consists of sections headed by a name enclosed in square brackets. Each section contains parameters and their values in the format: 

parameter = value Lines beginning with a '#' are comments and are ignored by the parser.

PARAMETERS

[global]

This section contains settings that apply globally to all operations of Himmelblau.

domain

The primary Azure Entra ID domain name used for authentication. This value SHOULD match the domain name that users enter when signing in (for example, the domain portion of their UPN). In most cases, this will be the primary domain of your Azure Entra ID tenant. If your organization uses multiple verified domains or aliases, choose the one that your users actually use to sign in. This parameter is REQUIRED for successful authentication. If it is not specified, no users will be permitted to authenticate.

EXAMPLES

domain = example.com

debug

A boolean option that enables debug-level logging. When set to true, debug messages are output to the system journal.

EXAMPLES

debug = true

pam_allow_groups

A 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 may not be used because these names are not guaranteed to be unique in Entra Id.

EXAMPLES

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 recommeneded. By name mapping is the default.

EXAMPLES

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 no gidNumber attribute is 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. If id_attr_map = rfc2307 and a group does not have a gidNumber defined in the directory, this setting determines the fallback method for mapping the group ID. If this option is not set, groups without a gidNumber will not be available to NSS.

EXAMPLES

rfc2307_group_fallback_map = <name|uuid>

enable_hello

Enables or disables user enrollment in Windows Hello authentication. If disabled, users will need to provide MFA for each login.

EXAMPLES

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.

EXAMPLES

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.

EXAMPLES

hello_pin_retry_count = 3

hello_pin_prompt

Customizes the prompt text shown when requesting the user’s Linux Hello PIN. If not set, the default prompt is:

Use the Linux Hello PIN for this device.

EXAMPLES

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 not set, the default prompt is:

Use the password for your Office 365 or Microsoft online login.

EXAMPLES

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.

EXAMPLES

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.

EXAMPLES

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, you may wish for 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.

EXAMPLES

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.

EXAMPLES

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. Only has an affect if sudo_groups is set. Removes group from user if they are no longer a member of the specified entra group.

logon_script

A script that will execute every time a user logs on. Two environment variables are 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.

EXAMPLES

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.

EXAMPLES

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, ensure 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.

EXAMPLES

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 not set, the value of app_id will be used instead. This option allows using 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, ensure 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.

EXAMPLES

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 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.

EXAMPLES

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.

EXAMPLES

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 does not 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 unrecognized. Errors must be handled to avoid authentication failures.

EXAMPLES

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.

EXAMPLES

apply_policy = false

enable_experimental_intune_custom_compliance

A boolean option that enables support for Linux Intune Custom Compliance policies. This feature is experimental and not yet fully functional. While policy settings should be applied locally, the compliance status is not reliably reported to Intune, and failed policies do not currently block authentication. By default, this option is disabled. This option requires apply_policy = true.

EXAMPLES

enable_experimental_intune_custom_compliance = true

authority_host

Specifies the hostname for Microsoft authentication. The default value is login.microsoftonline.com.

EXAMPLES

authority_host = login.microsoftonline.com

db_path

The location of the cache database. This file is used to store cached authentication data and device state.

EXAMPLES

db_path = /var/cache/himmelblau/himmelblau.cache.db

hsm_type

Specifies how Himmelblau should handle secure key storage. This option determines whether to use a TPM (Trusted Platform Module) bound software-based HSM, a TPM, or a hybrid approach. The available options are:

  • tpm_bound_soft_if_possible – Use a software-based HSM that encrypts key material locally on the system, but binds the parent AuthCode to the TPM, if available.

  • tpm – Use a hardware TPM exclusively for storing and binding cryptographic keys.

  • tpm_if_possible – Attempt to use a hardware TPM if available; if not, fall back to the software HSM. If the TPM has previously been used for key storage, the system will not fall back to the software HSM. The default is tpm_bound_soft_if_possible his setting is important for protecting sensitive cryptographic keys in a secure environment, reducing the risk of compromise if the system is breached.Note that the old soft option has been deprecated. Environments currently enrolled using soft will be automatically migrated to tpm_bound_soft_if_possible. To validate whether Himmelblau is utilizing the hardware TPM, run the command sudo aad-tool tpm for a status report.

EXAMPLES

hsm_type = tpm_bound_soft_if_possible

tpm_tcti_name

Specifies the TCTI (Trusted Computing Technology Interface) to use when communicating with a Trusted Platform Module (TPM) for secure key operations. This setting is only relevant when hsm_type is set to tpm or tpm_if_possible. Common values include:

  • device:/dev/tpmrm0 – This uses the kernel TPM resource manager device, which is the recommended default for most Linux systems. Other TCTI strings may be required depending on your system’s TPM driver or configuration. This option allows advanced control over how Himmelblau connects to the TPM for performing cryptographic operations.
EXAMPLES

tpm_tcti_name = device:/dev/tpmrm0

hsm_pin_path

The location where the HSM (Hardware Security Module) PIN will be stored. This PIN is used to protect sensitive cryptographic operations.

EXAMPLES

hsm_pin_path = /var/lib/himmelblaud/hsm-pin

socket_path

The path to the socket file for communication between the pam and nss modules and the Himmelblau daemon.

EXAMPLES

socket_path = /var/run/himmelblaud/socket

task_socket_path

The path to the socket file for communication with the task daemon.

EXAMPLES

task_socket_path = /var/run/himmelblaud/task_sock

broker_socket_path

The path to the socket file for communication with the broker DBus service.

EXAMPLES

broker_socket_path = /var/run/himmelblaud/broker_sock

home_prefix

The prefix to use for user home directories.

EXAMPLES

home_prefix = /home/

home_attr

The attribute used to create a home directory for a user. Available options include:

  • UUID (default)

  • SPN

  • CN

EXAMPLES

home_attr = UUID

home_alias

The symlinked alias for the user's home directory. Available options include:

  • UUID

  • SPN (default)

  • CN

EXAMPLES

home_alias = SPN

shell

The default shell for users. This will be assigned when the user logs in.

EXAMPLES

shell = /bin/bash

idmap_range

Specifies the range of IDs to be used for the user and group mappings. When this option is modified, you SHOULD run:

sudo aad-tool cache-clear --really To ensure that old cached ID mappings are cleared, preventing potential UID overlaps caused by stale cache data.

EXAMPLES

idmap_range = 5000000-5999999

connection_timeout

The timeout for connections to the authentication server. Default is 2 seconds.

EXAMPLES

connection_timeout = 5

cache_timeout

The timeout for caching authentication data. Default is 300 seconds (5 minutes).

EXAMPLES

cache_timeout = 10

use_etc_skel

If set to true, Himmelblau will use the contents of /etc/skel when creating new user directories.

EXAMPLES

use_etc_skel = false

selinux

Whether SELinux security labels should be applied to users' home directories. Set to true to enable.

EXAMPLES

selinux = true

join_type

Specifies whether the system should join or register with Microsoft Entra ID.

EXAMPLES

join_type = register

user_map_file

Specifies the path to a user-mapping file used to map local user accounts to Azure Entra ID user accounts, allowing them to authenticate using Entra ID credentials. Each line of the file must contain a single mapping entry in the format:

local_username:name@domain

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

EXAMPLES

user_map_file = /path/to/user_map

EXAMPLES

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 unavailable.

Offline breakglass allows Entra ID users who normally require multi-factor authentication (MFA) to authenticate with their cached password when the host is offline. This feature provides a controlled fallback for MFA-only users who would otherwise be unable to sign in 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 cannot 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 value specifying whether offline breakglass mode is permitted.

When set to true, Himmelblau will cache secure, salted password verifiers for MFA-enabled Entra ID users who successfully authenticate online. These verifiers can then be used to authenticate the same users when Entra ID is unreachable, allowing MFA users to log in using their cached password.

If this option is set to false (the default), Himmelblau will continue to cache password verifiers only for SFA-only users, and MFA-enabled users will not be able to authenticate when offline. The aad-tool(1) command aad-tool offline-breakglass will also have no effect.

Administrators must enable this option well in advance of an outage, as password verifiers for MFA users are only stored following a successful online authentication. It is too late to enable this feature once Entra ID is already unreachable.

Enabling offline breakglass mode 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) authentication state. Administrators should enable this mode only after careful consideration of their organization’s security posture and offline access requirements.

This feature does not apply to passwordless accounts. If an MFA user signs in using a passwordless method, no password hash exists to cache, and offline breakglass cannot function for that user.

EXAMPLES

[offline_breakglass] enabled = true ttl = 2h

Allow MFA users to authenticate offline for up to 2 hours

ttl

Specifies how long breakglass mode should remain active once triggered. The value may include a suffix to indicate the unit of time: m for minutes, h for hours, or d for days. If no suffix is provided, the value is interpreted as seconds. After the specified period, offline breakglass mode automatically expires and normal authentication resumes.

EXAMPLES

[offline_breakglass] enabled = true ttl = 1d

Permit offline MFA logins for up to 24 hours after activation

SEE ALSO

himmelblaud(8), himmelblaud-tasks(8)