1. Manuals
  2. Tumbleweed
  3. himmelblau
  4. himmelblau.conf(5)

Scroll to navigation

HIMMELBLAU.CONF(5) File Formats HIMMELBLAU.CONF(5)

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.

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

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.


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.

domain = example.com


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

debug = true


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.

pam_allow_groups = f3c9a7e4-7d5a-47e8-832f-3d2d92abcd12,5ba4ef1d-e454-4f43-ba7c-6fe6f1601915,admin@himmelblau-idm.org


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.

id_attr_map = <name|uuid|rfc2307>


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.

rfc2307_group_fallback_map = <name|uuid>


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

enable_hello = false


The minimum length of the PIN for Windows Hello authentication. The value must be between 6 and 32 characters.

hello_pin_min_length = 8


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


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.

hello_pin_prompt = Enter your device unlock PIN


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.

entra_id_password_prompt = Enter your Microsoft 365 password


Determines whether password-only (single-factor) authentication is permitted when MFA is unavailable. Disabled by default.

enable_sfa_fallback = true


Allows users to enter the short form of their username (e.g., 'dave') instead of the full UPN.

cn_name_mapping = true


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.

local_groups = sudo,admin


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


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.


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.

logon_script = /etc/himmelblau/logon.sh


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


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.

app_id = d023f7aa-d214-4b59-911d-6074de623765


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.

logon_token_app_id = 544e695f-5d78-442e-b14e-e114e95e640c


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.

enable_experimental_mfa = true


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


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.

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


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


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

enable_experimental_intune_custom_compliance = true


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

authority_host = login.microsoftonline.com


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

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


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

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.

hsm_type = tpm_bound_soft_if_possible


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.

tpm_tcti_name = device:/dev/tpmrm0


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

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


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

socket_path = /var/run/himmelblaud/socket


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

task_socket_path = /var/run/himmelblaud/task_sock


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

broker_socket_path = /var/run/himmelblaud/broker_sock


The prefix to use for user home directories.

home_prefix = /home/


The attribute used to create a home directory for a user. Available options include:
- UUID (default)
- SPN
- CN

home_attr = UUID


The symlinked alias for the user's home directory. Available options include:
- UUID
- SPN (default)
- CN

home_alias = SPN


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

shell = /bin/bash


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

To ensure that old cached ID mappings are cleared, preventing potential UID overlaps caused by stale cache data. Afterwards, restart himmelblaud.

idmap_range = 5000000-5999999


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

connection_timeout = 5


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

cache_timeout = 10


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

use_etc_skel = false


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

selinux = true


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

join_type = register


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.

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


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.

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


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.

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

SEE ALSO

himmelblaud(8), himmelblaud-tasks(8)

November 2024 Himmelblau Configuration