Quickstart

Himmelblau brings Microsoft Entra ID and OIDC (Google Workspace, Okta, Keycloak, etc) login, policy enforcement, and Hello PIN support to Linux.

Install Himmelblau

Run the bootstrap installer:

curl -fsSL https://himmelblau-idm.org/install | sh

For most systems, that is all you need. The installer uses your native package manager, prompts for Microsoft Entra ID or generic OIDC settings, configures PAM and NSS, and starts the Himmelblau services.

What the installer does

The bootstrap installer detects your distribution, offers the supported package sources, adds the trusted Himmelblau repository when needed, and installs packages with `apt`, `dnf`, or `zypper`.
It asks whether to configure Microsoft Entra ID or a generic OIDC provider such as Google Workspace, Okta, or Keycloak.
For Entra ID, it writes a `domain` setting. For generic OIDC, it writes `oidc_issuer_url` and `app_id`. If `/etc/himmelblau/himmelblau.conf` already contains a complete identity provider configuration, the installer treats the run as an upgrade or repair install and leaves the file unchanged.
After package installation and configuration, it enables and starts `himmelblaud` and `himmelblaud-tasks`.
The installer delegates package installation to your system package manager. It does not download or install Himmelblau binaries directly.
For manual repository setup or source builds, see Installing Himmelblau.

After installation, log in with your Entra ID or OIDC credentials.

Optional: manual config, PAM, NSS, and service restart

If you need to edit configuration

The installer normally writes `/etc/himmelblau/himmelblau.conf` for you. Edit it manually only if the installer did not prompt for your identity provider settings, or if you need to change them later.
The `himmelblau.conf` configuration file uses the INI file format.
Set the primary domain of your Entra ID tenant in `/etc/himmelblau/himmelblau.conf`:

[global]
domain = example.onmicrosoft.com

For generic OIDC providers such as Google Workspace, Okta, or Keycloak, set the issuer URL and client ID:

[global]
oidc_issuer_url = https://keycloak.example.com/realms/himmelblau
app_id = himmelblau-login

To enforce MDM Intune compliance, enable it:

[global]
apply_policy = true

For additional configuration options, see the himmelblau.conf man page.

If PAM was not configured automatically

On most Linux distributions, PAM configuration happens automatically when you install Himmelblau. If you use distribution-provided packages, you may need to configure PAM manually.
On openSUSE or SUSE Linux Enterprise:

sudo pam-config --add --himmelblau

On all other distros, you can run the manual config utility bundled with Himmelblau:

sudo aad-tool configure-pam

For more detail, see PAM configuration.

If NSS was not configured automatically

On most Linux distributions, NSS configuration happens automatically when you install Himmelblau.
Add `himmelblau` to your `/etc/nsswitch.conf` to resolve Entra ID users and groups.

passwd:     files himmelblau
group:      files himmelblau

For more detail, see NSS configuration.

If you changed configuration manually

The Himmelblau installer normally enables and starts the daemons for you. If you edit configuration manually, restart them:

sudo systemctl enable himmelblaud himmelblaud-tasks
sudo systemctl restart himmelblaud himmelblaud-tasks