| 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.
- Restarting the Daemons
- 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:
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 Users and Groups permitted to access the system. Groups must be specified using their Object ID (not UPN) due to Azure's restrictions on reading group names.
pam_allow_groups = f3c9a7e4-7d5a-47e8-832f-3d2d92abcd12,d98c8e1d-7f8a-4597-babc-9d3b781ef456
Specifies whether to map user and group IDs based on the object name or object UUID. Mapping by name is recommended for more consistent SSH authentication.
id_attr_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
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_to_upn_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.
logon_script = /etc/himmelblau/logon.sh
A comma-separated list of the scopes to be requested for the ACCESS_TOKEN during logon.
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
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
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
SEE ALSO¶
himmelblaud(8), himmelblaud-tasks(8)
| November 2024 | Himmelblau Configuration |