Microsoft OIDC Integration für HashiCorp Vault

Diese Anleitung beschreibt die Konfiguration von Microsoft Azure AD / Entra ID als OIDC-Provider für HashiCorp Vault, um Single Sign-On (SSO) zu ermöglichen.

Überblick

Mit Microsoft OIDC können sich Benutzer über ihre Microsoft-Accounts (Azure AD / Entra ID) bei Vault authentifizieren, ohne separate Vault-spezifische Credentials zu benötigen.

Vorteile:

Zentrale Benutzerverwaltung über Azure AD
Multi-Faktor-Authentifizierung (MFA) über Azure AD
Single Sign-On für Vault-Zugriff
Automatische Integration mit bestehenden Microsoft-Accounts
Gruppen-basierte Zugriffskontrolle

Voraussetzungen

HashiCorp Vault installiert und initialisiert
Azure AD / Microsoft Entra ID Tenant
Admin-Rechte in Azure AD für App-Registrierung
Vault Root Token oder ausreichende Berechtigungen

Azure AD App-Registrierung

1. Neue App erstellen

Navigiere zum Azure Portal
Gehe zu Azure Active Directory → App registrations
Klicke auf New registration

App-Konfiguration:

Name: Vault OIDC (oder beliebig)
Supported account types:
- Accounts in this organizational directory only (Single tenant)
Redirect URI:
- Platform: Web
- URI: https://vault.iteas.cloud/ui/vault/auth/oidc/oidc/callback
- URI: http://localhost:8250/oidc/callback (für CLI-Zugriff)

Klicke auf Register

2. Client Secret erstellen

Gehe zu Certificates & secrets
Klicke auf New client secret
Description: Vault OIDC Secret
Expires: Wähle passende Laufzeit (z.B. 24 Monate)
Klicke auf Add
Wichtig: Kopiere sofort den Value (wird nur einmal angezeigt!)

3. API Permissions konfigurieren

Gehe zu API permissions
Füge folgende Permissions hinzu:
- Microsoft Graph:
  - email (Delegated)
  - openid (Delegated)
  - profile (Delegated)
  - User.Read (Delegated)
  - Optional: GroupMember.Read.All (Application) für Gruppen-Mapping
Klicke auf Grant admin consent für alle Permissions

4. Optional: Token Configuration

Gehe zu Token configuration
Füge Optional Claims hinzu:
- ID Token:
  - email
  - preferred_username
  - groups (falls Gruppen-Mapping verwendet wird)

5. Notiere wichtige Werte

Aus Overview:

Application (client) ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Directory (tenant) ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Aus Certificates & secrets:

Client secret value: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Vault OIDC Konfiguration

1. OIDC Auth Method aktivieren

bash

# Login mit Root Token
vault login

# OIDC Auth Method aktivieren
vault auth enable oidc

2. OIDC Provider konfigurieren

bash

# OIDC-Konfiguration setzen
vault write auth/oidc/config \
  oidc_discovery_url="https://login.microsoftonline.com/<TENANT_ID>/v2.0" \
  oidc_client_id="<CLIENT_ID>" \
  oidc_client_secret="<CLIENT_SECRET>" \
  default_role="default_role"

Parameter:

<TENANT_ID>: Azure AD Tenant ID (Directory ID)
<CLIENT_ID>: Application (Client) ID aus App-Registrierung
<CLIENT_SECRET>: Client Secret Value
default_role: Standard-Rolle für OIDC-Authentifizierung

Beispiel:

bash

vault write auth/oidc/config \
  oidc_discovery_url="https://login.microsoftonline.com/a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6/v2.0" \
  oidc_client_id="12345678-1234-1234-1234-123456789012" \
  oidc_client_secret="abcDEF123~ghi456JKL789mnoPQR012" \
  default_role="default_role"

3. OIDC Role erstellen

Erstelle eine Role, die OIDC-User auf Vault-Policies mapped.

Standard-Role

Wenn Azure AD Gruppen für Zugriffskontrolle verwendet werden sollen:

bash

vault write auth/oidc/role/default_role \
   user_claim="email" \
   allowed_redirect_uris="https://vault.iteas.cloud/ui/vault/auth/oidc/oidc/callback" \
   allowed_redirect_uris="http://localhost:8250/oidc/callback" \
   groups_claim="groups" \
   oidc_scopes="https://graph.microsoft.com/.default profile" \
   policies="default"

Admin-Role (mit Gruppen-Mapping)

Wenn Azure AD Gruppen für Zugriffskontrolle verwendet werden sollen:

bash

vault write auth/oidc/role/admin \
  allowed_redirect_uris="https://vault.iteas.cloud/ui/vault/auth/oidc/oidc/callback" \
  allowed_redirect_uris="http://localhost:8250/oidc/callback" \
  user_claim="email" \
  groups_claim="groups" \
  bound_claims='{"groups": ["<AZURE_AD_GROUP_ID>"]}' \
  policies="admin"

Zusätzliche Parameter:

groups_claim: Claim für Gruppen-Information
bound_claims: Einschränkung auf bestimmte Azure AD Gruppen wenn benötigt (Object ID)

Azure AD Gruppen-ID finden:

Azure Portal → Azure Active Directory → Groups
Wähle Gruppe aus
Kopiere Object ID

4. Vault Policies erstellen

Erstelle Policies, die den Rollen zugewiesen werden.

Admin Policy

Create admin-policy.hcl:

hcl

path "*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

Apply policy:

bash

vault policy write admin admin-policy.hcl

Navigiere zu https://vault.iteas.cloud
Wähle Method: OIDC
Optional: Wähle Role (falls mehrere Rollen konfiguriert)
Klicke auf Sign in with OIDC Provider
Authentifiziere dich mit Microsoft-Account
Du wirst zurück zu Vault UI geleitet

bash

# Vault Adresse für Session setzen (Linux)
export VAULT_ADDR="https://vault.iteas.cloud"
# ODER für Powershell: 
$env:VAULT_ADDR = "https://vault.iteas.cloud"

# Standard-Role verwenden
vault login -method=oidc -path=oidc

# Spezifische Role verwenden
vault login -method=oidc role=developer

Ablauf:

Vault öffnet automatisch einen Browser
Authentifizierung über Microsoft
Token wird an CLI zurückgegeben
Token ist nun aktiv für weitere Vault-Befehle

Erweiterte Konfiguration

Gruppen-basierte Policies

Vault kann Azure AD Gruppen automatisch auf Vault-Policies mappen.

External Groups erstellen

bash

# 1. Erstelle externe Gruppe für Azure AD Gruppe
vault write identity/group \
  name="devops-admins" \
  type="external" \
  policies="admin"

# 2. Hole OIDC Auth Accessor
OIDC_ACCESSOR=$(vault auth list -format=json | jq -r '.["oidc/"].accessor')

# 3. Erstelle Group Alias (verbindet Azure AD Gruppe mit Vault Gruppe)
vault write identity/group-alias \
  name="<AZURE_AD_GROUP_OBJECT_ID>" \
  mount_accessor="$OIDC_ACCESSOR" \
  canonical_id="<VAULT_GROUP_ID>"

Azure AD Group Object ID findet man unter:

Azure Portal → Azure Active Directory → Groups → [Gruppe] → Object ID

Vault Group ID erhält man aus:

bash

vault read identity/group/name/devops-admins

Beispiel für mehrere Gruppen

bash

# Vault Groups erstellen
vault write identity/group name="azure-ad-admins" type="external" policies="admin"
vault write identity/group name="azure-ad-developers" type="external" policies="developer"
vault write identity/group name="azure-ad-readonly" type="external" policies="readonly"

# OIDC Accessor holen
OIDC_ACCESSOR=$(vault auth list -format=json | jq -r '.["oidc/"].accessor')

# Group Aliases erstellen
vault write identity/group-alias \
  name="11111111-1111-1111-1111-111111111111" \
  mount_accessor="$OIDC_ACCESSOR" \
  canonical_id=$(vault read -field=id identity/group/name/azure-ad-admins)

vault write identity/group-alias \
  name="22222222-2222-2222-2222-222222222222" \
  mount_accessor="$OIDC_ACCESSOR" \
  canonical_id=$(vault read -field=id identity/group/name/azure-ad-developers)

vault write identity/group-alias \
  name="33333333-3333-3333-3333-333333333333" \
  mount_accessor="$OIDC_ACCESSOR" \
  canonical_id=$(vault read -field=id identity/group/name/azure-ad-readonly)

Custom Claims Mapping

Verwende zusätzliche Claims für erweiterte Zugriffskontrolle:

bash

vault write auth/oidc/role/restricted \
  bound_audiences="<CLIENT_ID>" \
  allowed_redirect_uris="https://vault.iteas.cloud/ui/vault/auth/oidc/oidc/callback" \
  user_claim="email" \
  groups_claim="groups" \
  bound_claims='{"groups": ["<GROUP_ID>"], "department": ["IT", "Engineering"]}' \
  claim_mappings='{"preferred_username": "username", "department": "dept"}' \
  token_policies="restricted"

Parameter:

bound_claims: Nur User mit diesen Claim-Werten erhalten Zugriff
claim_mappings: Mappt OIDC Claims auf Vault Metadata

Token-Lebensdauer konfigurieren

bash

vault write auth/oidc/role/long-lived \
  bound_audiences="<CLIENT_ID>" \
  allowed_redirect_uris="https://vault.iteas.cloud/ui/vault/auth/oidc/oidc/callback" \
  user_claim="email" \
  token_ttl=24h \
  token_max_ttl=720h \
  token_period=24h \
  token_policies="default"

Parameter:

token_ttl: Initial Token Lifetime
token_max_ttl: Maximale Lifetime (inkl. Renewals)
token_period: Renewal Period (Token kann unbegrenzt erneuert werden)

Verifizierung

OIDC-Konfiguration prüfen

bash

# OIDC Config lesen
vault read auth/oidc/config

# OIDC Roles auflisten
vault list auth/oidc/role

# Spezifische Role lesen
vault read auth/oidc/role/default

# Auth Methods auflisten
vault auth list

bash

# CLI Login testen
vault login -method=oidc role=default

# Token-Info prüfen
vault token lookup

# Eigene Capabilities prüfen
vault token capabilities secret/data/apps/myapp

# Gruppen-Membership prüfen
vault read identity/entity/name/<USERNAME>

Logging aktivieren

Für Debugging OIDC-Issues:

bash

# In vault.hcl
log_level = "debug"

# Oder zur Laufzeit
vault operator raft autopilot set-config -debug=true

Troubleshooting

Redirect URI Mismatch

Symptom:

Error: redirect_uri_mismatch

Lösung:

Prüfe Redirect URIs in Azure AD App-Registrierung
Stelle sicher, dass beide URIs konfiguriert sind:
- https://vault.iteas.cloud/ui/vault/auth/oidc/oidc/callback
- http://localhost:8250/oidc/callback
Prüfe allowed_redirect_uris in Vault Role-Konfiguration

Invalid Client Secret

Symptom:

Error: invalid_client

Lösung:

Client Secret in Azure AD neu generieren

Vault OIDC-Konfiguration aktualisieren:

bash

vault write auth/oidc/config \
  oidc_client_secret="<NEW_SECRET>" \
  -force

Groups Claim nicht verfügbar

Symptom: Gruppen-Mapping funktioniert nicht

Lösung:

Prüfe API Permissions in Azure AD:
- GroupMember.Read.All muss gewährt sein
Füge groups zu Optional Claims hinzu (Token configuration)
Verwende groups_claim="groups" in Role-Konfiguration
Bei großen Gruppen-Memberships: Azure AD sendet nur Gruppen-IDs, nicht Namen

CLI Port bereits belegt

Symptom:

Error binding to port 8250

Lösung:

bash

# Verwende anderen Port
vault login -method=oidc -port=8300

Discovery URL Fehler

Symptom:

Error: failed to get discovery document

Lösung:

Prüfe Tenant ID in oidc_discovery_url

Teste Discovery URL manuell:

bash

curl https://login.microsoftonline.com/<TENANT_ID>/v2.0/.well-known/openid-configuration

Stelle sicher, dass Vault Internet-Zugriff hat

Best Practices

Separate Rollen für verschiedene Teams/Projekte

bash

vault write auth/oidc/role/team-a ...
vault write auth/oidc/role/team-b ...

Kurze Token-Lebenszeiten mit Renewal
- token_ttl=1h für Sicherheit
- token_max_ttl=12h für Komfort
- Automatisches Renewal via CLI/API
Gruppen-basierte Zugriffskontrolle
- Verwende Azure AD Gruppen statt individueller User
- Zentrale Verwaltung über Azure AD
Multi-Faktor-Authentifizierung
- MFA in Azure AD aktivieren
- Wird automatisch über OIDC durchgesetzt

Audit Logging aktivieren

bash

vault audit enable file file_path=/vault/logs/audit.log

Client Secret Rotation
- Regelmäßig Client Secrets rotieren
- Azure AD: Secret mit Ablaufdatum erstellen
- Vault-Konfiguration aktualisieren vor Ablauf
Namespace-Isolation (Enterprise)
- Separate OIDC-Konfigurationen pro Namespace
- Team-spezifische Roles und Policies
Least Privilege Principle
- Standard-Role mit minimalen Berechtigungen
- Erweiterte Rechte nur für spezifische Gruppen

Migration von anderen Auth Methods

Von Token zu OIDC

bash

# 1. OIDC parallel aktivieren
vault auth enable oidc

# 2. OIDC konfigurieren (siehe oben)

# 3. User testen lassen mit OIDC

# 4. Token-basierte Zugänge schrittweise deaktivieren
vault token revoke -mode=path auth/token

# 5. Optional: Token Auth Method deaktivieren (VORSICHT!)
# vault auth disable token  # Nicht empfohlen, da Root Tokens benötigt werden

Von LDAP zu OIDC

bash

# 1. OIDC aktivieren
vault auth enable oidc

# 2. Policies von LDAP zu OIDC mappen
# LDAP Groups → Azure AD Groups → Vault Policies

# 3. Parallel-Betrieb während Migration

# 4. LDAP deaktivieren nach vollständiger Migration
vault auth disable ldap

Monitoring

OIDC Auth Metrics

bash

# Auth Method Status
vault read sys/auth/oidc/tune

# Login-Statistiken über Audit Log
grep "auth/oidc/login" /vault/logs/audit.log | jq .

# Token-Erneuerungen tracken
vault read sys/internal/counters/tokens

Alerting

Überwache folgende Metriken:

OIDC Login-Fehler (Rate)
Token-Ablehnungen
Client Secret Ablauf-Datum
Ungewöhnliche Login-Muster

Weiterführende Ressourcen

ITeas Setup

Aktuelle Konfiguration

Azure AD Tenant: iteas.onmicrosoft.com

Vault Server: https://vault.iteas.cloud

OIDC Path: /auth/oidc

Redirect URIs:

Web UI: https://vault.iteas.cloud/ui/vault/auth/oidc/oidc/callback
CLI: http://localhost:8250/oidc/callback

Konfigurierte Rollen:

default_role - Standard-Zugriff für alle Azure AD User

Policies:

default - Basis-Zugriff auf persönliche Secrets
admin - Voller Vault-Admin-Zugriff

Microsoft OIDC Integration für HashiCorp Vault ​

Überblick ​

Voraussetzungen ​

Azure AD App-Registrierung ​

1. Neue App erstellen ​

2. Client Secret erstellen ​

3. API Permissions konfigurieren ​

4. Optional: Token Configuration ​

5. Notiere wichtige Werte ​

Vault OIDC Konfiguration ​

1. OIDC Auth Method aktivieren ​

2. OIDC Provider konfigurieren ​

3. OIDC Role erstellen ​

Standard-Role ​

Admin-Role (mit Gruppen-Mapping) ​

4. Vault Policies erstellen ​

Admin Policy ​

Login via OIDC ​

Web UI Login ​

CLI Login ​

Erweiterte Konfiguration ​

Gruppen-basierte Policies ​

External Groups erstellen ​

Beispiel für mehrere Gruppen ​

Custom Claims Mapping ​

Token-Lebensdauer konfigurieren ​

Verifizierung ​

OIDC-Konfiguration prüfen ​

Test-Login durchführen ​

Logging aktivieren ​

Troubleshooting ​

Redirect URI Mismatch ​

Invalid Client Secret ​

Groups Claim nicht verfügbar ​

CLI Port bereits belegt ​

Discovery URL Fehler ​

Best Practices ​

Migration von anderen Auth Methods ​

Von Token zu OIDC ​

Von LDAP zu OIDC ​

Monitoring ​

OIDC Auth Metrics ​

Alerting ​

Weiterführende Ressourcen ​

ITeas Setup ​

Microsoft OIDC Integration für HashiCorp Vault

Überblick

Voraussetzungen

Azure AD App-Registrierung

1. Neue App erstellen

2. Client Secret erstellen

3. API Permissions konfigurieren

4. Optional: Token Configuration

5. Notiere wichtige Werte

Vault OIDC Konfiguration

1. OIDC Auth Method aktivieren

2. OIDC Provider konfigurieren

3. OIDC Role erstellen

Standard-Role

Admin-Role (mit Gruppen-Mapping)

4. Vault Policies erstellen

Admin Policy

Login via OIDC

Web UI Login

CLI Login

Erweiterte Konfiguration

Gruppen-basierte Policies

External Groups erstellen

Beispiel für mehrere Gruppen

Custom Claims Mapping

Token-Lebensdauer konfigurieren

Verifizierung

OIDC-Konfiguration prüfen

Test-Login durchführen

Logging aktivieren

Troubleshooting

Redirect URI Mismatch

Invalid Client Secret

Groups Claim nicht verfügbar

CLI Port bereits belegt

Discovery URL Fehler

Best Practices

Migration von anderen Auth Methods

Von Token zu OIDC

Von LDAP zu OIDC

Monitoring

OIDC Auth Metrics

Alerting

Weiterführende Ressourcen

ITeas Setup