OIDC-Anmeldung und Token-Verwaltung mit Entra ID in Webanwendungen

SSO für Webanwendungen mit Entra ID OIDC: Authorization Code + PKCE, App-Registrierung, Token-Speicherung (BFF), Berechtigung über App-Rollen, Abmeldung und AADSTS-Fehler.
Technische Zusammenfassung
Technologie
Microsoft Entra ID, OpenID Connect, OAuth 2.0, PKCE (RFC 7636), MSAL, Microsoft.Identity.Web
Thema
Unternehmens-SSO und Token-Verwaltung für Webanwendungen
Niveau
Mittel bis fortgeschritten
Voraussetzungen
  • Recht zum Anlegen von App-Registrierungen in Entra ID
  • Kenntnisse zu HTTP-Weiterleitungen und Cookies
  • Vertrautheit mit der JWT-Struktur
In diesem Beitrag7 Abschnitte

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:

  1. Die Anwendung erzeugt einen zufälligen code_verifier und berechnet die base64url-Kodierung seines SHA-256-Hashs als code_challenge. Außerdem erzeugt sie einen state gegen CSRF und einen nonce gegen Replay und speichert beide in der Sitzung des Benutzers.
  2. Der Browser wird zum Autorisierungsendpunkt weitergeleitet (unten eine URL-kodierte Beispielanfrage).
  3. Der Benutzer authentifiziert sich in Entra ID; Richtlinien für bedingten Zugriff und MFA greifen in dieser Phase.
  4. Entra ID schickt den Browser mit einem code und state an die registrierte Umleitungs-URI zurück.
  5. Die Anwendung prüft den state und tauscht den Code am Token-Endpunkt mit code_verifier und Client-Anmeldedaten gegen Tokens.
  6. Signatur sowie die Werte iss, aud, exp und nonce des 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 localhost ist 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, Secure und SameSite=Lax (oder Strict). 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 kein localStorage.

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, nonce und PKCE von der Bibliothek aktiviert; Implicit Grant deaktiviert.
  • Tokens im BFF; im Browser nur ein Cookie mit HttpOnly und Secure.
  • 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.

Support

Kontaktieren Sie uns für Support oder eine Bestandsaufnahme zu diesem Thema.

Kontaktformular
[email protected]

Eretek Web

Wir bauen Unternehmenswebsites, WordPress- und CMS-Plattformen, Intranet- und SharePoint-Portale, Dokumentenmanagement sowie Formular- und Freigabeprozesse auf und halten sie sicher und aktuell.

Wissenszentrum

Weitere Beiträge