Skip to content

Home

Jump to bottom
David Mulder edited this page Oct 15, 2024 · 11 revisions

Welcome to the Himmelblau wiki!

Supported Linux Distributions

The following distributions are currently supported:

Distribution Version
openSUSE openSUSE Tumbleweed

The following distributions have experimental packages available, but are not currently supported:

Distribution Version
openSUSE openSUSE Leap 15.4+
SUSE Linux Enterprise 15 SP4+

Installing Himmelblau

Himmelblau provides the necessary tools and utilities to enable authentication with Azure Entra ID.

On openSUSE Tumbleweed, refresh the repos and install himmelblau:

sudo zypper ref && sudo zypper in himmelblau nss-himmelblau pam-himmelblau

On openSUSE Leap and SUSE Linux Enterprise, add the experimental repo and install himmelblau:

# For Leap 15.6 or SUSE Linux Enterprise 15 SP6:
sudo zypper ar https://download.opensuse.org/repositories/network:/idm/15.6/network:idm.repo
# For Leap 15.5 or SUSE Linux Enterprise 15 SP5:
sudo zypper ar https://download.opensuse.org/repositories/network:/idm/15.5/network:idm.repo
# For Leap 15.4 or SUSE Linux Enterprise 15 SP4:
sudo zypper ar https://download.opensuse.org/repositories/network:/idm/15.4/network:idm.repo

Then refresh the repos and install himmelblau:

sudo zypper ref && sudo zypper in himmelblau nss-himmelblau pam-himmelblau

Configuring Himmelblau

To enable authentication, it is imperative to configure the domains and pam_allow_groups options in the /etc/himmelblau/himmelblau.conf file. These settings determine which domains and users or groups are granted access to the host.

[global]
domains = contoso.onmicrosoft.com
pam_allow_groups = [email protected],[email protected]

Note: pam_allow_groups is no longer a required parameter as of Himmelblau 0.6.0. Leaving pam_allow_groups unset now permits all users to authenticate.

Note: On Ubuntu, you should additionally set use_etc_skel to true and configure home_attr and home_alias to match (I recommend using the CN attribute). These parameters are necessary, otherwise Ubuntu's snaps will fail to execute.

[global]
home_attr = CN
home_alias = CN
use_etc_skel = true

Run the daemon

Enable and start the himmelblaud and himmelblaud-tasks daemons. The himmelblaud daemon communicates with Entra ID and facilitates device, Hello PIN enrollment, and authentication. The himmelblaud-tasks daemon is responsible for authenticated tasks, such as creating the users home directory.

systemctl enable himmelblaud himmelblaud-tasks
systemctl start himmelblaud himmelblaud-tasks

Disable nscd

It is recommended that the Name Service Cache daemon (nscd) be disabled.

The nscd daemon caches name service lookups, including user and group information obtained from sources like /etc/passwd and /etc/group. When integrating with Azure Entra ID, it's important to ensure that the most up-to-date user and group information is consistently retrieved from the directory. Disabling nscd helps avoid potential inconsistencies that may arise from cached data not reflecting changes made in Azure Entra ID.

systemctl stop nscd
systemctl disable nscd
systemctl mask nscd

Setup NSS

Configuring NSS (Name Service Switch) is essential in integrating Linux hosts with Azure Entra ID using Himmelblau. By configuring NSS to include himmelblau alongside sources such as compat, systemd, etc., the system knows to query Azure Entra ID for user and group information.

The NSS configuration file is found at /etc/nsswitch.conf. The himmelblau NSS module name should be appended to the passwd, group and shadow entries.

passwd:     compat systemd himmelblau
group:      compat systemd himmelblau
shadow:     compat systemd himmelblau

Setup PAM

PAM enables flexible authentication mechanisms by allowing administrators to define authentication policies through modular components. Configuring PAM for Azure Entra ID that users can authenticate using their Azure Entra ID credentials. By configuring PAM to include the Himmelblau module, authentication requests are directed to Azure Entra ID.

To configure Himmelblau for PAM on openSUSE Tumbleweed, simply use pam-config:

pam-config --add --himmelblau

Check the pam files afterward to ensure the configuration was successful.

Otherwise configure pam manually:

In /etc/pam.d/common-auth, ensure that the pam_himmelblau.so module is placed after other authentication methods (such as pam_unix.so). Ensure that other authentication modules are not set to required, as this could cause authentication to fail prior to PAM communicating with Entra ID. Include the ignore_unknown_user option for Himmelblau. Ensure pam_deny.so is placed after all modules, so that unknown users are not implicitly allowed.

auth        required      pam_env.so
auth        [default=1 ignore=ignore success=ok] pam_localuser.so
auth        sufficient    pam_unix.so nullok try_first_pass
auth        sufficient    pam_himmelblau.so ignore_unknown_user
auth        required      pam_deny.so

Configure /etc/pam.d/common-account in a similar manner.

account    [default=1 ignore=ignore success=ok] pam_localuser.so
account    sufficient    pam_unix.so
account    sufficient    pam_himmelblau.so ignore_unknown_user
account    required      pam_deny.so

In /etc/pam.d/common-session, set pam_himmelblau.so as an optional module.

session optional    pam_systemd.so
session required    pam_limits.so
session optional    pam_unix.so try_first_pass
session optional    pam_umask.so
session optional    pam_himmelblau.so
session optional    pam_env.so

Enrolling the Device and Hello PIN

A Windows Hello PIN offers a secure and convenient authentication method by leveraging strong encryption, local authentication capabilities, and integration with Entra ID. By setting a PIN on a soft TPM object and unlocking it securely, users can authenticate to their devices and Azure services with confidence in the security of their credentials.

If you're coming from using Active Directory, you're familiar with a device join. In Azure Entra ID, enrollment (device join) is performed by individual users who can enroll a maximum of 50 devices each (by default). Instead of being performed as an administrative action, enrollment happens at authentication time, and the first user to authenticate to a device becomes the owner of the device in Entra ID. Subsequent users who are authorized may authenticate to the device, but will not own the device. In a workplace setting, administrators would be responsible for configuring the himmelblau.conf file, as well as pam and nss, but enrollment would be performed by the user when they receive the device.

opensuse-himmelblau login: [email protected]
Password: 
Please type in the code displayed on your authenticator app from your device:
Code: 
Set up a PIN
 A Hello PIN is a fast, secure way to signin to your device, apps, and services.
New PIN: 
Confirm PIN: 
Have a lot of fun...
[email protected]@opensuse-himmelblau:~>

To enroll your device in Entra ID:

  1. Login:
  • At the login prompt, enter your username in the format [email protected].
  • Enter your password when prompted.
  1. MFA:
  • You'll be prompted to provide multi-factor authentication, using your prefered method.
  • Your device is now enrolled in Entra ID.
  1. Set up a PIN:
  • You'll be prompted to set up a PIN for Windows Hello. This PIN serves as a fast and secure way to sign in to your device, apps, and services.
  • Your PIN must be between 6 and 32 characters in length.
  • Enter a new PIN of your choice when prompted.
  • Confirm the new PIN by entering it again.
  1. Completion:
  • You are now enrolled in Windows Hello PIN authentication.

Ensure that you choose a strong and memorable PIN to maintain the security of your device. Additionally, keep your PIN confidential and do not share it with others to prevent unauthorized access to your device and associated services. Your PIN is unique to this host, and will not effect authentication to other hosts and Azure services.

You can now use your newly set up PIN to authenticate and access your device.

Libhimmelblau Design Document

Clone this wiki locally