When a user logs in with their Entra ID credentials, Himmelblau presents an MFA challenge after the password step (or instead of the password step, if passwordless is enabled). The challenge is driven by the user’s MFA configuration in Entra ID — Himmelblau does not manage MFA enrollment itself.
Once a user has enrolled in Windows Hello, subsequent logins skip the MFA challenge entirely and use the local Hello credential instead.
Supported MFA methods
Himmelblau supports the following MFA methods:
| Method | mfa_method value | Description |
|---|
| Microsoft Authenticator push | PhoneAppNotification | Sends a push notification to the Authenticator app. The user approves on their phone. |
| Authenticator Lite (Outlook) | CompanionAppsNotification | Push notification via Outlook or Authenticator Lite. |
| Authenticator OTP | PhoneAppOTP | Generates a time-based code in the Authenticator app. |
| SMS | OneWaySMS | Sends a code via text message. |
| Phone call (mobile) | TwoWayVoiceMobile | Calls the user’s registered mobile number. |
| Phone call (alternate mobile) | TwoWayVoiceAlternateMobile | Calls the user’s alternate mobile number. |
| Phone call (office) | TwoWayVoiceOffice | Calls the user’s registered office number. |
| Call or SMS | ConsolidatedTelephony | Either a call or a text message, depending on what is available. |
| Device code (QR) | (automatic) | Displays a URL or QR code on screen. The user scans it on another device. Used as a fallback when other methods are unavailable. |
Device authorization (QR code) flow
When no other MFA method is configured or available, Himmelblau falls back to the Device Authorization Grant (DAG) flow. A verification URL and code are shown in the terminal or on the login screen. The user opens the URL on another device and approves the request.
If the authentication endpoint returns a verification_uri_complete (a URL with the code pre-filled), Himmelblau displays it directly. Otherwise it falls back to the plain verification_uri and shows the code separately.
When using GDM (GNOME Display Manager), the GNOME greeter extension can display the device code as a scannable QR code on the login screen. This removes the need for the user to type a URL manually. See the platform guides for your distribution to enable the greeter extension.
Pinning an MFA method
By default, Himmelblau uses whatever MFA method is configured as the default in the user’s Entra ID profile. To override this and always use a specific method, set mfa_method in /etc/himmelblau/himmelblau.conf:
[global]
mfa_method = PhoneAppNotification
mfa_method unset to rely on the Entra ID default.
Single-factor fallback
By default, MFA is always required for Entra ID users. If you need to allow password-only (single-factor) authentication when MFA is unavailable, set:
[global]
enable_sfa_fallback = true
| Option | Default | Description |
|---|
enable_sfa_fallback | false | When true, permits password-only authentication if MFA is unavailable. Use with caution. |
Experimental MFA flow
Himmelblau has two MFA code paths:
- Experimental MFA (default: enabled): Supports the full interactive MFA flow, including Hello enrollment. May encounter failures in edge cases.
- Device Authorization Grant only: Disabling experimental MFA forces the DAG (QR code) flow for all logins. This is more robust but does not allow Hello authentication.
[global]
# Set to false to force the DAG flow and disable Hello enrollment
enable_experimental_mfa = true
| Option | Default | Description |
|---|
enable_experimental_mfa | true | Enables the experimental MFA flow that supports Hello. Set to false to fall back to the DAG flow. |
MFA over SSH
MFA works for SSH sessions when pam_himmelblau is included in the SSH PAM stack. Himmelblau presents the MFA challenge as a PAM conversation, so any MFA method that can be satisfied without a browser (push notification, OTP, phone call) works over SSH.
The device code (QR) flow also works over SSH — the verification URL and code are printed to the terminal. The user must approve the login from another device.
If you prefer PIN-based authentication for SSH without requiring MFA at each login, see Windows Hello — Remote Hello. 