Skip to main content
Windows Hello on Linux works the same way it does on Windows: after completing an initial interactive login that satisfies MFA, Himmelblau registers a local credential (a PIN or FIDO2 key) tied to the device. On subsequent logins, that credential is accepted in place of the password and MFA challenge, keeping daily authentication fast without reducing security — the Hello credential is device-bound and never leaves the machine.
Hello enrollment requires the device to be joined to Entra ID. Hello is only available after a successful first interactive online login. If enable_hello is true but the device has never authenticated online, users will be prompted for their password and MFA as usual until enrollment completes.

​
How Hello enrollment works

  1. The user logs in interactively with their Entra ID password and completes MFA.
  2. Himmelblau prompts the user to set a Hello PIN (or registers a FIDO2 key if FIDO passwordless is enabled).
  3. The PIN is stored locally, protected by the TPM or software HSM. The Entra ID credential material is wrapped to the device.
  4. On the next login, Himmelblau accepts the PIN instead of the password and MFA challenge.
After this, logins on the same device use the Hello PIN. The PIN never leaves the host, and it is not the user’s Entra ID password.

​
Configuration

Add the following options to the [global] section of /etc/himmelblau/himmelblau.conf: 
[global]
# Enable Hello enrollment and PIN login (default: true)
enable_hello = true

# Minimum PIN length — must be between 6 and 32 (default: 6)
hello_pin_min_length = 6

# Failed PIN attempts before MFA is required to reset the PIN (default: 3)
hello_pin_retry_count = 3

# Customize the PIN prompt shown at login
hello_pin_prompt = Use the Linux Hello PIN for this device.
OptionDefaultDescription
enable_hellotrueEnables or disables Hello enrollment. When disabled, users must provide MFA at every login.
hello_pin_min_length6Minimum PIN length. Accepted range: 6–32.
hello_pin_retry_count3Number of wrong PIN attempts allowed before the user is required to complete MFA and set a new PIN.
hello_pin_promptUse the Linux Hello PIN for this device.The prompt text shown when the PIN is requested.

​
Hello TOTP

By default, Hello PIN alone is not accepted for remote authentication (for example, SSH). To extend Hello to remote services, you can enable Hello TOTP, which requires users to provide both the Hello PIN and a time-based one-time password. The TOTP secret is enrolled and stored locally on the host — it is independent of any cloud-based MFA configured in Entra ID. Users who have not yet enrolled a TOTP secret are prompted to do so the first time they log in after this option is enabled. 
[global]
enable_hello_totp = true
OptionDefaultDescription
enable_hello_totpfalseWhen enabled, remote logins accept Hello PIN + local TOTP as a second factor.

​
Remote Hello (SSH without TOTP)

If you want to allow Hello PIN alone for SSH and other remote services — without requiring TOTP — you can enable allow_remote_hello. This restores the previous behavior where PIN alone is accepted remotely.
Allowing remote Hello without TOTP weakens remote authentication. An attacker who obtains the PIN can log in from any machine in scope of the PAM stack. Prefer enable_hello_totp = true instead.
[global]
allow_remote_hello = true
OptionDefaultDescription
allow_remote_hellofalsePermits Hello PIN alone for remote services such as SSH. Not recommended; prefer enable_hello_totp.

​
FIDO2 passwordless

Himmelblau includes experimental support for authenticating against Entra ID using a FIDO2 security key, bypassing the password entirely. 
[global]
enable_experimental_passwordless_fido = true

# How long to wait for the user to insert their key (seconds, default: 25)
fido_timeout = 25

# Message shown when the key must be inserted
fido_prompt = Please insert your security key.

# Message shown when the user must touch the key
fido_presence_prompt = Please touch your security key.
OptionDefaultDescription
enable_experimental_passwordless_fidofalseEnables the experimental FIDO2 passwordless flow. When set, Himmelblau attempts to authenticate with Entra ID using a FIDO2 key without a password.
fido_timeout25Seconds to wait for the user to insert and activate their security key.
fido_promptPlease insert your security key.Message shown at the start of FIDO authentication.
fido_presence_promptPlease touch your security key.Message shown when user presence (touch) is required.
FIDO2 passwordless in Himmelblau is experimental. If a user signs in using a passwordless method, no password hash is ever cached, which means offline breakglass cannot function for that user.

​
FAQ

Enter the wrong PIN the number of times specified by hello_pin_retry_count (default: 3). After the limit is reached, Himmelblau requires the user to complete online MFA. On success, the user is prompted to set a new PIN.Administrators can also clear all cached credentials (including Hello state) by running:
sudo aad-tool cache-clear
This marks all cached entries as stale and forces users through a fresh enrollment on the next login.
By default, no — Hello PIN alone is only accepted for local (console or display manager) logins. To extend Hello to SSH, enable enable_hello_totp = true (recommended) or allow_remote_hello = true (less secure).
The Hello PIN is not stored in plaintext. The underlying cryptographic material is wrapped using the device’s TPM (if available) or the software HSM. The credential cannot be used on a different machine.
Yes, but Hello enrollment for OIDC providers (when oidc_issuer_url is set) requires the client application to allow refresh tokens and include the offline_access scope.

Build docs developers (and LLMs) love

Get started for freeTalk to us