Skip to main content
Himmelblau stores all sensitive cryptographic material in a Hardware Security Module (HSM) or a TPM-bound software equivalent. This includes:
  • Windows Hello for Business keys (PIN-protected user authentication keys)
  • Transport keys used during token acquisition
  • Device certificate keys
  • Confidential client credentials (client secrets and certificates used for delegated Graph API queries)
Binding key material to the TPM means that even if the on-disk database is copied, the keys cannot be used on another machine.

​
hsm_type

Controls which HSM backend Himmelblau uses.
ValueBehavior
tpm_bound_soft_if_possible (default)Uses a software HSM that encrypts key material locally. If a TPM is available, the HSM’s parent AuthCode is bound to it.
tpmUses a hardware TPM exclusively. Fails if no TPM is present.
tpm_if_possibleAttempts to use a hardware TPM; falls back to software HSM if none is available. If the TPM was previously used for key storage, the system will not fall back.
[global]
hsm_type = tpm_bound_soft_if_possible
The legacy soft value is deprecated. Existing enrollments using soft are automatically migrated to tpm_bound_soft_if_possible.
For production deployments, tpm or tpm_bound_soft_if_possible with a real TPM is strongly recommended. SoftHSM (the software fallback) is acceptable for testing and development but provides no hardware-backed key protection.

​
hsm_pin_path

The path where the HSM PIN is stored. This PIN protects the HSM key material. 
[global]
hsm_pin_path = /var/lib/himmelblaud/hsm-pin
Default: /var/lib/himmelblaud/hsm-pin. The path can be overridden with the HIMMELBLAU_HSM_PIN_PATH environment variable.

​
tpm_tcti_name

Specifies the TCTI (Trusted Computing Technology Interface) string used to communicate with the TPM. Only relevant when hsm_type is tpm or tpm_if_possible. 
[global]
tpm_tcti_name = device:/dev/tpmrm0
Default: device:/dev/tpmrm0 (the kernel TPM resource manager, recommended for most Linux systems). Use device:/dev/tpm0 for direct device access, or consult your TPM driver documentation for other TCTI strings.

​
Checking TPM status

To confirm whether Himmelblau is using the hardware TPM: 
sudo aad-tool tpm
This prints a status report showing the active HSM backend and whether a hardware TPM is in use.

​
Confidential client credentials

Confidential client credentials allow Himmelblau to query Entra ID for user and group attributes (such as RFC2307 UIDs/GIDs and group memberships) on behalf of the device, without requiring a user to be interactively signed in. All credentials are stored in the HSM.

​
Certificate-based authentication

Generate an HSM-backed RSA key pair and a self-signed certificate, then upload the certificate to your Entra ID app registration: 
sudo aad-tool cred cert \
  --client-id <CLIENT_ID> \
  --domain contoso.com \
  --valid-days 365 \
  --cert-out /tmp/himmelblau-client.pem
The private key is generated inside the TPM (or SoftHSM) and never leaves it. Upload the PEM file at Entra ID portal → App registrations → your app → Certificates & secrets → Certificates. To renew, run the command again with a new --cert-out path and re-upload the certificate.

​
Secret-based authentication

Store a client secret from an Entra ID app registration: 
sudo aad-tool cred secret \
  --client-id <CLIENT_ID> \
  --domain contoso.com \
  --secret <SECRET_VALUE>
Copy the secret Value (not Secret ID) immediately after creating it in the portal — it cannot be retrieved again. To renew, create a new secret in the portal and run this command again.

​
Listing and deleting credentials

List which credentials are currently stored for a domain: 
sudo aad-tool cred list --domain contoso.com
Delete credentials: 
# Delete both secret and certificate
sudo aad-tool cred delete --domain contoso.com

# Delete only the client secret
sudo aad-tool cred delete --domain contoso.com --secret

# Delete only the client certificate
sudo aad-tool cred delete --domain contoso.com --cert

Build docs developers (and LLMs) love

Get started for freeTalk to us