Einer internen Webanwendung „Anmelden mit Microsoft-Konto“ hinzuzufügen, wirkt wie ein paar Zeilen Bibliothekskonfiguration. Ist es aber nicht. Welcher Flow gewählt wird, wo Tokens liegen und aus welchem Claim die Berechtigung gelesen wird, bestimmt direkt das Sicherheitsniveau der Anwendung. Im Folgenden behandeln wir die OpenID-Connect-Anmeldung (OIDC) mit Microsoft Entra ID von Anfang bis Ende: Authorization-Code-Flow mit PKCE, App-Registrierung, Tokentypen und Speicherung, rollenbasierte Autorisierung, Abmeldung und die in der Praxis häufigsten AADSTS-Fehlercodes.
Rollen in OIDC und OAuth 2.0
OAuth 2.0 (RFC 6749) ist ein Autorisierungs-Rahmenwerk: Es erlaubt einem Client, im Namen des Benutzers auf eine Ressource zuzugreifen. OpenID Connect fügt darüber eine Identitätsschicht hinzu und definiert das ID Token, das dem Client mitteilt, wer der Benutzer ist. Im Entra-ID-Szenario ordnen sich die Rollen so zu:
| Rolle | Im Entra-ID-Szenario |
|---|---|
| OpenID Provider / Autorisierungsserver | Microsoft Identity Platform (login.microsoftonline.com) |
| Relying Party / Client | Ihre Webanwendung (App-Registrierung) |
| Ressourcenserver | Ihre eigene API oder Microsoft Graph |
| Ressourcenbesitzer | Angemeldeter Benutzer |
Diese Unterscheidung klar zu machen, verhindert von Anfang an den Fehler, den wir im Code-Review am häufigsten sehen: Authentifizierung (ID Token) und das Einholen einer Zugriffsberechtigung für eine API (Access Token) sind verschiedene Aufgaben und werden mit verschiedenen Tokens erledigt. Das ID Token wird nicht an die API gesendet. Mit welchen Berechtigungen die Anwendung auf Microsoft Graph zugreift, ist ein eigenes Designthema; das beschreiben wir im Beitrag Microsoft-Graph-API-Berechtigungen. Hier geht es um den Anmeldeflow des Benutzers in die Anwendung.
Authorization-Code-Flow mit PKCE
Der für Webanwendungen empfohlene Flow ist der mit PKCE (RFC 7636) gehärtete Authorization-Code-Flow. Der früher in Single-Page-Anwendungen genutzte Implicit Flow wird nicht mehr empfohlen, da er das Token im URL-Fragment transportiert. Die Schritte des Flows:
- Die Anwendung erzeugt einen zufälligen
code_verifierund berechnet die base64url-Kodierung seines SHA-256-Hashs alscode_challenge. Außerdem erzeugt sie einenstategegen CSRF und einennoncegegen Replay und speichert beide in der Sitzung des Benutzers. - Der Browser wird zum Autorisierungsendpunkt weitergeleitet (unten eine URL-kodierte Beispielanfrage).
- Der Benutzer authentifiziert sich in Entra ID; Richtlinien für bedingten Zugriff und MFA greifen in dieser Phase.
- Entra ID schickt den Browser mit einem
codeundstatean die registrierte Umleitungs-URI zurück. - Die Anwendung prüft den
stateund tauscht den Code am Token-Endpunkt mitcode_verifierund Client-Anmeldedaten gegen Tokens. - Signatur sowie die Werte
iss,aud,expundnoncedes ID Tokens werden geprüft; die Anwendung erstellt ihre eigene Sitzung.
GET https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
?client_id={client-id}
&response_type=code
&redirect_uri=https%3A%2F%2Fportal.beispiel.de%2Fsignin-oidc
&response_mode=form_post
&scope=openid%20profile%20offline_access
&state={zufaelliger-state}
&nonce={zufaelliger-nonce}
&code_challenge={code-challenge}
&code_challenge_method=S256
Codieren Sie diese Schritte nicht von Hand. Verwenden Sie eine ausgereifte Bibliothek: Microsoft.Identity.Web für ASP.NET Core, MSAL Node oder eine standardkonforme OIDC-Client-Bibliothek für Node.js. Die Grundkonfiguration in ASP.NET Core sieht so aus:
// Program.cs
builder.Services
.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
.AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"));
// appsettings.json
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"TenantId": "{tenant-id}",
"ClientId": "{client-id}",
"CallbackPath": "/signin-oidc"
// Client-Anmeldedaten zum Tausch des Codes gegen Tokens und fuer API-Aufrufe
// werden unter "ClientCredentials" definiert (Zertifikat bevorzugt)
}
Tragen Sie als Mandant statt common oder organizations Ihre eigene Mandanten-ID ein. So sind Anmeldeversuche mit Konten anderer Organisationen in einer internen Anwendung von vornherein ausgeschlossen.
App-Registrierung und Umleitungs-URIs
Die im Entra Admin Center unter App registrations angelegte Registrierung ist die Identität der Anwendung. Bei der Einrichtung einzeln zu prüfende Einstellungen:
- Unterstützte Kontotypen: Für eine interne Anwendung „nur Konten in diesem Organisationsverzeichnis“ (ein Mandant).
- Plattformtyp: Für eine serverseitige Anwendung Web; für eine Single-Page-Anwendung, die das Token direkt im Browser erhält, Single-page application. Ein falscher Plattformtyp ist die häufigste Ursache der unten aufgeführten Fehlercodes.
- Umleitungs-URIs: Es wird eine exakte Übereinstimmung verlangt, einschließlich Schema, Domain, Port, Pfad und abschließendem Schrägstrich. Außer für
localhostist HTTPS Pflicht. Legen Sie für Entwicklung, Test und Produktion separate Registrierungen an; sonst bleiben Testadressen in der Produktionsregistrierung vergessen. - Implicit-Grant-Optionen: Im Authorization-Code-Flow müssen die Kontrollkästchen „ID tokens“ und „Access tokens“ deaktiviert bleiben.
- Client-Anmeldedaten: Bevorzugen Sie statt eines Client-Geheimnisses ein Zertifikat, wenn möglich eine federated/managed identity. Nutzen Sie ein Geheimnis, verknüpfen Sie dessen Ablaufdatum mit einem Kalender und einem Monitoring-Eintrag. Ein abgelaufenes Geheimnis sperrt eines Morgens alle Benutzer aus.
- Benutzerzuweisung: Wird unter Enterprise applications „Assignment required?“ aktiviert, können sich nur zugewiesene Benutzer und Gruppen anmelden.
Tokentypen und sichere Speicherung
| Token | Zweck | Wer es nutzt |
|---|---|---|
| ID Token | Identität und Sitzungsinformationen des Benutzers | Client-Anwendung |
| Access Token | Zugriff auf eine bestimmte API | Ziel-API (Wert aud) |
| Refresh Token | Neues Access Token ohne Benutzerinteraktion erhalten | Nur der Client, sendet es an den Token-Endpunkt |
In der Microsoft Identity Platform ist die Standardlebensdauer von Access Tokens kurz, und sie werden per Refresh Token erneuert; auf der Single-Page-Application-Plattform ausgestellte Refresh Tokens leben noch kürzer. Microsoft kann diese Zeiten ändern. Gehen Sie im Code nicht von festen Laufzeiten aus; nutzen Sie die Werte expires_in und exp.
Für die Speicherentscheidung gibt es zwei Hauptmuster:
- BFF (Backend for Frontend): Tokens liegen nur auf dem Server im Sitzungsspeicher; der Browser erhält nur ein Sitzungscookie mit den Attributen
HttpOnly,SecureundSameSite=Lax(oderStrict). API-Aufrufe laufen über das BFF. Selbst bei XSS kann der Angreifer das Token nicht lesen. Für Unternehmensanwendungen ist das die Standardwahl. In Next.js-Webanwendungen mit App Router wird dieses Muster umgesetzt, indem Tokens nur in Servermodulen bleiben; wie die Grenze gezogen wird, beschreibt der Beitrag Trennung von Server und Client Component im Next.js App Router. - Token im Browser: MSAL Browser hält Tokens standardmäßig in
sessionStorage. Eine separate Serverschicht ist nicht nötig; aber jedes auf der Seite laufende Skript kann auf das Token zugreifen. Wird dieses Muster gewählt, werden Content Security Policy (CSP), Kontrolle von Drittanbieterskripten und kurze Tokenlaufzeit zur Pflicht. Verwenden Sie keinlocalStorage.
Ihre eigene API sollte beim Prüfen des Access Tokens Folgendes abgleichen: die Signatur mit dem Schlüssel vom JWKS-Endpunkt des Mandanten, den Wert iss mit Ihrem Mandanten, den Wert aud mit App-ID/URI der API und die Claims scp oder roles mit den erwarteten Berechtigungen. Bei der Zuordnung des Benutzers in der Anwendungsdatenbank werden nicht die E-Mail, sondern oid und tid gemeinsam genutzt. Die E-Mail ändert sich; oid nicht.
Autorisierung über App-Rollen und Gruppen-Claims
Für die Autorisierung gibt es zwei Quellen: App-Rollen (App Roles) und Gruppen-Claims. App-Rollen werden in der Registrierung definiert (Bereich App roles; etwa Anfrage.Erstellen, Anfrage.Freigeben, Administrator), über die Unternehmensanwendung Benutzern oder Gruppen zugewiesen und kommen im Token als Claim roles. Da Rollennamen anwendungsspezifisch und sprechend sind, bleibt der Code lesbar:
[Authorize(Roles = "Anfrage.Freigeben")]
public IActionResult Freigeben(Guid anfrageId) { ... }
Gruppen-Claims (Token configuration > Add groups claim) transportieren Gruppen-Objekt-IDs. Sie haben zwei Einschränkungen: Im Code ist die Arbeit mit GUID-Listen mühsam, und ist der Benutzer Mitglied sehr vieler Gruppen, wird im Token statt der Gruppen ein Überschreitungs-Indikator (Overage) gesetzt. Im JWT liegt diese Grenze bei 200 Gruppen; wird sie überschritten, muss die Anwendung die Gruppen separat über Microsoft Graph abfragen. Code, der in der Testumgebung mit einem Benutzer mit drei Gruppen läuft, bricht in der Produktion bei einer Führungskraft mit Hunderten Gruppenmitgliedschaften. Die Rangfolge ist daher klar: zuerst App-Rollen; sind Gruppen Pflicht, die Option „nur der Anwendung zugewiesene Gruppen“. Für Portale mit kundenbezogenen Berechtigungen, in denen das Rollenmodell mit der Datenschicht verbunden wird, siehe den Beitrag Autorisierungsarchitektur im B2B-Portal.
Abmeldung und häufige Fehler
Die Abmeldung hat zwei Ebenen: das eigene Sitzungscookie der Anwendung löschen und den Benutzer mit dem Parameter post_logout_redirect_uri zum Endpunkt für die Sitzungsbeendigung von Entra ID (/oauth2/v2.0/logout) weiterleiten. Löschen Sie nur das lokale Cookie, bleibt die Entra-Sitzung offen; klickt der Benutzer auf „Anmelden“, wird er stillschweigend wieder eingelassen. Auf gemeinsam genutzten Geräten ist dieser Unterschied ein ernstes Problem. Ist in der App-Registrierung eine front-channel logout URL definiert, ruft Entra ID diese Adresse auf, wenn sich der Benutzer aus einer anderen Anwendung abmeldet, und die Anwendung kann die lokale Sitzung bereinigen.
Die in der Praxis häufigsten Fehlercodes und ihre Bedeutung:
| Code | Bedeutung | Typische Lösung |
|---|---|---|
| AADSTS50011 | Umleitungs-URI stimmt nicht mit der Registrierung überein | Schema/Host hinter dem Reverse Proxy korrigieren, URI exakt hinzufügen |
| AADSTS700054 | Antworttyp id_token nicht aktiviert |
Bibliothek auf den Code-Flow umstellen |
| AADSTS65001 | Benutzer- oder Administratorzustimmung fehlt | Administratorzustimmung für die Berechtigungen erteilen |
| AADSTS50105 | Benutzer ist der Anwendung nicht zugewiesen | Benutzer oder seine Gruppe der Anwendung zuweisen |
| AADSTS7000215 | Ungültiges Client-Geheimnis | Den Wert des Geheimnisses (nicht seine ID) verwenden, Ablauf prüfen |
| AADSTS9002326 | Ursprungsübergreifender Tokenbezug nur beim Typ SPA möglich | Umleitungs-URI zum richtigen Plattformtyp verschieben |
Die häufigste Quelle von AADSTS50011 sind Installationen, bei denen TLS am Reverse Proxy terminiert wird und die Anwendung glaubt, über http:// zu laufen. Die Anwendung erzeugt die Umleitungs-URI mit http, in der Registrierung steht https, die Übereinstimmung scheitert. In ASP.NET Core muss die Middleware ForwardedHeaders, in Node.js die Proxy-Vertrauenseinstellung (trust proxy) das ursprüngliche Schema und den Host an die Anwendung weitergeben. Für die vollständige Beschreibung eines Fehlercodes geben Sie den Code auf der Seite login.microsoftonline.com/error ein.
Checkliste vor dem Livegang:
- Ein Mandant, richtiger Plattformtyp und separate App-Registrierung pro Umgebung.
state,nonceund PKCE von der Bibliothek aktiviert; Implicit Grant deaktiviert.- Tokens im BFF; im Browser nur ein Cookie mit
HttpOnlyundSecure. - Benutzerzuordnung über
oid+tid; Berechtigung aus App-Rollen. - Bei der Abmeldung werden lokale Sitzung und Entra-Sitzung beendet.
- Ablaufdatum von Client-Geheimnis/Zertifikat wird überwacht.
Die Stärke der Anmeldung hängt von der Authentifizierungsmethode auf Entra-ID-Seite ab; zur Umstellung auf phishingresistente Methoden siehe den Beitrag Umstellungsplan auf FIDO2 und Passkeys. Beim Hinzufügen von SSO und rollenbasierter Berechtigung zu Ihrer internen Anwendung können wir Flow und Token-Speichermuster im Rahmen unserer Leistung Entwicklung individueller Webanwendungen gemeinsam konzipieren. Als ausführliche Referenz sind die Dokumentation der Microsoft Identity Platform und RFC 7636 maßgeblich.
Häufig gestellte Fragen
Ist PKCE auch in einer serverseitigen Webanwendung nötig?
Nicht zwingend, aber empfohlen. Bei vertraulichen Clients mit Client-Geheimnis oder Zertifikat bietet PKCE zusätzlichen Schutz dagegen, dass ein Autorisierungscode abgefangen und in einer anderen Sitzung verwendet wird. Die OAuth-2.0-Security-Best-Practices (RFC 9700) empfehlen PKCE auch für vertrauliche Clients; aktuelle MSAL-Bibliotheken unterstützen es.
Mit welchem Claim sollte ich den Benutzer in der Anwendungsdatenbank zuordnen?
Für eine dauerhafte und eindeutige Zuordnung werden oid (Objekt-ID) und tid (Mandanten-ID) gemeinsam verwendet. preferred_username, upn oder email können sich ändern oder einem anderen Benutzer neu zugewiesen werden; verwenden Sie sie nur zur Anzeige.
Wann wirkt sich das Entfernen eines Benutzers aus einer Rolle in der Anwendung aus?
Da Rollen und Gruppen bei der Ausstellung des Tokens als Claims geschrieben werden, wirkt die Änderung erst, wenn die Anwendung ein neues Token erhält. Hält die Anwendung ihr eigenes Sitzungscookie lange gültig, verlängert sich die Verzögerung noch. Halten Sie bei sensiblen Berechtigungen die Sitzungsdauer kurz oder verlangen Sie vor dem Vorgang eine erneute Authentifizierung.
Sollte ich ein von Microsoft Graph erhaltenes Access Token in der Anwendung dekodieren und prüfen?
Nein. Microsoft empfiehlt, Access Tokens, die für eine andere Ressource wie Graph ausgestellt wurden, aus Client-Sicht als opak zu behandeln und nicht zu parsen; ihr Format kann sich ohne Ankündigung ändern. Der Client bezieht Benutzerinformationen aus dem ID Token; Ihre eigene API prüft nur Access Tokens, die für sie ausgestellt wurden.