himmelblau.conf.5

.TH HIMMELBLAU.CONF "5" "November 2024" "Himmelblau Configuration" "File Formats"
.SH NAME
himmelblau.conf \- Configuration file for Himmelblau, enabling Azure Entra ID authentication on Linux.

.SH SYNOPSIS
.B /etc/himmelblau/himmelblau.conf

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

.TP
.B Restarting the Daemons
To apply changes, restart the Himmelblau services using the following systemd commands:

.EXAMPLES
.RS
.IP
sudo systemctl restart himmelblaud
.IP
sudo systemctl restart himmelblaud-tasks
.RE

.SH DESCRIPTION
The
.B 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.

.SH 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:
.RS 4
parameter = value
.RE

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

.SH PARAMETERS

.SS [global]
This section contains settings that apply globally to all operations of Himmelblau.

.TP
.B domains
.RE
A comma-separated list of primary domains for your Azure Entra ID tenants. This parameter is
.B 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
.B MUST
define an
.B 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.

.EXAMPLES
domains = example.com,example2.com

[example.com]
idmap_range = 5000000-5999999

[example2.com]
idmap_range = 6000000-6999999

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

.EXAMPLES
debug = true

.TP
.B pam_allow_groups
.RE
A comma-separated list of Entra Id Users and Groups permitted to access the system. Users should be specified by UPN. Groups may be specified using either their Object ID or their Name.

.EXAMPLES
pam_allow_groups = f3c9a7e4-7d5a-47e8-832f-3d2d92abcd12,EntraSudoersGroup,admin@himmelblau-idm.org

.TP
.B id_attr_map
.RE
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.

.EXAMPLES
id_attr_map = <name|uuid|rfc2307>

.TP
.B rfc2307_group_fallback_map
.RE
Specify whether to map group IDs (GIDs) based on the object name or object UUID when no
.B gidNumber
attribute is found in an on-prem Active Directory instance synchronized to Azure Entra ID. This option is only applicable if
.B id_attr_map
is set to
.B rfc2307.
If
.B id_attr_map = rfc2307
and a group does not have a
.B 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
.B gidNumber
will not be available to NSS.

.EXAMPLES
rfc2307_group_fallback_map = <name|uuid>

.TP
.B odc_provider
.RE
Specifies the hostname for sending federationProvider requests.

.EXAMPLES
odc_provider = odc.officeapps.live.com

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

.EXAMPLES
enable_hello = false

.TP
.B hello_pin_min_length
.RE
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

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

.EXAMPLES
enable_sfa_fallback = true

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

.EXAMPLES
cn_name_mapping = true

.TP
.B local_groups
.RE
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

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

.EXAMPLES
logon_script = /etc/himmelblau/logon.sh

.TP
.B logon_token_scopes
.RE
A comma-separated list of the scopes to be requested for the ACCESS_TOKEN during logon. These scopes
.B MUST
correspond to the API permissions assigned to the Entra Id Application specified by the
.B app_id
domain option.

.EXAMPLES
logon_token_scopes = user.read,mail.read

.TP
.B enable_experimental_mfa
.RE
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

.TP
.B name_mapping_script
.RE
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:
.RS 4
.nf
#!/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
.fi
.RE

.TP
.B apply_policy
.RE
A boolean option that enables the experimental application of Intune policies to the authenticated user. This setting does not mark the device as compliant in Entra ID, nor does it register the device as managed in Intune. Instead, it attempts to apply any assigned Intune policies to the user session.

For this feature to function correctly, an `app_id` must be defined for the corresponding domain, and the "DeviceManagementConfiguration.Read.All" API permission must be granted to it.

By default, this option is disabled.

.EXAMPLES
apply_policy = false

.TP
.B authority_host
.RE
Specifies the hostname for Microsoft authentication. The default value is
.B login.microsoftonline.com.

.EXAMPLES
authority_host = login.microsoftonline.com

.TP
.B db_path
.RE
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

.TP
.B hsm_pin_path
.RE
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

.TP
.B socket_path
.RE
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

.TP
.B task_socket_path
.RE
The path to the socket file for communication with the task daemon.

.EXAMPLES
task_socket_path = /var/run/himmelblaud/task_sock

.TP
.B broker_socket_path
.RE
The path to the socket file for communication with the broker DBus service.

.EXAMPLES
broker_socket_path = /var/run/himmelblaud/broker_sock

.TP
.B home_prefix
.RE
The prefix to use for user home directories.

.EXAMPLES
home_prefix = /home/

.TP
.B home_attr
.RE
The attribute used to create a home directory for a user. Available options include:
.RS
.IP
\- UUID (default)
.IP
\- SPN
.IP
\- CN
.RE

.EXAMPLES
home_attr = UUID

.TP
.B home_alias
.RE
The symlinked alias for the user's home directory. Available options include:
.RS
.IP
\- UUID
.IP
\- SPN (default)
.IP
\- CN
.RE

.EXAMPLES
home_alias = SPN

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

.EXAMPLES
shell = /bin/bash

.TP
.B idmap_range
.RE
Specifies the range of IDs to be used for the user and group mappings.

When this option is modified, you
.B SHOULD
run:
.RS
.IP
sudo aad-tool cache-clear --really
.RE

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

.EXAMPLES
idmap_range = 5000000-5999999

.TP
.B connection_timeout
.RE
The timeout for connections to the authentication server. Default is 2 seconds.

.EXAMPLES
connection_timeout = 5

.TP
.B cache_timeout
.RE
The timeout for caching authentication data. Default is 300 seconds (5 minutes).

.EXAMPLES
cache_timeout = 10

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

.EXAMPLES
use_etc_skel = false

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

.EXAMPLES
selinux = true

.SH DOMAIN-SPECIFIC SECTIONS
Overrides can be defined for individual domains by using a section named after the domain in square brackets.

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

.TP
.B odc_provider
.RE
Overrides the `odc_provider` value for this domain.

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

.TP
.B home_prefix
.RE
Overrides the `home_prefix` value for this domain.

.EXAMPLES
[example.com]
home_prefix = /home/

.TP
.B home_attr
.RE
Overrides the `home_attr` value for this domain.

.EXAMPLES
[example.com]
home_attr = UUID

.TP
.B home_alias
.RE
Overrides the `home_alias` value for this domain.

.EXAMPLES
[example.com]
home_alias = SPN

.TP
.B shell
.RE
Overrides the `shell` value for this domain.

.EXAMPLES
[example.com]
shell = /bin/bash

.TP
.B idmap_range
.RE
Overrides the `idmap_range` value for this domain.

When this option is modified, you
.B SHOULD
run:
.RS
.IP
sudo aad-tool cache-clear --really
.RE

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

.EXAMPLES
[example.com]
idmap_range = 5000000-5999999

.TP
.B logon_token_app_id
.RE
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
.B 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.

.PP
\fBNote:\fR In the Azure Portal for the application corresponding to \fBlogon_token_app_id\fR, ensure that the redirect URI \fIhttps://login.microsoftonline.com/common/oauth2/nativeclient\fR is enabled in the application's Authentication section under “Mobile and desktop applications.” This is required so that Himmelblau can obtain the necessary tokens.

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

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

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

.PP
\fBNote:\fR For the application corresponding to \fBapp_id\fR, ensure that the redirect URI \fIhimmelblau://Himmelblau.EntraId.BrokerPlugin\fR 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.

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

.SH SEE ALSO
.BR himmelblaud(8),
.BR himmelblaud-tasks(8)