Skip to content

Commit

Permalink
Merge pull request #311 from himmelblau-idm/stable-0.7.x_dag_flow
Browse files Browse the repository at this point in the history
Add DAG flow as a fallback for MFA
  • Loading branch information
dmulder authored Dec 4, 2024
2 parents b48d0bb + f4db13f commit f24e0e6
Show file tree
Hide file tree
Showing 10 changed files with 446 additions and 18 deletions.
4 changes: 2 additions & 2 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ members = [
resolver = "2"

[workspace.package]
version = "0.7.7"
version = "0.7.8"
authors = [
"David Mulder <[email protected]>"
]
Expand All @@ -40,7 +40,7 @@ tracing-subscriber = "^0.3.17"
tracing = "^0.1.37"
himmelblau_unix_common = { path = "src/common" }
kanidm_unix_common = { path = "src/glue" }
libhimmelblau = { version = "0.3.9" }
libhimmelblau = { version = "0.4.1" }
clap = { version = "^4.5", features = ["derive", "env"] }
clap_complete = "^4.4.1"
reqwest = { version = "^0.12.2", features = ["json"] }
Expand Down
360 changes: 360 additions & 0 deletions man/man5/himmelblau.conf.5
Original file line number Diff line number Diff line change
@@ -0,0 +1,360 @@
.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 configured domains. 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.

.EXAMPLES
domains = example.com,example2.com

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

.EXAMPLES
pam_allow_groups = f3c9a7e4-7d5a-47e8-832f-3d2d92abcd12,d98c8e1d-7f8a-4597-babc-9d3b781ef456

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

.EXAMPLES
id_attr_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_to_upn_mapping
.RE
Allows users to enter the short form of their username (e.g., 'dave') instead of the full UPN.

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

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

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

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

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

.SH SEE ALSO
.BR himmelblaud(8),
.BR himmelblaud-tasks(8)
5 changes: 2 additions & 3 deletions man/man8/himmelblaud.8
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,6 @@ Print the version of the `himmelblaud` daemon and exit.
.TP
.B Enable debug mode:
# himmelblaud --debug
.SH "SEE ALSO"
Documentation for the `himmelblaud` daemon is available in the Texinfo manual. Use the following command to access the full manual:

.BR info himmelblaud
.SH SEE ALSO
.BR himmelblaud-tasks(8)
Loading

0 comments on commit f24e0e6

Please sign in to comment.