AAD-TOOL(1)

📦 version 2.3.14+git0.e23b4c54, in opensuse-leap 16.0

💅 NAME ✨

aad-tool — the Azure Entra ID (AAD) management utility for Himmelblau, bestie. This is the aad-tool(1) manual page and we are gonna get through it together 🫶

🌸 SYNOPSIS 🌸

aad-tool <COMMAND> [OPTIONS]

🦋 DESCRIPTION 🦋

Okay so aad-tool is part of the Himmelblau project, and its whole thing is managing and interacting with Azure Entra ID through a bunch of different commands. It lets you test authentication, manage caches, and check the status of services related to the himmelblaud resolver. That's the vibe 💖

⭐ SYNOPSIS (yes, again) ⭐

aad-tool <COMMAND>

👑 DESCRIPTION — Himmelblau Management Utility 👑

Literally what it says on the tin: it's the Himmelblau Management Utility. Periodt.

🎀 Commands:

  • application — manage Entra ID application registrations, including creation, listing, and extension schema configuration ✨
  • auth-test — test authentication of a user via the himmelblaud resolver "pam" channel. Important: this does not test that your pam configuration is correct — only that himmelblaud is correctly processing and validating authentications 🫶
  • cache-clear — clear or invalidate the himmelblaud resolver cache
  • cache-invalidate — (Deprecated) previously used to mark cache entries as stale for immediate refresh. Now behaves identically to cache-clear and will be removed in a future release 💀
  • configure-pam — configure PAM to use pam_himmelblau
  • cred — manage confidential client credentials for authenticating to Entra ID
  • enumerate — enumerate all users and groups in Entra ID that have rfc2307 attributes, and cache their values locally. This addresses the issue where UID/GID mappings are needed before authentication can succeed, but are normally only retrievable after login. Iconic problem-solving ngl 🌟
  • user — manage Entra ID user accounts, including POSIX attribute assignment and UID mapping
  • group — manage Entra ID groups, including POSIX attribute assignment and GID mapping
  • idmap — manage the static idmapping cache used to map Entra ID accounts to static UID/GID values. This is useful for migrations from on-prem AD to Entra ID, where existing UID/GID mappings need to be preserved 🧚
  • offline-breakglass — activate or deactivate Himmelblau's offline breakglass mode
  • status — check that the himmelblaud daemon is online and able to connect correctly to the himmelblaud server
  • tpm — check whether Himmelblau is utilizing the TPM
  • version — show the version of this tool
  • help — print this message or the help of the given subcommand(s)

✨ OPTIONS ✨

  • -h, --help — print help

🎀 SUBCOMMAND

aad-tool application add-schema-extensions

aad-tool application add-schema-extensions [OPTIONS] --client-id <CLIENT_ID> --schema-app-object-id <SCHEMA_APP_OBJECT_ID>

🦋 DESCRIPTION 🦋

Adds a standard set of POSIX-related schema extensions to an existing Entra ID application. So slay of it.

This command registers directory extension attributes (like uidNumber, gidNumber, unixHomeDirectory, loginShell, gecos) on the application specified by --schema-app-object-id. These extensions will be usable on user and/or group objects, as appropriate 💖

The application specified by --schema-app-object-id must already exist in the tenant, and must be identified by its Object ID (not the Client ID — say it louder for the people in the back 😭). This value is labeled as "Object ID" in the Entra Admin Center and corresponds to the id field in Graph API responses.

You must also supply a separate --client-id that grants Application.ReadWrite.All permissions to perform the extension registration.

If the --name parameter is omitted, the command authenticates as the currently logged-in user via the Himmelblau SSO broker. If the --name parameter is provided, the command attempts to authenticate as the specified Entra ID user. In this case, the command must be run as root to impersonate another user 🔥

This command must be run from a device that has already been joined to Entra ID.

✨ OPTIONS ✨

  • -d, --debug — the manual lists it with zero blurb, so I'm not gonna invent one, bestie 🫶
  • -D, --name <ACCOUNT_ID> — same deal, no blurb here either
  • --client-id <CLIENT_ID> — also blurb-less in the original
  • --schema-app-object-id <SCHEMA_APP_OBJECT_ID> — yep, also just listed
  • -h, --help — print help (see a summary with -h)

🎀 SUBCOMMAND

aad-tool application create

aad-tool application create [OPTIONS] --client-id <CLIENT_ID> --display-name <DISPLAY_NAME>

🦋 DESCRIPTION 🦋

Creates a new Entra ID application registration in the current tenant. Main character energy fr fr 👑

This command performs a delegated Microsoft Graph API request using an access token acquired via the specified client application (--client-id), which must have Application.ReadWrite.All permissions in the tenant.

The new application will be created with the provided --display-name.

You may specify one or more --redirect-uri options to configure redirect URIs for the application (used for public client authentication). If no redirect URIs are provided, the application will not include any by default 🌸

Use the --user-read-write and/or --group-read-write flags to grant the application additional Microsoft Graph API permissions at registration time, including User.ReadWrite.All and Group.ReadWrite.All.

⚠️ NOTE, and I mean it: if you grant these permissions, it is strongly recommended that you restrict access to the application to specific administrators or groups:
  1. In the Microsoft Entra admin portal, go to Entra???ID -> Enterprise applications and find your app's entry. (Yes, that's literally how it's printed in the manual — the little arrow glyph glitched out 😭 don't come for me.)
  2. Under Properties, set "Assignment required?" to Yes.
  3. Go to Users and groups, click Add, and assign only the specific users or groups you want to have access.

If the --name parameter is omitted, the command authenticates as the currently logged-in user via the Himmelblau SSO broker. If the --name parameter is provided, the command attempts to authenticate as the specified Entra ID user. In this case, the command must be run as root to impersonate another user 💅

This command must be run from a device that has already been joined to Entra ID.

✨ OPTIONS ✨

  • -d, --debug — listed, no blurb, moving on 🫶
  • -D, --name <ACCOUNT_ID> — listed, no blurb
  • --client-id <CLIENT_ID> — listed, no blurb
  • --display-name <DISPLAY_NAME> — listed, no blurb
  • --redirect-uri <URI> — listed, no blurb
  • --user-read-write — listed, no blurb
  • --group-read-write — listed, no blurb
  • -h, --help — print help (see a summary with -h)

🎀 SUBCOMMAND

aad-tool application list-schema-extensions

aad-tool application list-schema-extensions [OPTIONS] --client-id <CLIENT_ID> --schema-app-object-id <SCHEMA_APP_OBJECT_ID>

🦋 DESCRIPTION 🦋

Lists the schema extension attributes registered on an Entra ID application. Receipts, basically 🧾✨

This command retrieves the directory extension attributes (like uidNumber, gidNumber, etc.) that have been added to the application identified by --schema-app-object-id.

The --schema-app-object-id parameter must be the Object ID of the application (not the Client ID), as shown in the Entra Admin Center. This value corresponds to the id field in Microsoft Graph and is required to query extension properties.

You must also supply a separate --client-id that grants Application.Read.All or Application.ReadWrite.All permissions in the tenant to perform this query.

If the --name parameter is omitted, the command authenticates as the currently logged-in user via the Himmelblau SSO broker. If the --name parameter is provided, the command attempts to authenticate as the specified Entra ID user. In this case, the command must be run as root to impersonate another user.

This command must be run from a device that has already been joined to Entra ID.

✨ OPTIONS ✨

  • -d, --debug — listed, no blurb 💜
  • -D, --name <ACCOUNT_ID> — listed, no blurb
  • --client-id <CLIENT_ID> — listed, no blurb
  • --schema-app-object-id <SCHEMA_APP_OBJECT_ID> — listed, no blurb
  • -h, --help — print help (see a summary with -h)

🎀 SUBCOMMAND

aad-tool application list

aad-tool application list [OPTIONS] --client-id <CLIENT_ID>

🦋 DESCRIPTION 🦋

Lists Entra ID application registrations in the current tenant. It's giving inventory day 💅

This command performs a delegated Microsoft Graph API request using an access token acquired via the specified client application (--client-id), which must have Application.Read.All permissions in the tenant.

If the --name parameter is omitted, the command authenticates as the currently logged-in user via the Himmelblau SSO broker. If the --name parameter is provided, the command attempts to authenticate as the specified Entra ID user. In this case, the command must be run as root to impersonate another user 🌈

This command must be run from a device that has already been joined to Entra ID.

✨ OPTIONS ✨

  • -d, --debug — listed, no blurb 🫶
  • -D, --name <ACCOUNT_ID> — listed, no blurb
  • --client-id <CLIENT_ID> — listed, no blurb
  • -h, --help — print help (see a summary with -h)

🎀 SUBCOMMAND

aad-tool auth-test

aad-tool auth-test [OPTIONS] --name <ACCOUNT_ID>

🦋 DESCRIPTION 🦋

Test authentication of a user via the himmelblaud resolver "pam" channel. And listen — this does not test that your pam configuration is correct, only that himmelblaud is correctly processing and validating authentications. Read that twice, it matters 😭💖

✨ OPTIONS ✨

  • -d, --debug — listed, no blurb
  • -D, --name <ACCOUNT_ID> — listed, no blurb
  • -h, --help — print help

🎀 SUBCOMMAND

aad-tool cache-clear

aad-tool cache-clear [OPTIONS]

🦋 DESCRIPTION 🦋

Clear or invalidate the himmelblaud resolver cache. Spring cleaning but make it enterprise 🧹✨

By default, this marks all cached user and group entries as stale, forcing them to refresh immediately when next used.

Specify --nss or --mapped to clear these individual caches as well. Omit both these to clear them all.

Use --full to completely purge the user and group cache entries and unjoin the host from Entra ID.

💀 This is irreversible. Like, actually irreversible. Not "oops I can undo it" irreversible. Be sure.

✨ OPTIONS ✨

  • -d, --debug — listed, no blurb 🫶
  • --nss — only clear the nss cache
  • --mapped — only clear the mapped name cache
  • --full — force a full cache wipe and unjoin the host from Entra ID. This is probably not what you want 😭 (the manual says that, not me)
  • -h, --help — print help (see a summary with -h)

🎀 SUBCOMMAND

aad-tool cache-invalidate

aad-tool cache-invalidate [OPTIONS]

🦋 DESCRIPTION 🦋

(Deprecated) bestie it's on its way out 🙈 Previously used to mark cache entries as stale for immediate refresh. Now behaves identically to cache-clear and will be removed in a future release.

✨ OPTIONS ✨

  • -d, --debug — listed, no blurb
  • --nss — listed, no blurb
  • --mapped — listed, no blurb
  • --full — listed, no blurb
  • -h, --help — print help

🎀 SUBCOMMAND

aad-tool configure-pam

aad-tool configure-pam [OPTIONS]

🦋 DESCRIPTION 🦋

Configure PAM to use pam_himmelblau. That's the whole description, she's brief and she knows it 💅

✨ OPTIONS ✨

  • -d, --debug — listed, no blurb
  • --really — listed, no blurb 🫶 (name's doing a lot of work there)
  • --auth-file <AUTH_FILE> — listed, no blurb
  • --account-file <ACCOUNT_FILE> — listed, no blurb
  • --session-file <SESSION_FILE> — listed, no blurb
  • --password-file <PASSWORD_FILE> — listed, no blurb
  • -h, --help — print help

(part 1 done, but we're not done — more coming ✨)

🌸 SUBCOMMAND — aad-tool cred cert

aad-tool cred cert [OPTIONS] --client-id <CLIENT_ID> --domain <DOMAIN>
--valid-days <VALID_DAYS> --cert-out <CERT_OUT>

💜 DESCRIPTION

Okay so this one generates an RS256 HSM-backed key pair with a self-signed certificate, all for confidential client authentication. Bestie, the key pair literally lives in your hardware. Iconic behavior.

To set this up, here's the whole vibe:

  1. In the Entra ID portal, navigate to Azure Active Directory -> App registrations, then open (or create) your application.
  2. Under Manage > Certificates & secrets, go to the Certificates tab.
  3. Click Upload certificate and select the PEM file generated by this command.
  4. Azure will store this cert for authenticating via public key.

The private key never leaves your TPM (or SoftHSM). Like, not once. It's giving ✨boundaries✨.

When this cred needs renewed in the future, simple run this command again to replace the expired certificate. That's the whole renewal arc, no drama.

Example: aad-tool cred cert --client-id <CLIENT_ID> --valid-days 365 --cert-out /tmp/my-cert.crt

✨ OPTIONS

  • -d, --debug — turn on the debug chatter 🐛
  • --client-id <CLIENT_ID> — The Azure AD application (client) ID this certificate is associated with
  • --domain <DOMAIN> — The tenant domain this certificate is associated with
  • --valid-days <VALID_DAYS> — Number of days the self-signed certificate will be valid
  • --cert-out <CERT_OUT> — Path to write the generated PEM certificate file. This is the file you will upload to Entra ID. Don't lose it, mkay? 🎀
  • -h, --help — Print help (see a summary with -h)

🦋 SUBCOMMAND — aad-tool cred delete

aad-tool cred delete [OPTIONS] --domain <DOMAIN>

💜 DESCRIPTION

Delete confidential client credentials (secret, certificate, or both). Lowkey the Marie Kondo of creds 💅

This deletes stored confidential client credentials from Himmelblau's encrypted cache. If neither --secret nor --cert is specified, both will be deleted. No picking favorites, everything goes.

Example: aad-tool cred delete --domain <DOMAIN> aad-tool cred delete --domain <DOMAIN> --secret aad-tool cred delete --domain <DOMAIN> --cert

✨ OPTIONS

  • -d, --debug — debug mode, on 🐛
  • --domain <DOMAIN> — The tenant domain whose creds will be deleted
  • --secret — Delete only the client secret (not the certificate)
  • --cert — Delete only the client certificate (not the secret)
  • -h, --help — Print help (see a summary with -h)

🌈 SUBCOMMAND — aad-tool cred list

aad-tool cred list [OPTIONS] --domain <DOMAIN>

💜 DESCRIPTION

List the presence of confidential client credentials — like a vibe check for your cache 🔍

This checks Himmelblau's encrypted cache to see whether a client secret and/or client certificate exists for the given domain.

Example: aad-tool cred list --domain <DOMAIN>

✨ OPTIONS

  • -d, --debug — debug mode
  • --domain <DOMAIN> — the domain to check, obvs
  • -h, --help — Print help (see a summary with -h)

🍓 SUBCOMMAND — aad-tool cred secret

aad-tool cred secret [OPTIONS] --client-id <CLIENT_ID> --domain <DOMAIN>
--secret <SECRET>

💜 DESCRIPTION

Store a client secret for confidential client authentication. Ok so here's the recipe 🧑‍🍳

  1. In the Entra ID portal, navigate to Azure Active Directory -> App registrations, then open (or create) your application.
  2. Under Manage > Certificates & secrets, go to the Client secrets tab.
  3. Click New client secret, choose an expiry, and click Add.
  4. Copy the Value (not Secret ID) immediately. You won't be able to see it again. Like, ever. 😭
  5. Use that value with this command to store it in Himmelblau's encrypted cache.

When this cred needs renewed in the future, simple run this command again to replace the expired secret.

Example: aad-tool cred secret --client-id <CLIENT_ID> --secret <SECRET_VALUE>

⚠️ Real talk: grab the Value, not the Secret ID. The portal will not show it to you twice and there is no undo.

✨ OPTIONS

  • -d, --debug — debug mode
  • --client-id <CLIENT_ID> — The Azure AD application (client) ID this secret is associated with
  • --domain <DOMAIN> — The tenant domain this secret is associated with
  • --secret <SECRET> — The client secret value copied from the Entra ID portal
  • -h, --help — Print help (see a summary with -h)

🌟 SUBCOMMAND — aad-tool enumerate

aad-tool enumerate [OPTIONS]

💜 DESCRIPTION

Enumerate all users and groups in Entra ID that have rfc2307 attributes, and cache their values locally. This addresses the issue where UID/GID mappings are needed before authentication can succeed, but are normally only retrievable after login. It's giving catch-22, and we said not today 💀

The --client-id parameter is optional and must refer to a registered Entra ID application with User.Read.All and Group.Read.All permissions.

The --name parameter specifies the Entra ID user on whose behalf the token is requested, enabling delegated access through the specified client application.

This command can only be executed from an Entra Id enrolled host. No enrolled host, no enumeration, periodt.

✨ OPTIONS

  • -d, --debug — debug mode
  • -D, --name <ACCOUNT_ID> — the user on whose behalf the token is requested
  • --client-id <CLIENT_ID> — optional client app for delegated access
  • -h, --help — Print help (see a summary with -h)

🎀 SUBCOMMAND — aad-tool group set-posix-attrs

aad-tool group set-posix-attrs [OPTIONS] --schema-client-id
<SCHEMA_CLIENT_ID> --group-id <GROUP_ID> --gid <GID>

💜 DESCRIPTION

Sets POSIX-related attributes on a specified Entra ID group object. Group glow-up, basically 💅

This command updates the gidNumber attribute on the Entra ID group identified by --group-id, which must be a valid Object ID.

You must also provide the --schema-client-id, which identifies the application where the extension properties were registered. This value must be the Client ID of the application used for schema registration. The application associated with --schema-client-id must supply Group.ReadWrite.All permissions in the tenant. No permission, no slay.

If the --name parameter is omitted, the command authenticates as the currently logged-in user via the Himmelblau SSO broker. If the --name parameter is provided, the command must be run as root to impersonate another user. Root only, iykyk.

This command must be run from a device that has already been joined to Entra ID.

✨ OPTIONS

  • -d, --debug — debug mode
  • -D, --name <ACCOUNT_ID> — impersonate another user (requires root)
  • --schema-client-id <SCHEMA_CLIENT_ID> — the app where the extension properties were registered
  • --group-id <GROUP_ID> — the group's Object ID
  • --gid <GID> — the GID to set
  • -h, --help — Print help (see a summary with -h)

💫 SUBCOMMAND — aad-tool idmap clear

aad-tool idmap clear [OPTIONS]

💜 DESCRIPTION

Clear the contents of the idmap static cache. Fresh start energy ✨

✨ OPTIONS

  • -d, --debug — debug mode
  • -h, --help — Print help

🧚 SUBCOMMAND — aad-tool idmap group-add

aad-tool idmap group-add [OPTIONS] --object_id <OBJECT_ID> --gid <GID>

💜 DESCRIPTION

Add a static group mapping to the idmap cache. This maps an Entra ID group (by Object Id GUID) to a fixed GID. This can be used to maintain group identity and membership compatibility after moving to Entra ID. Honestly? A lifesaver.

✨ OPTIONS

  • -d, --debug — debug mode
  • -D, --object_id <OBJECT_ID> — the group's Object Id GUID
  • -g, --gid <GID> — the fixed GID to map it to
  • -h, --help — Print help

🫶 SUBCOMMAND — aad-tool idmap user-add

aad-tool idmap user-add [OPTIONS] --name <ACCOUNT_ID> --uid <UID> --gid
<GID>

💜 DESCRIPTION

Add a static user mapping to the idmap cache. This maps an Entra ID user (by UPN or SAM-compatible name) to a fixed UID and primary group GID. Same energy as above, but for people 🫶

✨ OPTIONS

  • -d, --debug — debug mode
  • -D, --name <ACCOUNT_ID> — the user's UPN or SAM-compatible name
  • -u, --uid <UID> — the fixed UID
  • -g, --gid <GID> — the primary group GID
  • -h, --help — Print help

🔥 SUBCOMMAND — aad-tool offline-breakglass

aad-tool offline-breakglass [OPTIONS]

💜 DESCRIPTION

Activate or deactivate Himmelblau's offline breakglass mode. Emergency mode, but make it controlled 🚨

This command enables temporary offline password authentication when Azure Entra ID is unreachable. When invoked, Himmelblau enters a controlled "breakglass" state, allowing cached Entra ID user passwords to be used for login until the TTL expires.

Breakglass mode can only be activated if it was previously enabled in /etc/himmelblau/himmelblau.conf under the [offline_breakglass] section. If the feature was disabled, calling this command will have no effect, and no password verifiers will have been cached. So like… plan ahead, bestie 🙈

Once activated, Himmelblau will:

  • Allow cached Entra ID users to log in using their known password.
  • Automatically exit breakglass mode after the TTL expires or once Entra ID connectivity has been restored.

Use --ttl to override the configured duration for this session. The TTL value accepts a time unit suffix (m, h, or d) and defaults to the value defined in himmelblau.conf if omitted.

To manually exit breakglass mode before TTL expiry, run: aad-tool offline-breakglass --ttl 0

✨ OPTIONS

  • -d, --debug — debug mode
  • --ttl <TTL> — override the configured duration for this session
  • -h, --help — Print help (see a summary with -h)

🌸 EXAMPLES

# Activate breakglass mode for 2 hours
aad-tool offline-breakglass --ttl 2h

# Force disable breakglass mode immediately
aad-tool offline-breakglass --ttl 0

# Use the configured default TTL (from himmelblau.conf)
aad-tool offline-breakglass

Notes:

  • If [offline_breakglass] enabled = false in himmelblau.conf, this command will do nothing.
  • Himmelblau will not cache Entra ID password hashes unless offline breakglass has been explicitly enabled in advance.
  • This feature should only be used for emergency access during verified outages.
🚨 Lowkey the most important note here: this is emergency access only, during verified outages. It's not a shortcut, it's a fire exit.

🦋 SUBCOMMAND — aad-tool status

aad-tool status [OPTIONS]

💜 DESCRIPTION

Check that the himmelblaud daemon is online and able to connect correctly to the himmelblaud server. Vibe check on the daemon 💫

✨ OPTIONS

  • -d, --debug — debug mode
  • -h, --help — Print help

👑 SUBCOMMAND — aad-tool tpm

aad-tool tpm [OPTIONS]

💜 DESCRIPTION

Check whether Himmelblau is utilizing the TPM. Is the hardware doing its thing? Let's find out 🔍

✨ OPTIONS

  • -d, --debug — debug mode
  • -h, --help — Print help

💖 SUBCOMMAND — aad-tool user set-posix-attrs

aad-tool user set-posix-attrs [OPTIONS] --schema-client-id
<SCHEMA_CLIENT_ID> --user-id <USER_ID>

💜 DESCRIPTION

Sets POSIX-related attributes on a specified Entra ID user object. User glow-up, the sequel 💅

This command updates POSIX attributes (uidNumber, gidNumber, unixHomeDirectory, loginShell, and gecos) on the Entra ID user identified by --user-id, which must be a valid Object ID or UPN.

You must also provide the --schema-client-id, which identifies the application where the extension properties were registered. This value must be the Client ID of the application used for schema registration. The application associated with --schema-client-id must supply User.ReadWrite.All permissions in the tenant.

If the --name parameter is omitted, the command authenticates as the currently logged-in user via the Himmelblau SSO broker. If the --name parameter is provided, the command must be run as root to impersonate another user. Root privileges, no exceptions.

This command must be run from a device that has already been joined to Entra ID.

✨ OPTIONS

  • -d, --debug — debug mode
  • -D, --name <ACCOUNT_ID> — impersonate another user (requires root)
  • --schema-client-id <SCHEMA_CLIENT_ID> — the app where the extension properties were registered
  • --user-id <USER_ID> — a valid Object ID or UPN
  • --uid <UID> — sets uidNumber
  • --gid <GID> — sets gidNumber
  • --home <HOME> — sets unixHomeDirectory
  • --shell <SHELL> — sets loginShell
  • --gecos <GECOS> — sets gecos
  • -h, --help — Print help (see a summary with -h)

🌈 SEE ALSO

himmelblau.conf(5), himmelblaud(8), himmelblaud-tasks(8) — go read those too, they're part of the lore 🫶

🎀 AUTHOR

David Mulder <dmulder@himmelblau-idm.org>, <dmulder@samba.org> — shoutout to the main character who wrote all this 👑

That's the whole page, bestie! This is aad-tool from the 2025-10-31 release of the man page — go forth, set your POSIX attrs, and keep that private key in the TPM where it belongs. 💜✨🎀

📦 where this page comes from