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.


A comma-separated list of primary domains for your Azure Entra ID tenants. This parameter is REQUIRED for successful authentication. If this option is not specified, no users will be permitted to authenticate. The first user to authenticate to each domain will become the owner of the device object in the directory.

Specify ONLY the primary domain for each tenant. Specifying multiple custom domains which belong to a single tenant will cause an idmap range overlap and the himmelblaud daemon will NOT start.

If multiple domains are specified, you MUST define an idmap_range for each domain to avoid conflicts in user and group ID mappings. Overlapping ID ranges will cause the idmapper to throw a critical error and stop the daemon. This safeguard ensures that two users are not mistakenly mapped to the same UID.

domains = example.com,example2.com

[example.com] idmap_range = 5000000-5999999

[example2.com] idmap_range = 6000000-6999999


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.

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>


Specifies the hostname for sending federationProvider requests.

odc_provider = odc.officeapps.live.com


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 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. The app_id option MUST be set for each domain to ensure the logon_token_scopes option has the correct API permissions. Failing to do so will prevent the logon_script from executing.

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

logon_token_scopes = user.read,mail.read


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 software-based HSM, a TPM (Trusted Platform Module), or a hybrid approach.

The available options are:

• soft – Use a software-based HSM that encrypts key material locally on the system.

• 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 soft

hsm_type = soft


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

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

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

DOMAIN-SPECIFIC SECTIONS

Overrides can be defined for individual domains by using a section named after the domain in square brackets.

[example.com]

This section allows customization of specific parameters for the domain example.com. Domain-specific sections override global values for the specified domain.


Overrides the `odc_provider` value for this domain.

[example.com] odc_provider = custom.odcprovider.example.com


Overrides the `home_prefix` value for this domain.

[example.com] home_prefix = /home/


Overrides the `home_attr` value for this domain.

[example.com] home_attr = UUID


Overrides the `home_alias` value for this domain.

[example.com] home_alias = SPN


Overrides the `shell` value for this domain.

[example.com] shell = /bin/bash


Overrides the `idmap_range` value for this domain.

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.

[example.com] idmap_range = 5000000-5999999


Specifies the Entra ID application ID to be used when requesting an ACCESS_TOKEN on behalf of the user for the logon script. If not set, the domain’s app_id will be used instead.

This option allows configuring a separate application ID specifically for logon token requests, ensuring the correct API permissions are applied.

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 in the application's Authentication section under “Mobile and desktop applications.” This is required so that Himmelblau can obtain the necessary tokens.

[example.com] logon_token_app_id = 544e695f-5d78-442e-b14e-e114e95e640c


Specifies the Entra ID application identifier that permits Himmelblau to fetch the gidNumber extended attribute using the GroupMember.Read.All API permission for rfc2307 idmapping.

If logon_token_app_id is not set, this app_id will also be used for requesting access tokens for the logon script.

Note: For the application corresponding to app_id, ensure that the redirect URI himmelblau://Himmelblau.EntraId.BrokerPlugin is added in the application's Authentication section under “Mobile and desktop applications” in the Azure Portal. This allows Himmelblau to properly handle token redirection for the extended attribute lookups.

[example.com] app_id = d023f7aa-d214-4b59-911d-6074de623765

SEE ALSO

himmelblaud(8), himmelblaud-tasks(8)

November 2024 Himmelblau Configuration