Himmelblau is an open-source project designed to integrate Azure Entra ID (formerly Azure Active Directory) authentication seamlessly with Linux environments. By enabling features like single sign-on (SSO), multi-factor authentication (MFA), and secure token handling, Himmelblau allows organizations to bridge the gap between Microsoft’s enterprise identity solutions and Linux systems. It serves as a middleware layer, providing tools for authentication, device registration, and identity management across various Linux distributions.
The name 'Himmelblau' is derived from German, meaning 'Sky blue', or 'Azure blue,' a nod to Microsoft Azure, which the project is designed to integrate with. This name reflects the project's purpose of bridging Linux systems with Azure Entra ID authentication. Himmelblau originated as an open-source initiative aimed at addressing the gap in identity integration between Linux environments and Microsoft's enterprise cloud solutions.
Himmelblau leverages protocols such as OAuth2 and Kerberos to deliver secure and efficient authentication mechanisms. The project’s modular and lightweight design ensures it can scale across small deployments or large enterprise environments, making it suitable for diverse use cases.
Modern enterprises often operate in hybrid environments that combine Windows and Linux systems. Azure Entra ID is a cornerstone of Microsoft’s cloud-based identity and access management strategy, providing centralized control over authentication, access policies, and user management. However, native Linux support for Azure Entra ID has historically been limited, creating challenges for organizations aiming to unify their IT infrastructure.
Himmelblau stands out as an open-source alternative to proprietary identity integration solutions. By providing transparency and flexibility, it empowers organizations to:
Himmelblau is a transformative tool that bridges the gap between Azure Entra ID and Linux environments. By supporting secure, scalable, and seamless authentication workflows, it addresses the challenges of integrating diverse systems into a unified identity framework. This chapter introduced Himmelblau’s purpose, its advantages, and its importance in the open-source community. The next chapter will delve into the broader challenges of integrating Azure Entra ID with Linux systems and how Himmelblau mitigates these issues.
Himmelblau uses OAuth2 as the primary protocol for authentication, leveraging Microsoft’s MS-OAPX and OAPXBC extensions. These extensions ensure secure and seamless integration with Azure Entra ID, providing robust support for modern authentication workflows.
For organizations migrating Linux systems from on-premises Active Directory (AD) to Azure Entra ID, the transition can be challenging, particularly with UID and GID mismatches. These discrepancies often arise due to differences in ID mapping between traditional tools like Winbind or SSSD and Himmelblau's default mapping strategies.
To mitigate UID/GID mismatch issues, organizations can continue using the SSSD NSS module for UID/GID mapping while utilizing Himmelblau solely for authentication. This hybrid approach allows:
Configuration Example:
Configure SSSD:
[sssd] domains = example.org [domain/example.org] id_provider = ad ldap_id_mapping = false
Configure NSS:
passwd: files systemd sss group: files systemd sss shadow: files sss
Use Himmelblau for Authentication:
Ensure Himmelblau is configured in the PAM stack for auth , account, and session while disabling its NSS module.
To address these challenges more seamlessly, Himmelblau plans to:
Integrating Linux systems with Azure Entra ID introduces unique challenges, particularly when transitioning from on-prem AD environments. By using OAuth2 with MS-OAPX/OAPXBC extensions for authentication and adopting workarounds like SSSD for ID mapping, organizations can achieve a smoother transition. Himmelblau’s future enhancements promise to further simplify these processes, ensuring consistent and secure identity management across hybrid infrastructures.
Himmelblau provides a comprehensive suite of tools designed to integrate Azure Entra ID authentication into Linux environments. By leveraging open standards and implementing advanced features, it bridges the gap between Linux systems and Microsoft’s enterprise identity solutions. Below are the key features and benefits that define the Himmelblau ecosystem.
Himmelblau seamlessly integrates with Azure Entra ID, enabling Linux systems to utilize Azure’s robust identity and access management framework. This includes:
By incorporating the Siemens linux-entra-sso framework, Himmelblau ensures a consistent and secure SSO experience for browser-based applications. This functionality simplifies user workflows and boosts productivity by reducing the need for repeated logins.
Himmelblau extends Azure Entra ID’s Kerberos capabilities to Linux environments. It retrieves and caches cloud-based Ticket Granting Tickets (TGTs) from Azure’s KDC, supporting both cloud and hybrid setups. This functionality ensures compatibility with existing Kerberos-based applications and workflows.
The Himmelblau ecosystem is designed with modularity in mind, allowing administrators to enable or disable features based on organizational needs. This flexibility ensures that Himmelblau can scale from small deployments to large enterprise environments.
Himmelblau incorporates features like encrypted token storage, PAM integration, and support for secure device authentication. These measures help organizations meet compliance requirements and protect sensitive data.
As an open-source project, Himmelblau empowers organizations to:
Himmelblau is compatible with a wide range of Linux distributions, including enterprise-grade and community-supported versions. Current supported distributions include:
This extensive compatibility ensures that organizations can adopt Himmelblau regardless of their Linux environment.
Himmelblau’s design prioritizes seamless interaction with Microsoft’s ecosystem, enabling Linux clients to access:
This interoperability allows organizations to maintain consistent identity management across their entire infrastructure, regardless of the underlying operating system.
The Himmelblau ecosystem represents a powerful solution for integrating Azure Entra ID with Linux environments. Its robust feature set, extensive distribution support, and open-source foundation make it a versatile tool for organizations of all sizes. The next chapter will explore the technical architecture and components that make Himmelblau such an effective bridge between these two ecosystems.
Himmelblau’s architecture is designed to seamlessly integrate Linux systems with Azure Entra ID, leveraging a modular and scalable framework. This chapter explores its core components and their roles in achieving secure and efficient authentication.
himmelblaud)The himmelblaud daemon is the central component responsible for handling authentication requests and interacting directly with Azure Entra ID. Key functionalities include:
User Authentication: Processes login attempts and validates credentials against Azure Entra ID.
OAuth2 Flows: Initiates authentication and token exchanges with Azure Entra ID, passing tokens to the Himmelblau Broker via a secure socket.
Token Management: Manages the secure storage, caching, and renewal of authentication tokens.
Integration with PAM and NSS: Supports Pluggable Authentication Modules (PAM) for system-level authentication and integrates with NSS to provide consistent user and group information across the system.
The Himmelblau Broker serves as a middleware layer, facilitating communication between Linux applications and Azure Entra ID. Key functions include:
DBus Integration for SSO: Exposes a DBus interface for seamless interaction with browser and application plugins.
Socket-Based Communication: Receives OAuth2 tokens and other data from the himmelblaud daemon via a secure socket for further processing.
Himmelblau’s configuration is managed through the /etc/himmelblau/himmelblau.conf file. Key elements include:
Example configuration:
[global] domains = example.com pam_allow_groups = f3c9a7e4-7d5a-47e8-832f-3d2d92abcd1
Himmelblau extends Kerberos functionality to Azure Entra ID by acting as a Kerberos client. It retrieves and caches Ticket Granting Tickets (TGTs) from Azure Entra ID’s cloud-based KDC, enabling:
Example Kerberos configuration:
[realms]
KERBEROS.MICROSOFTONLINE.COM = {
kdc = https://login.microsoftonline.com/common/kerberos
}
[libdefaults]
default_ccache_name = DIR:/tmp/krb5cc_%{uid}
himmelblaud-tasks)The himmelblaud-tasks service handles essential background operations, including:
Himmelblau’s modular architecture ensures it can adapt to various organizational needs. Administrators can enable or disable components depending on the deployment scenario, ensuring optimal resource usage.
Himmelblau’s architecture is built to bridge the gap between Azure Entra ID and Linux systems. By combining modular components, robust token management, and seamless Kerberos integration, Himmelblau provides a scalable and secure authentication framework. The next chapter will explore how these components interact in real-world deployment scenarios.
Himmelblau provides seamless authentication workflows that bridge the gap between Linux systems and Azure Entra ID. By leveraging protocols like OAuth2 and Kerberos, it ensures secure and efficient user authentication, supports single sign-on (SSO), and integrates with multi-factor authentication (MFA) mechanisms. This chapter outlines the main authentication workflows in Himmelblau, highlighting the steps involved and the components responsible for each.
Himmelblau’s OAuth2-based authentication enables Linux systems to interact securely with Azure Entra ID. The workflow involves the following steps:
himmelblaud daemon sends an OAuth2 token request to Azure Entra ID, including the user’s credentials or device code if applicable.himmelblaud-tasks.Himmelblau integrates Azure Entra ID’s Kerberos capabilities to support existing Kerberos-dependent applications. The following steps outline the process:
himmelblaud-tasks retrieves a Ticket Granting Ticket (TGT) as part of the Primary Refresh Token (PRT) request from Azure Entra ID. The TGT is essential for Kerberos workflows and is obtained directly from the cloud-based KDC./tmp/krb5cc_%{uid}).Himmelblau supports Azure Entra ID’s MFA capabilities, providing an additional layer of security. Common MFA methods include:
These methods are seamlessly integrated into the OAuth2 and Kerberos workflows, ensuring robust security without complicating the user experience.
SSO is a critical feature for enterprise environments, allowing users to authenticate once and access multiple services. Himmelblau’s SSO implementation involves:
Himmelblau supports hybrid setups where both cloud and on-premises resources are accessible. In such environments:
himmelblaud, reducing administrative overhead.Himmelblau’s authentication workflows provide a robust framework for integrating Azure Entra ID with Linux systems. By supporting OAuth2, Kerberos, MFA, and SSO, it ensures secure and seamless user experiences. The next chapter will delve into deployment best practices, covering setup strategies for different organizational needs.
Device registration is a cornerstone of Azure Entra ID’s security framework, enabling organizations to enforce compliance policies, manage access, and enhance security for connected devices. Himmelblau leverages the Device Registration Service (DRS) protocol, as outlined in the MS-DRS specification, to seamlessly register Linux devices with Azure Entra ID. This chapter provides a detailed explanation of the device registration process.
Device registration establishes a device identity in Azure Entra ID, enabling administrators to:
For Linux environments, Himmelblau facilitates device registration, bridging a gap previously filled by proprietary tools on other platforms.
Himmelblau’s device registration process adheres to the MS-DRS protocol. Below is a detailed step-by-step breakdown:
Initiating the Registration Process:
himmelblaud.Retrieving Enrollment Information:
Generating the Device Certificate Request:
Submitting the Registration Request:
Receiving the Device Certificate:
Storing the Device Certificate:
Completing the Registration:
Himmelblau’s implementation of the MS-DRS protocol ensures seamless device registration with Azure Entra ID, establishing a secure and compliant foundation for managing Linux devices. By automating key steps and leveraging robust cryptographic mechanisms, Himmelblau simplifies a traditionally complex process. In the next chapter, we will explore best practices for optimizing Himmelblau deployments in enterprise environments.
Installing Himmelblau is the first step toward integrating Azure Entra ID with Linux systems. This chapter provides a detailed guide for setting up Himmelblau on various supported Linux distributions. By the end of this chapter, you will have a functioning Himmelblau installation configured for your environment.
Himmelblau supports a wide range of Linux distributions, including:
This diversity ensures that organizations can adopt Himmelblau regardless of their preferred Linux environment.
Before installing Himmelblau, ensure that the following prerequisites are met:
System Updates:
sudo apt update && sudo apt upgrade # For Debian-based systems sudo dnf update # For Red Hat-based systems sudo zypper update # For SUSE-based systems
Azure Entra ID Preparation:
Follow these steps to install Himmelblau:
Download the Packages:
Install the Packages:
dpkg to install Himmelblau and its components.sudo dpkg -i himmelblau_0.8.2-debian12_amd64.deb \
himmelblau-sshd-config_0.8.2-debian12_amd64.deb \
himmelblau-sso_0.8.2-debian12_amd64.deb \
nss-himmelblau_0.8.2-debian12_amd64.deb \
pam-himmelblau_0.8.2-debian12_amd64.deb
Resolve Dependencies:
sudo apt --fix-broken install
Download the RPM Packages:
Install the Packages:
dnf to install Himmelblau.sudo dnf install ./himmelblau-0.8.2-1.x86_64-rocky8.rpm \
./himmelblau-sshd-config-0.8.2-1.x86_64-rocky8.rpm \
./himmelblau-sso-0.8.2-1.x86_64-rocky8.rpm \
./nss-himmelblau-0.8.2-1.x86_64-rocky8.rpm \
./pam-himmelblau-0.8.2-1.x86_64-rocky8.rpm
Download the RPM Packages:
Install the Packages:
zypper to install Himmelblau.sudo zypper install ./himmelblau-0.8.2-1.x86_64-sle15sp6.rpm \
./himmelblau-sshd-config-0.8.2-1.x86_64-sle15sp6.rpm \
./himmelblau-sso-0.8.2-1.x86_64-sle15sp6.rpm \
./nss-himmelblau-0.8.2-1.x86_64-sle15sp6.rpm \
./pam-himmelblau-0.8.2-1.x86_64-sle15sp6.rpm
Configuration:
Disable Name Service Caching (Optional):
Disable nscd to ensure up-to-date user and group information.
sudo systemctl disable nscd sudo systemctl stop nscd
This chapter covered the steps required to install Himmelblau on various Linux distributions, ensuring compatibility and optimal setup. The next chapter will focus on configuring Himmelblau to meet organizational requirements.
After installing Himmelblau, the next step is configuring it to integrate seamlessly with your Azure Entra ID environment. This chapter provides a detailed guide to configuring Himmelblau, including editing its configuration file, setting up domain and user options, and preparing it for production use. Once configuration is complete, the required daemons can be started to activate Himmelblau.
The main configuration file for Himmelblau is located at:
/etc/himmelblau/himmelblau.conf
This file controls essential settings, including domains, user authentication policies, and logging.
Below is an example configuration file:
[global] domains = contoso.onmicrosoft.com pam_allow_groups = f3c9a7e4-7d5a-47e8-832f-3d2d92abcd12 id_attr_map = name home_attr = CN home_alias = CN use_etc_skel = true
Domains:
Example:
domains = contoso.onmicrosoft.com
Group Filtering:
pam_allow_groups to restrict authentication to specific Azure Entra ID groups.Example:
pam_allow_groups = f3c9a7e4-7d5a-47e8-832f-3d2d92abcd12
Home Directory Options:
Example:
home_attr = CN home_alias = CN use_etc_skel = true
Logging:
Example:
debug = true
Himmelblau integrates with NSS and PAM for user and group management. Ensure the following configurations are applied:
Edit /etc/nsswitch.conf to include Himmelblau:
passwd: files systemd himmelblau shadow: files himmelblau group: files systemd himmelblau
Himmelblau’s PAM module can be configured automatically using distribution-specific tools, through the aad-tool utility (v1.0.0+), or manually for advanced customization. This configuration enables systems to authenticate users using their Azure Entra ID credentials through PAM.
Automatic Configuration:
On Ubuntu/Debian, use the pam-auth-update utility:
sudo pam-auth-update
Ensure the Azure authentication checkbox is enabled. After saving, verify that PAM files were updated correctly.
On openSUSE Tumbleweed or SUSE Linux Enterprise, use:
pam-config --add --himmelblau
Configuration Using aad-tool (Himmelblau 1.0.0 and above):
The aad-tool configure-pam command helps inject recommended PAM directives into the appropriate configuration files.
By default, it performs a dry run — showing the changes it would make without modifying any files:
sudo aad-tool configure-pam
To apply the changes, use the --really flag:
sudo aad-tool configure-pam --really
To view verbose output, add --debug:
sudo aad-tool configure-pam --really --debug
You can optionally specify custom target files instead of using the default files in /etc/pam.d:
--auth-file <PATH> – Target file for the auth stack (e.g., common-auth)--account-file <PATH> – Target file for the account stack--session-file <PATH> – Target file for the session stack--password-file <PATH> – Target file for the password stackThis is especially useful for testing or containerized environments where you don’t want to touch live PAM files:
sudo aad-tool configure-pam \
--auth-file ./test_pam/common-auth \
--account-file ./test_pam/common-account \
--session-file ./test_pam/common-session \
--password-file ./test_pam/common-password
Manual Configuration:
For full control, you may manually configure the PAM stack. Ensure that pam_himmelblau.so is placed before pam_unix.so in common-auth, and always after modules like pam_localuser.so. This is important for Hello for Business and passwordless logins. Use the ignore_unknown_user option to prevent errors for local-only accounts.
/etc/pam.d/common-auth:
auth required pam_env.so
auth [default=1 ignore=ignore success=ok] pam_localuser.so
auth sufficient pam_himmelblau.so ignore_unknown_user
auth sufficient pam_unix.so nullok try_first_pass
auth required pam_deny.so
/etc/pam.d/common-account:
account [default=1 ignore=ignore success=ok] pam_localuser.so
account sufficient pam_himmelblau.so ignore_unknown_user
account sufficient pam_unix.so
account required pam_deny.so
/etc/pam.d/common-session:
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
/etc/pam.d/common-password:
password sufficient pam_himmelblau.so ignore_unknown_user
password optional pam_gnome_keyring.so use_authtok
password sufficient pam_unix.so use_authtok nullok shadow try_first_pass
password required pam_deny.so
Once the configuration is complete, enable and start the Himmelblau daemons to activate the service:
sudo systemctl enable himmelblaud himmelblaud-tasks sudo systemctl start himmelblaud himmelblaud-tasks
Service Status:
systemctl status himmelblaud systemctl status himmelblaud-tasks
NSS User Resolution:
getent passwd user@domain.onmicrosoft.com
Test Authentication:
su -l user@domain.onmicrosoft.com
Check Logs:
Inspect the logs for any errors:
sudo journalctl -u himmelblaud -u himmelblaud-tasks
Verify that the Himmelblau daemons are running:
systemctl status himmelblaud systemctl status himmelblaud-tasks
This chapter covered configuring Himmelblau to integrate with Azure Entra ID, setting up NSS and PAM, and starting the necessary services. By following these steps, you’ll ensure a secure and functional deployment. The next chapter will address advanced configurations and optimization techniques.
While Himmelblau is designed for seamless integration, issues may arise during deployment or operation. This chapter covers common problems and their resolutions, focusing on MFA-related SSH authentication issues and techniques for debugging authentication traffic.
SSH authentication involving Azure Entra ID MFA can present challenges, especially when using interactive prompts. Below are some common issues and solutions:
Symptoms: Users attempting to authenticate via SSH do not see the MFA prompt or entropy code. Authentication eventually times out or fails.
Solution:
Enable Keyboard-Interactive Authentication:
AuthenticationMethods in the SSH daemon configuration includes keyboard-interactive:pam./etc/ssh/sshd_config:
AuthenticationMethods keyboard-interactive:pam KbdInteractiveAuthentication yes UsePAM yes
sudo systemctl restart sshd
Verify PAM Configuration:
pam_himmelblau.so is configured in the PAM stack for auth and account./etc/pam.d/sshd:
auth required pam_himmelblau.so account required pam_himmelblau.so
Test Locally:
su -l user@domain.onmicrosoft.com
Check Logs:
sudo journalctl -u sshd -u himmelblaud
Symptoms: Users successfully enter their password, but the session hangs instead of displaying the MFA prompt.
Solution:
mfa_poll_prompt option to resolve this issue:
/etc/pam.d/sshd) to include:
auth required pam_himmelblau.so mfa_poll_prompt account required pam_himmelblau.so
sudo systemctl restart sshd
Effective debugging is essential for resolving complex authentication issues. Himmelblau supports various methods for capturing and analyzing authentication traffic.
cirrus-scope with mitmproxyThe cirrus-scope tool, in conjunction with mitmproxy, allows for comprehensive testing and debugging of Azure Entra ID authentication flows.
Steps:
Download and Install cirrus-scope:
Download and Extract mitmproxy:
mitmproxy from their official website and extract the binaries:
tar -xf mitmproxy-11.0.0-linux-x86_64.tar.gz
Start mitmweb:
mitmweb:
./mitmweb
This starts mitmweb and opens a web interface for monitoring HTTP and HTTPS traffic.
Install the mitmproxy CA Certificate:
sudo cp $HOME/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy.crt
sudo update-ca-certificates
sudo cp $HOME/.mitmproxy/mitmproxy-ca-cert.pem /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust
sudo cp $HOME/.mitmproxy/mitmproxy-ca-cert.pem /usr/share/pki/trust/anchors/mitmproxy.crt
sudo update-ca-certificates
Access the Web Interface:
http://127.0.0.1:8081/
You should see the mitmweb dashboard for viewing captured traffic.
Run cirrus-scope with Proxy Enabled:
cirrus-scope, routing its traffic through mitmproxy by setting the HTTPS_PROXY environment variable. For example:
HTTPS_PROXY=http://127.0.0.1:8080 cirrus-scope auth-test --name your_user@example.com
You will be prompted to enter credentials interactively. For detailed logs, add the --debug flag:
HTTPS_PROXY=http://127.0.0.1:8080 cirrus-scope auth-test --name your_user@example.com --debug
Other available test commands include:
enrollment-test: Simulates device enrollmentrefresh-token-acquire: Acquires new access tokens using a refresh tokenprovision-hello-key-test: Tests Hello for Business key provisioningCapture and Save the HAR File:
mitmweb dashboard, click on the "File" drop-down menu, then select "Save". Your browser will download a file called 'flows'.This section provided guidance on debugging authentication traffic using tools like cirrus-scope and mitmproxy. These troubleshooting techniques ensure that Himmelblau operates smoothly and securely in your environment. The next section will explore future directions and enhancements for Himmelblau.