Microsoft Identity Platform und der OAuth 2.0-Autorisierungscodeflow

Die Gewährung eines OAuth 2.0-Autorisierungscodes bzw. der Autorisierungscodeflow ermöglicht es einer Clientanwendung, autorisierten Zugriff auf geschützte Ressourcen wie beispielsweise Web-APIs zu erhalten. Der Autorisierungscodeflow erfordert einen Benutzer-Agent, der die Umleitung vom Autorisierungsserver (Microsoft Identity Platform) zurück zu Ihrer Anwendung unterstützt. Dies kann beispielsweise ein Webbrowser, ein Desktop oder eine mobile Anwendung sein, mit der sich ein Benutzer bei Ihrer Anwendung anmelden und auf seine Daten zugreifen kann.

In diesem Artikel werden Low-Level-Protokolldetails beschrieben, die nur bei der manuellen Erstellung und Ausgabe von unformatierten HTTP-Anforderungen zur Flowausführung benötigt werden, was wir nicht empfehlen. Verwenden Sie stattdessen eine von Microsoft erstellte und unterstützte Authentifizierungsbibliothek, um Sicherheitstoken abzurufen und geschützte Web-APIs in Ihren Apps aufzurufen.

Anwendungen mit Unterstützung des Autorisierungscodeflows

Verwenden Sie den Authentifizierungscodeflow in Verbindung mit Proof Key for Code Exchange (PKCE) und OpenID Connect (OIDC), um Zugriffstoken und ID-Token in den folgenden App-Typen abzurufen:

• Single-Page-Webanwendung (SPA)
• Standardwebanwendung (serverbasiert)
• Desktop-Apps und mobile Apps

Protokolldetails

Der OAuth 2.0-Autorisierungscodefluss wird in Abschnitt 4.1 der OAuth 2.0-Spezifikationbeschrieben. Apps, die den OAuth 2.0-Autorisierungscodeflow verwenden, rufen ein access_token ab. Dieses wird anschließend in Anforderungen an Ressourcen eingefügt, die durch Microsoft Identity Platform geschützt sind ( typischerweise APIs). Apps können auch neue ID- und Zugriffstoken für zuvor authentifizierte Entitäten anfordern, indem sie einen Aktualisierungsmechanismus verwenden.

Diese Abbildung zeigt eine allgemeine Übersicht über den Authentifizierungsfluss:

Umleitungs-URIs für Single-Page-Webanwendungen (SPAs)

Umleitungs-URIs für SPAs, die den Authentifizierungscodeflow verwenden, erfordern eine spezielle Konfiguration.

• Fügen Sie einen Umleitungs-URI hinzu, der den Authentifizierungscodeflow mit PKCE und CORS (Cross-Origin Resource Sharing) unterstützt: Führen Sie die Schritte unter Umleitungs-URI: MSAL.js 2.0 mit dem Authentifizierungscodeflow aus.
• Aktualisieren eines Umleitungs-URIs: Legen Sie mithilfe des Anwendungsmanifest-Editors im Microsoft Entra Admin Center den type des URIs auf spa fest.

Der Umleitungstyp spa ist abwärtskompatibel mit dem impliziten Flow. Apps, die derzeit den impliziten Flow zum Abrufen von Token verwenden, können ohne Probleme auf den Umleitungs-URI-Typ spa umgestellt werden und den impliziten Flow weiterhin verwenden. Trotz dieser Abwärtskompatibilität wird empfohlen, den Authentifizierungscodeflow mit PKCE für SPAs zu verwenden.

Wenn Sie versuchen, den Autorisierungscodeflow zu verwenden, ohne CORS für Ihren Umleitungs-URI einzurichten, wird folgender Fehler in der Konsole angezeigt:

access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Wenn dies der Fall ist, rufen Sie Ihre App-Registrierung auf, und ändern Sie den Umleitungs-URI für Ihre App in den Typ spa.

Anwendung können keinen spa-Umleitungs-URI mit Nicht-SPA-Flows verwenden, zum Beispiel native Anwendungen oder Flows für Clientanmeldeinformationen. Zur Gewährleistung von Sicherheit und bewährten Methoden gibt Microsoft Identity Platform einen Fehler zurück, wenn Sie versuchen, einen spa-Umleitungs-URI ohne Origin-Header zu verwenden. Auf ähnliche Weise verhindert Microsoft Identity Platform auch bei Vorhandensein eines Origin-Headers die Verwendung von Clientanmeldeinformationen in allen Flows, um sicherzustellen, dass Geheimnisse aus dem Browser nicht verwendet werden.

Anfordern eines Autorisierungscodes

Der Autorisierungscodefluss beginnt damit, dass der Client den Benutzer auf den /authorize -Endpunkt leitet. In dieser Beispielanforderung fordert der Client die Berechtigungen openid, offline_access und https://graph.microsoft.com/mail.read vom Benutzer an.

Einige Berechtigungen sind auf Administratoren beschränkt, z. B. das Schreiben von Daten in das Verzeichnis einer Organisation mithilfe von Directory.ReadWrite.All. Wenn Ihre Anwendung von einem Organisationsbenutzer Zugriff auf eine dieser Berechtigungen anfordert, wird dem Benutzer in einer Fehlermeldung mitgeteilt, dass er nicht befugt ist, den Berechtigungen Ihrer App zuzustimmen. Zugriff auf Bereiche, die auf Administratoren beschränkt sind, sollten Sie direkt von einem globalen Administrator anfordern. Weitere Informationen finden Sie unter Auf Administratoren beschränkte Berechtigungen.

Sofern nicht anders angegeben, gibt es keine Standardwerte für optionale Parameter. Es gibt jedoch ein Standardverhalten für eine Anforderung, bei dem optionale Parameter ausgelassen werden. Das Standardverhalten besteht im Anmelden des einzigen aktuellen Benutzers, im Anzeigen der Kontoauswahl bei mehreren Benutzern oder im Anzeigen der Anmeldeseite, wenn keine Benutzer angemeldet sind.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

An dieser Stelle wird der Benutzer aufgefordert, seine Anmeldeinformationen einzugeben und die Authentifizierung abzuschließen. Microsoft Identity Platform stellt auch sicher, dass der Benutzer den Berechtigungen zugestimmt hat, die im Abfrageparameter scope angegeben sind. Wenn der Benutzer keiner Berechtigung zugestimmt hat, wird er aufgefordert, den erforderlichen Berechtigungen zuzustimmen. Weitere Informationen finden Sie unter Berechtigungen und Zustimmung in Microsoft Identity Platform.

Sobald sich der Benutzer authentifiziert und seine Zustimmung erteilt hat, gibt Microsoft Identity Platform mithilfe der im Parameter response_mode festgelegten Methode eine Antwort über den angegebenen redirect_uri an Ihre App zurück.

Erfolgreiche Antwort

Dieses Beispiel zeigt eine erfolgreiche Antwort mithilfe von response_mode=query:

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345

Sie können auch ein ID-Token erhalten, wenn Sie eines anfordern und die implizite Genehmigung in Ihrer Anwendungsregistrierung aktiviert ist. Dieses Verhalten wird manchmal als Hybridflow bezeichnet. Er wird von Frameworks wie ASP.NET verwendet.

Fehlerantwort

Fehlerantworten können auch an den redirect_uri gesendet werden, damit die App diese angemessen behandeln kann:

GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication

Fehlercodes beim Autorisierungsendpunktfehler

Die folgende Tabelle beschreibt die verschiedenen Fehlercodes, die im error -Parameter der Fehlerantwort zurückgegeben werden können:

Anfordern eines ID-Tokens und Hybridflow

Um vor dem Einlösen eines Autorisierungscodes zu ermitteln, wer der Benutzer ist, fordern Anwendungen häufig auch ein ID-Token an, wenn sie den Autorisierungscode anfordern. Dieser Ansatz wird als Hybridflow bezeichnet, da dabei OIDC mit dem OAuth2-Autorisierungscodeflow kombiniert wird.

Der Hybridflow wird häufig bei Web-Apps verwendet, um eine Seite für einen Benutzer zu rendern, ohne bei der Codeeinlösung eine Sperrung zu verursachen. Dies gilt besonders für ASP.NET. Sowohl einseitige als auch herkömmliche Web-Apps profitieren von der geringeren Latenz dieses Modells.

Der Hybridflow ist bis auf drei Ergänzungen identisch mit dem zuvor beschriebenen Autorisierungscodeflow. All diese Ergänzungen sind erforderlich, um ein ID-Token anzufordern: neue Bereiche, ein neuer Antworttyp (response_type) und ein neuer Abfrageparameter nonce.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Die Verwendung von fragment als Antwortmodus verursacht Probleme bei Web-Apps, die den Code aus der Umleitung lesen. Browser übergeben das Fragment nicht an den Webserver. In diesen Fällen sollten die Apps den Antwortmodus form_post verwenden, mit dem sichergestellt wird, dass alle Daten an den Server gesendet werden.

Erfolgreiche Antwort

Dieses Beispiel zeigt eine erfolgreiche Antwort mithilfe von response_mode=fragment:

GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345

Einlösen eines Codes für ein Zugriffstoken

Bei allen vertraulichen Clients haben Sie die Wahl zwischen geheimen Clientschlüsseln oder Zertifikatanmeldeinformationen. Symmetrische gemeinsame Geheimnisse werden von Microsoft Identity Platform generiert. Zertifikatanmeldeinformationen sind asymmetrische Schlüssel, die vom Entwickler hochgeladen werden. Weitere Informationen finden Sie unter Microsoft Identity Platform-Zertifikatanmeldeinformationen für die Anwendungsauthentifizierung.

Für optimale Sicherheit wird die Verwendung von Zertifikatanmeldeinformationen empfohlen. Öffentliche Clients, die native Anwendungen und Single-Page-Webapps enthalten, dürfen beim Einlösen eines Autorisierungscodes keine Geheimnisse oder Zertifikate verwenden. Stellen Sie immer sicher, dass Ihre Umleitungs-URIs den Typ der Anwendung enthalten und eindeutig sind.

Anfordern eines Zugriffstokens mit „client_secret“

Nun, da Sie einen authorization_code erworben und die Berechtigung vom Benutzer erhalten haben, können Sie den code für ein access_token für die gewünschte Ressource einlösen. Senden Sie zum Einlösen des code eine POST-Anforderung an den /token-Endpunkt:

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=11112222-bbbb-3333-cccc-4444dddd5555
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong 
&client_secret=sampleCredentia1s    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.

Anfordern eines Zugriffstokens mit Zertifikatanmeldeinformationen

// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg

Die Parameter sind nahezu identisch mit den Parametern der Anforderung mit dem gemeinsamen Geheimnis, nur werden anstelle des Parameters client_secret die beiden Parameter client_assertion_type und client_assertion verwendet.

Erfolgreiche Antwort

Das Beispiel enthält eine erfolgreiche Tokenantwort:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Fehlerantwort

Dieses Beispiel ist eine Fehlerantwort:

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
  "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

Fehlercodes für Token-Endpunktfehler

Verwenden des Zugriffstokens

Nachdem Sie nun erfolgreich ein access_token abgerufen haben, können Sie das Token für Anforderungen an Web-APIs verwenden, indem Sie es in den Authorization-Header einschließen:

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Aktualisieren des Zugriffstokens

Zugriffs- und ID-Token sind kurzlebig. Aktualisieren Sie sie, nachdem sie abgelaufen sind, um weiterhin auf Ressourcen zugreifen zu können. Dazu übermitteln Sie eine weitere POST-Anforderung an den /token-Endpunkt. Geben Sie den refresh_token anstelle von code an. Aktualisierungstoken sind für alle Berechtigungen gültig, für die Ihr Client bereits Zustimmung erhalten hat. Beispielsweise kann ein Aktualisierungstoken, das für eine scope=mail.read-Anforderung ausgegeben wird, verwendet werden, um ein neues Zugriffstoken für scope=api://contoso.com/api/UseResource anzufordern.

Für Aktualisierungstoken für Web-Apps und native Apps ist keine bestimmte Lebensdauer festgelegt. Normalerweise verfügen Aktualisierungstoken über relativ lange Lebensdauern. In einigen Fällen laufen Aktualisierungstoken jedoch ab, werden widerrufen oder verfügen nicht über ausreichende Berechtigungen für die gewünschte Aktion. Ihre Anwendung muss Fehler, die vom Tokenausstellungsendpunkt zurückgegeben werden erwarten und behandeln. Single-Page-Webapps erhalten ein Token mit einer Lebensdauer von 24 Stunden, d. h. es ist täglich eine neue Authentifizierung erforderlich. Diese Aktion kann im Hintergrund in einem iFrame durchgeführt werden, wenn Cookies von Drittanbietern aktiviert sind. Dies muss in Browsern ohne Drittanbietercookies (z. B. Safari) in einem Frame der obersten Ebene (entweder vollständige Seitennavigation oder Popupfenster) erfolgen.

Aktualisierungstoken werden nicht widerrufen, wenn sie zum Erhalten neuer Zugriffstoken verwendet werden. Es wird erwartet, dass Sie das alte Aktualisierungstoken verwerfen. Die OAuth 2.0-Spezifikation besagt Folgendes: „Der Autorisierungsserver KANN ein neues Aktualisierungstoken ausstellen. In dem Fall MUSS der Client das alte Aktualisierungstoken verwerfen und durch das neue Aktualisierungstoken ersetzen. Der Autorisierungsserver KANN das alte Aktualisierungstoken nach dem Ausstellen eines neuen Aktualisierungstokens für den Client widerrufen.“

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s    // NOTE: Only required for web apps. This secret needs to be URL-Encoded

Erfolgreiche Antwort

Das Beispiel enthält eine erfolgreiche Tokenantwort:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Fehlerantwort

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
  "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

Eine Beschreibung der Fehlercodes und der jeweils empfohlenen Clientaktion finden Sie unter Fehlercodes für Token-Endpunktfehler.

Nächste Schritte

• Wechseln Sie zu den MSAL JS-Beispielen, um in die Programmierung einzusteigen.
• Weitere Informationen finden Sie unter Szenarien für den Tokenaustausch.