Entra ID: Benutzerdefinierte Claims mit Directory Extension Attributes ausgeben

Einfach erklärt: Directory Extension Attributes sind benutzerdefinierte Attribute, die Sie an einer App-Registrierung in Entra ID (Azure AD) anheften. Diese Attribute können Werte wie Sponsor-IDs speichern. Anschließend mappen Sie diese Attribute zu Claims in einer Enterprise-Anwendung und geben sie nur für bestimmte Gruppen frei.

Wann das sinnvoll ist

• Wenn nur bestimmte Benutzergruppen zusätzliche Metadaten (z. B. Sponsor-ID, Partner-ID) im SSO-Token erhalten sollen.
• Wenn Sie keine permanente Änderung am zentralen Benutzerobjekt-Schema wünschen und die Attribute an eine App binden möchten.

Kurzanleitung (Schritt-für-Schritt)

Schritt 1: Directory Extension Attributes registrieren

Verwenden Sie Microsoft Graph (z. B. Graph Explorer) und registrieren Sie pro Zielanwendung die gewünschten Attribute, z. B. sponsorid1 und sponsorid2.

Beispiel-Request:

POST https://graph.microsoft.com/v1.0/applications/{AppObjectId}/extensionProperties

Request-Body-Beispiel:

{
  "name": "sponsorid1",
  "dataType": "String",
  "targetObjects": ["User"]
}

Wiederholen Sie den Aufruf für sponsorid2. Das System liefert anschließend die vollqualifizierten Attributnamen zurück, z. B.:

• extension__sponsorid1
• extension__sponsorid2

Notieren Sie diese exakten Namen für die spätere Verwendung.

Schritt 2: Extension Attributes Benutzern zuweisen

Setzen Sie die Werte für einzelne Benutzer via PATCH auf das Benutzerobjekt.

Request-URL:

PATCH https://graph.microsoft.com/v1.0/users/{UserObjectId}

Request-Body-Beispiel:

{
  "extension__sponsorid1": "ABC123"
}

Wiederholen Sie dies für jeden Benutzer und das jeweils passende Attribut (sponsorid1 oder sponsorid2).

Schritt 3: Claims in der Enterprise-Anwendung erstellen

Navigieren Sie in Entra ID zu: Enterprise-Anwendungen > [App-Name] > Single Sign-On > Attribute & Claims.

1. Klicken Sie auf “Add new claim”.
2. Geben Sie einen Namen an (z. B. sponsorClaim1).
3. Unter Claim-Bedingungen wählen Sie “Member” und die Gruppe, die das Claim erhalten soll.
4. Im Quellattribut wählen Sie den Directory-Extension-Namen (z. B. extension__sponsorid1).

Wiederholen Sie das für die zweite Gruppe und das zweite Attribut.

Schritt 4: Fehler bei Claim-Mapping beheben

Fehler: “Application requires custom signing key to customize claims”

Temporäre Lösung: Sie können das App-Manifest der App-Registrierung anpassen und “acceptMappedClaims”: true setzen. Dadurch ist die Anpassung der Claims möglich, ohne einen benutzerdefinierten Signaturschlüssel bereitzustellen.

Wichtig: Das Setzen von “acceptMappedClaims” kann Sicherheits- und Compliance-Auswirkungen haben. Prüfen Sie die Richtlinien Ihrer Organisation, bevor Sie dies produktiv verwenden.

Schritt 5: Konfiguration testen

Rufen Sie die Anmelde-URL auf (Beispiel) und melden Sie sich mit einem Benutzer an, der zur definierten Gruppe gehört:

https://login.microsoftonline.com/(Tenant ID)/oauth2/v2.0/authorize?client_id=(Client ID)&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345

Öffnen Sie anschließend https://jwt.ms und prüfen Sie das ausgegebene SAML- oder OIDC-Token. Benutzer in der Gruppe sollten das entsprechende Sponsor-Claim (sponsorid1 oder sponsorid2) sehen. Benutzer, die nicht in einer der Gruppen sind, erhalten kein Sponsor-Claim.

Checkliste für Administratoren

• App-Registrierung und AppObjectId bereithalten
• Directory Extension Attributes (Namen) registriert
• Attributewert für jeden Benutzer gesetzt
• Enterprise-App: Claims für die richtigen Gruppen angelegt
• Manifest geprüft auf “acceptMappedClaims” (nur wenn nötig)
• Tests mit jwt.ms oder vergleichbarem Tool durchgeführt

Entwickler- und Betriebshinweise

• Verwenden Sie die Microsoft Graph-API mit geeigneten Berechtigungen (Application oder Delegated) zum Schreiben der extensionProperties und zum Patchen von Benutzern.
• Achten Sie auf Limits: Token-Größe, Anzahl Claims und maximale Länge eines Attributs können Einschränkungen darstellen.
• Vermeiden Sie die Speicherung sensibler personenbezogener Daten, wenn nicht erforderlich.

Wann diese Methode nicht passt (Gegenbeispiele)

• Sie benötigen Claims für alle Anwendungen global statt an eine App gebunden: besser zentrale Benutzerattribute oder Claims-Transformationen prüfen.
• Sie benötigen komplexe Berechnungen oder externe Datenquellen zur Claim-Erstellung: ein Token-Exchange- oder Claims-Provider-Service könnte besser sein.
• Hohe Sicherheitsanforderungen verlangen signierte, nicht veränderbare Tokens mit firmenspezifischen Schlüsseln—dann ist ein eigener Signaturschlüssel oder ein Managed HSM nötig.

Alternative Ansätze

• Azure AD B2C mit benutzerdefinierten Richtlinien (wenn Consumer-Identitäten im Fokus stehen).
• Azure AD Schema Extensions (wenn Attribute nicht an eine einzelne App gebunden sein sollen).
• Externer Tokenservice, der Claims nach Unternehmensregeln anreichert.

Mini-Methodik: Planung bis Betrieb (4 Schritte)

1. Design: Welche Attribute, welche Gruppen, Datenschutzüberlegungen.
2. Implementierung: Eigenschaften registrieren, Benutzerdaten setzen, Claims mappen.
3. Test: Automatisierte Tests + manuelle JWT-Inspektion.
4. Betrieb: Überwachung auf fehlerhafte Tokens und regelmäßige Reviews der Attribute.

Sicherheits- und Datenschutzhinweise

• Minimieren Sie die Menge der übergebenen personenbezogenen Daten.
• Dokumentieren Sie den Zweck der Attribute und die Aufbewahrungsfristen.
• Prüfen Sie, ob die Übertragung der Attribute in Drittapps mit GDPR/DSGVO-konformen Vereinbarungen abgedeckt ist.

Testfälle / Akzeptanzkriterien

• Benutzer A (in Gruppe 1) erhält im Token das Claim mit dem Wert von sponsorid1.
• Benutzer B (in Gruppe 2) erhält sponsorid2, nicht sponsorid1.
• Benutzer C (in keiner Gruppe) erhält kein Sponsor-Claim.
• Änderung eines Attributs wird nach neuem Login im Token reflektiert.

Rollback / Notfallmaßnahmen

• Entfernen Sie die Claim-Definition in der Enterprise-App, wenn fehlerhafte Daten ausgegeben werden.
• Löschen oder leeren Sie die extension-Attribute via PATCH für betroffene Benutzer.
• Setzen Sie “acceptMappedClaims” im Manifest zurück, wenn unklar ist, welche Auswirkungen die Änderung hat.

1‑Zeilen-Glossar

• Entra ID: Microsofts Identitätsdienst (früher Azure AD).
• Directory Extension Attributes: App-gebundene, benutzerdefinierte Attribute.
• Claim: Ein Name/Wert-Paar im SAML-/OIDC-Token.
• Graph API: Microsofts REST-API für Azure-Ressourcen.

Wichtig: Testen Sie Änderungen zuerst in einer Nicht-Produktionsumgebung. Bewerten Sie Compliance- und Sicherheitsanforderungen, bevor Sie produktive Nutzer umstellen.

Zusammenfassung

• Directory Extension Attributes erlauben granulare, app-gebundene Claims.
• Die Schritte lauten: Attribute registrieren, Werte zuweisen, Claims mappen und testen.
• Achten Sie auf Limits, Datenschutz und auf notwendige Manifest-Anpassungen.