AD FS OpenID Connect-/OAuth-Flows und Anwendungsszenarien
Gilt für Active Directory-Verbunddienste (AD FS) 2019 und höher.
| Szenario | Exemplarische Vorgehensweise bei Szenarien mit Beispielen | OAuth 2.0 Flow/Gewährung | Clienttyp |
|---|---|---|---|
| Single-Page-App (SPA) | Beispiel mit MSAL | Implizit | Öffentlich |
| Web-App, die Benutzer anmeldet | Beispiel mit OWIN | Autorisierungscode | Öffentlich, Vertraulich |
| Native App ruft Web-API auf | Beispiel mit MSAL | Autorisierungscode | Öffentlich |
| Web-App ruft Web-API auf | Beispiel mit MSAL | Autorisierungscode | Vertraulich |
| Web-API ruft eine andere Web-API im Auftrag des (OBO) Benutzers auf | Beispiel mit MSAL | On-behalf-of | Web-App agiert vertraulich |
| Daemon-App ruft Web-API auf | Clientanmeldeinformationen | Vertraulich | |
| Web-App ruft Web-API mit Benutzeranmeldeinformationen auf | Kennwortanmeldeinformationen des Ressourcenbesitzers | Öffentlich, Vertraulich | |
| Browserfreie App ruft Web-API auf | Gerätecode | Öffentlich, Vertraulich |
Impliziter Gewährungsflow
Hinweis
Anstelle eines Upgrades auf die neueste Version von AD FS empfiehlt Microsoft dringend die Migration zu Microsoft Entra ID. Weitere Informationen zum impliziten Genehmigungsflow in Microsoft Entra ID finden Sie unter Microsoft Identity Platform und der Flow für die implizite Genehmigung.
Für Single-Page-Apps (AngularJS, Ember.js, React.js usw.) unterstützt AD FS den impliziten OAuth 2.0-Gewährungsflow. Der implizite Fluss wird in der OAuth 2.0-Spezifikation beschrieben. Sein Hauptvorteil besteht darin, dass die App entsprechende Token von AD FS abrufen kann, ohne dass ein Austausch von Anmeldeinformationen auf dem Back-End-Server durchgeführt werden muss. Dieser Flow ermöglicht es der App, innerhalb des JavaScript-Clientcodes Benutzer*innen anzumelden, die Sitzung aufrechtzuerhalten und Token für andere Web-APIs abzurufen. Es gibt einige wichtige Sicherheitsaspekte, die bei der Verwendung des impliziten Flows speziell bei Clients zu berücksichtigen sind.
Wenn Sie den impliziten Flow und AD FS verwenden möchten, um Ihrer JavaScript-App die Authentifizierung hinzuzufügen, folgen Sie den allgemeinen Schritten im folgenden Abschnitt.
Protokolldiagramm
Das folgende Diagramm zeigt, wie der gesamte implizite Anmeldevorgang aussieht, und in den folgenden Abschnitten wird jeder Schritt im Detail beschrieben.
Anfordern von ID-Token und Zugriffstoken
Um Benutzer*innen zunächst in Ihrer App anzumelden, können Sie eine OpenID Connect-Authentifizierungsanforderung senden und ID-Token und Zugriffstoken vom AD FS-Endpunkt abrufen.
// Line breaks for legibility only
https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token+token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
| Parameter | erforderlich/optional | BESCHREIBUNG |
|---|---|---|
| client_id | Erforderlich | Die Anwendungs-ID (Client), die Ihrer App von AD FS zugewiesen wurde. |
| response_type | required | Muss das id_token für die OpenID Connect-Anmeldung enthalten. Kann auch den Antworttyp token enthalten. Wenn Sie hier ein Token verwenden, kann die App sofort ein Zugriffstoken vom Autorisierungsendpunkt erhalten, ohne eine zweite Anforderung an den Tokenendpunkt stellen zu müssen. |
| redirect_uri | Erforderlich | Der redirect_uri (Umleitungs-URI) deiner App, wohin Authentifizierungsantworten gesendet und von deiner App empfangen werden können. Er muss genau mit einem der Umleitungs-URIs übereinstimmen, die du in AD FS konfiguriert hast. |
| nonce | Erforderlich | Ein in der Anforderung enthaltener, von der App generierter Wert, der als Anspruch in das resultierende id_token einbezogen werden soll. Die App kann diesen Wert dann überprüfen, um die Gefahr von Tokenwiedergabeangriffen zu vermindern. Der Wert ist in der Regel eine zufällige, eindeutige Zeichenfolge, die zur Identifizierung des Ursprungs der Anforderung verwendet werden kann. Nur erforderlich, wenn ein id_token angefordert wird. |
| scope | Optional | Eine durch Leerzeichen getrennte Liste von Bereichen. Für OpenID Connect muss der Bereich openid enthalten sein. |
| resource | Optional | Die URL Ihrer Web-API.Hinweis: Wenn Sie die MSAL-Clientbibliothek verwenden, wird der Ressourcenparameter nicht gesendet. Stattdessen wird die Ressourcen-URL als Teil des Bereichsparameters gesendet: scope = [resource url]//[scope values e.g., openid]Wenn die Ressource nicht hier oder im Bereich übergeben wird, verwenden AD FS eine Standardressource (urn:microsoft:userinfo). Ressourcenrichtlinien für Benutzerinformationen wie MFA-, Ausstellungs- oder Autorisierungsrichtlinien können nicht angepasst werden. |
| response_mode | optional | Gibt die Methode an, die verwendet werden soll, um das resultierende Token an deine App zurückzusenden. Dies ist standardmäßig fragment. |
| state | Optional | Ein in der Anforderung enthaltener Wert, der ebenfalls in der Tokenantwort zurückgegeben werden soll. Es kann sich um eine Zeichenfolge mit jedem beliebigen Inhalt handeln. Ein zufällig generierter eindeutiger Wert wird normalerweise verwendet, um websiteübergreifende Anforderungsfälschungsangriffe zu verhindern. Der Status wird auch verwendet, um Informationen über den Status des Benutzers in der App zu codieren, bevor die Authentifizierungsanforderung aufgetreten ist, z. B. Informationen zu der Seite oder Ansicht, die der Benutzer besucht hat. |
| prompt | optional | Gibt den Typ der erforderlichen Benutzerinteraktion an. Die einzigen derzeit gültigen Werte sind „sign-in“ und „none“.- prompt=login zwingt die Benutzer*innen, ihre Anmeldeinformationen für diese Anforderung einzugeben. Einmaliges Anmelden wird somit deaktiviert. - prompt=none stellt das Gegenteil dar. Hiermit wird sichergestellt, dass den Benutzer*innen keinerlei interaktive Eingabeaufforderung angezeigt wird. Wenn die Anforderung nicht im Hintergrund über einmaliges Anmelden abgeschlossen werden kann, wird von AD FS ein interaction_required-Fehler zurückgegeben. |
| login_hint | optional | Dieser Wert kann verwendet werden, um das Feld für den Benutzernamen oder die E-Mail-Adresse auf der Anmeldeseite vorab für den Benutzer auszufüllen, wenn dessen Benutzername im Vorfeld bekannt ist. Apps verwenden diesen Parameter häufig für die erneute Authentifizierung, nachdem sie den Benutzernamen bereits aus einer vorherigen Anmeldung mithilfe des Anspruchs upn aus id_token extrahiert haben. |
| domain_hint | optional | Wenn dies enthalten ist, wird der domänenbasierte Ermittlungsprozess, den Benutzer*innen auf der Anmeldeseite durchlaufen, übersprungen und somit die Benutzerfreundlichkeit verbessert. |
An dieser Stelle wird der Benutzer aufgefordert, seine Anmeldeinformationen einzugeben und die Authentifizierung abzuschließen. Sobald sich Benutzer*innen authentifiziert haben, gibt der AD FS-Autorisierungsendpunkt eine Antwort an die App am angegebenen redirect_uri (Umleitungs-URI) zurück, wobei die im Parameter „response_mode“ angegebene Methode verwendet wird.
Erfolgreiche Antwort
Eine erfolgreiche Antwort unter Verwendung von response_mode=fragment and response_type=id_token+token sieht folgendermaßen aus:
// Line breaks for legibility only
GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZEstZnl0aEV...
&token_type=Bearer
&expires_in=3599
&scope=openid
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZstZnl0aEV1Q...
&state=12345
| Parameter | BESCHREIBUNG |
|---|---|
| access_token | Enthalten, wenn response_type token enthält. |
| token_type | Enthalten, wenn response_type token enthält. Lautet immer „Bearer“. |
| expires_in | Enthalten, wenn response_type token enthält. Gibt die Anzahl der Sekunden an, in denen das Token für die Zwischenspeicherung gültig ist. |
| scope | Gibt die Bereiche an, für die das access_token gültig ist. |
| id_token | Enthalten, wenn response_type id_token enthält. Ein signiertes JSON Web Token (JWT). Die App kann die Segmente dieses Tokens entschlüsseln, um Informationen über den Benutzer, der sich angemeldet hat, anzufordern. Die App kann die Werte zwischenspeichern und anzeigen, aber sie sollte sich nicht auf sie verlassen, wenn es um Autorisierung oder Sicherheitsbegrenzungen geht. |
| state | Wenn ein Statusparameter in der Anforderung enthalten ist, sollte der gleiche Wert in der Antwort angezeigt werden. Die App sollte bestätigen, dass die state-Werte in der Anforderung und der Antwort identisch sind. |
Aktualisierungstoken
Die implizite Genehmigung stellt keine Aktualisierungstoken bereit. Sowohl id_tokens als auch access_tokens laufen nach kurzer Zeit ab. Daher muss Ihre App darauf vorbereitet sein, diese Token regelmäßig zu aktualisieren. Zum Aktualisieren beider Tokentypen können Sie die im vorherigen Abschnitt erwähnte verborgene IFrame-Anforderung unter Verwendung des Parameters prompt=none ausführen, um das Verhalten der Microsoft Identity Platform zu steuern. Wenn Sie ein new id_token erhalten möchten, verwenden Sie unbedingtresponse_type=id_token.
Gewährungsflow für Autorisierungscodes
Hinweis
Anstelle eines Upgrades auf die neueste Version von AD FS empfiehlt Microsoft dringend die Migration zu Microsoft Entra ID. Weitere Informationen zum Autorisierungscode-Genehmigungsflow in Microsoft Entra ID finden Sie unter Microsoft Identity Platform und der OAuth 2.0-Autorisierungscodeflow.
Die OAuth 2. 0-Autorisierungscodegewährung kann in Web-Apps verwendet werden, um Zugriff auf geschützte Ressourcen wie Web-APIs zu erhalten. Der OAuth 2.0-Autorisierungscodefluss wird in Abschnitt 4.1 der OAuth 2.0-Spezifikationbeschrieben. Er wird zur Authentifizierung und Autorisierung in den meisten App-Typen verwendet, einschließlich Web-Apps und nativ installierter Apps. Der Flow ermöglicht Apps das sichere Abrufen von access_token, mit denen auf Ressourcen zugegriffen werden kann, die AD FS vertrauen.
Protokolldiagramm
Allgemein sieht der Authentifizierungsflow für eine native Anwendung ein wenig wie folgt aus:
Anfordern eines Autorisierungscodes
Der Autorisierungscodeflow beginnt damit, dass der Client die Benutzer*innen zum Endpunkt „/authorize“ leitet. In dieser Anforderung gibt der Client die Berechtigungen an, die er vom Benutzer abrufen muss:
// Line breaks for legibility only
https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&resource=https://webapi.com/
&scope=openid
&state=12345
| Parameter | erforderlich/optional | BESCHREIBUNG |
|---|---|---|
| client_id | Erforderlich | Die Anwendungs-ID (Client), die Ihrer App von AD FS zugewiesen wurde. |
| response_type | Erforderlich | Muss den Code für den Autorisierungscodeflow enthalten. |
| redirect_uri | Erforderlich | Der redirect_uri deiner App, wohin Authentifizierungsantworten gesendet und von deiner App empfangen werden können. Er muss genau mit einem der Umleitungs-URIs übereinstimmen, die du im AD FS für den Client registriert hast. |
| resource | Optional | Die URL Ihrer Web-API.Hinweis: Wenn Sie die MSAL-Clientbibliothek verwenden, wird der Ressourcenparameter nicht gesendet. Stattdessen wird die Ressourcen-URL als Teil des Bereichsparameters gesendet: scope = [resource url]//[scope values e.g., openid]Wenn die Ressource nicht hier oder im Bereich übergeben wird, verwenden AD FS eine Standardressource (urn:microsoft:userinfo). Ressourcenrichtlinien für Benutzerinformationen wie MFA-, Ausstellungs- oder Autorisierungsrichtlinien können nicht angepasst werden. |
| scope | Optional | Eine durch Leerzeichen getrennte Liste von Bereichen. |
| response_mode | optional | Gibt die Methode an, die zum Senden des resultierenden Tokens zurück an Ihre App verwendet werden soll. Eine der folgenden Methoden ist möglich: – query – fragment – form_postquery stellt den Code als Abfragezeichenfolgenparameter für Ihren Umleitungs-URI bereit. Beim Anfordern des Codes können Sie „query“, „fragment“ oder „form_post“ verwenden. form_post führt ein POST-Element mit dem Code zu Ihrer Umleitungs-URI aus. |
| state | Optional | Ein in der Anforderung enthaltener Wert, der ebenfalls in der Tokenantwort zurückgegeben werden soll. Es kann sich um eine Zeichenfolge mit jedem beliebigen Inhalt handeln. Ein zufällig generierter eindeutiger Wert wird normalerweise verwendet, um websiteübergreifende Anforderungsfälschungsangriffe zu verhindern. Der Wert kann auch Informationen über den Zustand des Benutzers in der App vor der Authentifizierungsanforderung verschlüsseln, z. B. die Seite oder die Ansicht, auf der bzw. in der sie sich befunden haben. |
| prompt | optional | Gibt den Typ der erforderlichen Benutzerinteraktion an. Die einzigen derzeit gültigen Werte sind „sign-in“ und „none“.- prompt=login zwingt die Benutzer*innen, ihre Anmeldeinformationen für diese Anforderung einzugeben. Einmaliges Anmelden wird somit deaktiviert. - prompt=none stellt das Gegenteil dar. Hiermit wird sichergestellt, dass den Benutzer*innen keinerlei interaktive Eingabeaufforderung angezeigt wird. Wenn die Anforderung nicht im Hintergrund über einmaliges Anmelden abgeschlossen werden kann, wird von AD FS ein interaction_required-Fehler zurückgegeben. |
| login_hint | optional | Dieser Wert kann verwendet werden, um das Feld für den Benutzernamen oder die E-Mail-Adresse auf der Anmeldeseite vorab für den Benutzer auszufüllen, wenn dessen Benutzername im Vorfeld bekannt ist. Apps verwenden diesen Parameter häufig für die erneute Authentifizierung, nachdem sie den Benutzernamen bereits aus einer vorherigen Anmeldung mithilfe des Anspruchs upn aus id_token extrahiert haben. |
| domain_hint | optional | Wenn dies enthalten ist, wird der domänenbasierte Ermittlungsprozess, den Benutzer*innen auf der Anmeldeseite durchlaufen, übersprungen und somit die Benutzerfreundlichkeit verbessert. |
| code_challenge_method | Optional | Die zum Codieren von code_verifier für den code_challenge-Parameter verwendete Methode. Einer der folgenden Werte ist möglich: – plain – S256 Bei Ausschluss wird code_challenge als Nur-Text (plain) angenommen, wenn code_challenge enthalten ist. AD FS unterstützt sowohl „plain“ als auch „S256“. Weitere Informationen finden Sie unter PKCE RFC. |
| code_challenge | Optional | Wird verwendet, um die Gewährung von Autorisierungscodes über Proof Key for Code Exchange (PKCE) von einem nativen Client aus zu sichern. Erforderlich, wenn code_challenge_method enthalten ist. Weitere Informationen finden Sie unter PKCE RFC. |
An dieser Stelle wird der Benutzer aufgefordert, seine Anmeldeinformationen einzugeben und die Authentifizierung abzuschließen. Sobald Benutzer*innen sich authentifiziert haben, gibt AD FS eine Antwort an Ihre App am angegebenenredirect_uri zurück. Hierbei wird die im Parameter response_mode angegebene Methode verwendet.
Erfolgreiche Antwort
Eine erfolgreiche Antwort mit „response_mode=query“ sieht wie folgt aus:
GET https://adfs.contoso.com/common/oauth2/nativeclient?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| Parameter | Beschreibung |
|---|---|
| code | Der von der App angeforderte authorization_code. Die App kann mithilfe des Autorisierungscodes ein Zugriffstoken für die Zielressource anfordern. Authorization_codes sind kurzlebig, in der Regel laufen sie nach etwa 10 Minuten ab. |
| state | Wenn ein Parameter state in der Anforderung enthalten ist, sollte der gleiche Wert in der Antwort angezeigt werden. Die App sollte bestätigen, dass die state-Werte in der Anforderung und der Antwort identisch sind. |
Anfordern eines Zugriffstokens
Nachdem Sie einen authorization_code abgerufen und die Berechtigung des Benutzers bzw. der Benutzerin erhalten haben, können Sie den Code für ein access_token für die gewünschte Ressource einlösen. Lösen Sie den Code ein, indem Sie eine POST-Anforderung an den /token-Endpunkt senden:
// Line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com/
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for confidential clients (web apps)
| Parameter | Erforderlich/optional | BESCHREIBUNG |
|---|---|---|
| client_id | Erforderlich | Die Anwendungs-ID (Client), die Ihrer App von AD FS zugewiesen wurde. |
| grant_type | required | Muss der authorization_code für den Autorisierungscodefluss sein. |
| code | Erforderlich | Der authorization_code, den du im ersten Abschnitt des Flows abgerufen hast. |
| redirect_uri | Erforderlich | Derselbe redirect_uri-Wert, der zum Abrufen des authorization_code verwendet wurde. |
| client_secret | Erforderlich für Web-Apps | Das Anwendungsgeheimnis, das du während der Registrierung der App im AD FS erstellt hast. Du solltest das Anwendungsgeheimnis nicht in einer nativen App verwenden, da client_secrets nicht zuverlässig auf Geräten gespeichert werden können. Er ist erforderlich für Web-Apps und Web-APIs, die die Möglichkeit haben, den geheimen Client-Schlüssel sicher auf dem Server zu speichern. Der geheime Clientschlüssel muss vor dem Senden mit einer URL codiert werden. Diese Apps können auch eine schlüsselbasierte Authentifizierung verwenden, indem sie ein JWT signieren und dies als client_assertion-Parameter hinzufügen. |
| code_verifier | Optional | Derselbe code_verifier, der zum Erhalten des authorisation_code verwendet wurde. Erforderlich, wenn PKCE bei der Anforderung für die Gewährung des Autorisierungscodes verwendet wurde. Weitere Informationen finden Sie unter PKCE RFC. Diese Option gilt für AD FS 2019 und höher. |
Erfolgreiche Antwort
Eine erfolgreiche Token-Antwort sieht wie folgt aus:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| Parameter | BESCHREIBUNG |
|---|---|
| access_token | Das angeforderte Zugriffstoken. Die App kann dieses Token für die Authentifizierung mit der gesicherten Ressource (Web-API) verwenden. |
| token_type | Gibt den Wert des Tokentyps an. Der einzige von AD FS unterstützte Typ ist „Bearer“. |
| expires_in | Die Gültigkeitsdauer des Zugriffstokens (in Sekunden). |
| refresh_token | Ein Aktualisierungstoken von OAuth 2.0. Die App kann dieses Token verwenden, um nach Ablauf der aktuellen Zugriffstoken weitere Zugriffstoken zu erhalten. Refresh_token sind langlebig und können verwendet werden, um den Zugriff auf Ressourcen über längere Zeiträume zu erhalten. |
| refresh_token_expires_in | Die Gültigkeitsdauer des Aktualisierungstokens (in Sekunden). |
| id_token | Ein JSON-Webtoken (JWT). Die App kann die Segmente dieses Tokens entschlüsseln, um Informationen über den Benutzer, der sich angemeldet hat, anzufordern. Die App kann die Werte zwischenspeichern und anzeigen, aber sie sollte sich nicht auf sie verlassen, wenn es um Autorisierung oder Sicherheitsbegrenzungen geht. |
Verwenden des Zugriffstokens
GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Gewährungsflow für Aktualisierungstoken
Access_token sind kurzlebig und sie müssen nach Ablauf der Gültigkeitsdauer aktualisiert werden, um weiterhin auf Ressourcen zugreifen zu können. Zu diesem Zweck können Sie eine weitere POST-Anforderung an den /token-Endpunkt übermitteln und dieses Mal das refresh_token anstelle des Codes bereitstellen. Aktualisierungstoken sind für alle Berechtigungen gültig, für die dein Client bereits ein Zugriffstoken erhalten hat.
Für Aktualisierungstoken ist keine Lebensdauer festgelegt. Normalerweise verfügen Aktualisierungstoken über relativ lange Lebensdauern. In einigen Fällen laufen Aktualisierungstoken aber ab, werden widerrufen oder verfügen nicht über ausreichende Berechtigungen für die gewünschte Aktion. Von Ihrer Anwendung müssen Fehler, die vom Tokenausstellungs-Endpunkt zurückgegeben werden, erwartet und richtig behandelt werden.
Aktualisierungstoken werden zwar nicht widerrufen, wenn sie zum Abrufen neuer Zugriffstoken verwendet werden, aber Sie sollten dennoch das alte Aktualisierungstoken verwerfen. Die OAuth 2.0-Spezifikation besagt Folgendes: „Der Autorisierungsserver KANN ein neues Aktualisierungstoken ausgeben. In diesem Fall MUSS der Client das alte Aktualisierungstoken verwerfen und durch das neue Aktualisierungstoken ersetzen. Der Autorisierungsserver KANN das alte Aktualisierungstoken widerrufen, nachdem ein neues Aktualisierungstoken für den Client ausgestellt wurde.“ AD FS stellt Aktualisierungstoken aus, wenn die Lebensdauer des neuen Aktualisierungstokens die des vorherigen Aktualisierungstokens übersteigt. Weitere Informationen zur Lebensdauer von Aktualisierungstoken in AD FS findest du unter AD FS: Einstellungen für einmaliges Anmelden.
// Line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for confidential clients (web apps)
| Parameter | erforderlich/optional | BESCHREIBUNG |
|---|---|---|
| client_id | Erforderlich | Die Anwendungs-ID (Client), die Ihrer App von AD FS zugewiesen wurde. |
| grant_type | Erforderlich | Muss der refresh_token für diesen Abschnitt des Autorisierungscodeflusses sein. |
| resource | Optional | Die URL Ihrer Web-API.Hinweis: Wenn Sie die MSAL-Clientbibliothek verwenden, wird der Ressourcenparameter nicht gesendet. Stattdessen wird die Ressourcen-URL als Teil des Bereichsparameters gesendet: scope = [resource url]//[scope values e.g., openid]Wenn die Ressource nicht hier oder im Bereich übergeben wird, verwenden AD FS eine Standardressource (urn:microsoft:userinfo). Ressourcenrichtlinien für Benutzerinformationen wie MFA-, Ausstellungs- oder Autorisierungsrichtlinien können nicht angepasst werden. |
| scope | Optional | Eine durch Leerzeichen getrennte Liste von Bereichen. |
| refresh_token | Erforderlich | Das refresh_token, das du im zweiten Abschnitt des Flows abgerufen hast. |
| client_secret | Erforderlich für Web-Apps | Der geheime App-Schlüssel, den Sie im App-Registrierungsportal für Ihre App erstellt haben. Er sollte nicht in einer nativen App verwendet werden, da geheime Clientschlüssel nicht zuverlässig auf Geräten gespeichert werden können. Er ist erforderlich für Web-Apps und Web-APIs, die die Möglichkeit haben, den geheimen Client-Schlüssel sicher auf dem Server zu speichern. Diese Apps können auch eine schlüsselbasierte Authentifizierung verwenden, indem sie ein JWT signieren und dies als client_assertion-Parameter hinzufügen. |
Erfolgreiche Antwort
Eine erfolgreiche Token-Antwort sieht wie folgt aus:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| Parameter | BESCHREIBUNG |
|---|---|
| access_token | Das angeforderte Zugriffstoken. Die App kann dieses Token für die Authentifizierung mit der gesicherten Ressource (z. B. einer Web-API) verwenden. |
| token_type | Gibt den Wert des Tokentyps an. Der einzige von AD FS unterstützte Typ ist „Bearer“. |
| expires_in | Die Gültigkeitsdauer des Zugriffstokens (in Sekunden). |
| scope | Die Bereiche, für die das access_token gültig ist. |
| refresh_token | Ein Aktualisierungstoken von OAuth 2.0. Die App kann dieses Token verwenden, um nach Ablauf der aktuellen Zugriffstoken weitere Zugriffstoken zu erhalten. Refresh_token sind langlebig und können verwendet werden, um den Zugriff auf Ressourcen über längere Zeiträume zu erhalten. |
| refresh_token_expires_in | Die Gültigkeitsdauer des Aktualisierungstokens (in Sekunden). |
| id_token | Ein JSON-Webtoken (JWT). Die App kann die Segmente dieses Tokens entschlüsseln, um Informationen über den Benutzer, der sich angemeldet hat, anzufordern. Die App kann die Werte zwischenspeichern und anzeigen, aber sie sollte sich nicht auf sie verlassen, wenn es um Autorisierung oder Sicherheitsbegrenzungen geht. |
On-Behalf-Of-Flow
Hinweis
Anstelle eines Upgrades auf die neueste Version von AD FS empfiehlt Microsoft dringend die Migration zu Microsoft Entra ID. Weitere Informationen zum On-Behalf-Of-Flow in Microsoft Entra ID finden Sie unter Microsoft Identity Platform und der On-Behalf-Of-Fluss von OAuth2.0.
Der OAuth 2.0 On-Behalf-Of-Flow (OBO) dient dem Anwendungsfall, dass eine Anwendung eine Dienst-/Web-API aufruft, die wiederum eine andere Dienst-/Web-API aufrufen muss. Die Idee besteht darin, die delegierte Benutzeridentität und die Berechtigungen durch die Anforderungskette zu verteilen. Damit der Dienst der mittleren Ebene authentifizierte Anforderungen an den Downstreamdienst stellen kann, muss er im Auftrag des Benutzers ein Zugriffstoken vom AD FS sichern.
Protokolldiagramm
Nehmen wir an, dass der Benutzer bei einer Anwendung mit dem im vorherigen Abschnitt beschriebenen Genehmigungsflow für den OAuth 2.0-Autorisierungscode authentifiziert wurde. Zu diesem Zeitpunkt verfügt die Anwendung über ein Zugriffstoken für API A (Token A) mit den Ansprüchen und der Einwilligung des Benutzers für den Zugriff auf die Web-API der mittleren Ebene (API A). Stelle sicher, dass der Client im Token den Bereich „user_impersonation“ anfordert. Jetzt muss API A eine authentifizierte Anforderung an die Downstream-Web-API (API B) stellen.
Die folgenden Schritte bilden den OBO-Flow und werden mithilfe des folgenden Diagramms erläutert.
- Die Clientanwendung stellt eine Anforderung an API A mit Token A. Hinweis: Stellen Sie bei der Konfiguration des OBO-Flows in AD FS sicher, dass in der Anforderung der Bereich
user_impersonationausgewählt ist und der Client den Bereichuser_impersonationanfordert. - API A authentifiziert sich gegenüber dem AD FS-Tokenausstellungsendpunkt und fordert ein Token für den Zugriff auf API B an. Hinweis: Stellen Sie bei der Konfiguration dieses Flows in AD FS sicher, dass API A auch als Serveranwendung registriert wird. Der Wert von „clientID“ stimmt hierbei mit der Ressourcen-ID in API A überein.
- Der AD FS-Tokenausstellungsendpunkt überprüft die Anmeldeinformationen von API A mit Token A und stellt das Zugriffstoken für API B (Token B) aus.
- Token B wird im Autorisierungsheader der Anforderung für API B festgelegt.
- Daten von der gesicherten Ressource werden von API B zurückgegeben.
Anforderung von Zugriffstoken zwischen Diensten
Um ein Zugriffstoken anzufordern, führe einen HTTP POST-Vorgang an den AD FS-Tokenendpunkt mit den folgenden Parametern aus.
Erster Fall: Anforderung eines Zugriffstokens mit einem gemeinsamen Geheimnis
Für ein gemeinsames Geheimnisses enthält eine Anforderung von Zugriffstoken zwischen Diensten die folgenden Parameter:
| Parameter | erforderlich/optional | Beschreibung |
|---|---|---|
| grant_type | Erforderlich | Der Typ der Tokenanforderung. Bei einer Anforderung mit einem JWT muss der Wert „urn:ietf:params:oauth:grant-type:jwt-bearer“ sein. |
| client_id | Erforderlich | Die Client-ID, die du bei der Registrierung deiner ersten Web-API als Server-App (App auf mittlerer Ebene) konfigurierst. Sie sollte mit der Ressourcen-ID übereinstimmen, die im ersten Abschnitt verwendet wird, d. h. die URL der ersten Web-API. |
| client_secret | Erforderlich | Das Anwendungsgeheimnis, das Sie bei der Registrierung der Server-App in AD FS erstellt haben. |
| assertion | Erforderlich | Der Wert des in der Anforderung verwendeten Tokens. |
| requested_token_use | Erforderlich | Gibt an, wie die Anforderung verarbeitet werden soll. Im OBO-Flow muss der Wert auf „on_behalf_of“ festgelegt werden. |
| resource | Erforderlich | Die Ressourcen-ID, die bei der Registrierung der ersten Web-API als Server-App (App auf mittlerer Ebene) bereitgestellt wurde. Die Ressourcen-ID sollte der URL der zweiten Web-API entsprechen, die von der App auf mittlerer Ebene im Auftrag des Clients aufgerufen wird. |
| scope | Optional | Eine durch Leerzeichen getrennte Liste von Bereichen für die Tokenanforderung. |
Beispiel
Der folgende HTTP POST fordert ein Zugriffstoken und ein Aktualisierungstoken an.
//line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=https://webapi.com/
&client_secret=BYyVnAt56JpLwUcyo47XODd
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope=openid
Zweiter Fall: Anforderung eines Zugriffstokens mit einem Zertifikat
Eine Dienst-zu-Dienst-Zugriffstokenanforderung mit einem Zertifikat enthält die folgenden Parameter:
| Parameter | Erforderlich/optional | Beschreibung |
|---|---|---|
| grant_type | Erforderlich | Der Typ der Tokenanforderung. Bei einer Anforderung mit einem JWT muss der Wert „urn:ietf:params:oauth:grant-type:jwt-bearer“ sein. |
| client_id | Erforderlich | Die Client-ID, die du bei der Registrierung deiner ersten Web-API als Server-App (App auf mittlerer Ebene) konfigurierst. Sie sollte mit der Ressourcen-ID übereinstimmen, die im ersten Abschnitt verwendet wird, d. h. die URL der ersten Web-API. |
| client_assertion_type | Erforderlich | Der Wert muss „urn:ietf:params:oauth:client-assertion-type:jwt-bearer“ lauten. |
| client_assertion | required | Eine Assertion (ein JSON-Webtoken), die du mit dem Zertifikat, das als Berechtigungsnachweis für deine Anwendung registriert wurde, erstellen und signieren musst. |
| assertion | Erforderlich | Der Wert des in der Anforderung verwendeten Tokens. |
| requested_token_use | Erforderlich | Gibt an, wie die Anforderung verarbeitet werden soll. Im OBO-Flow muss der Wert auf „on_behalf_of“ festgelegt werden. |
| resource | Erforderlich | Die Ressourcen-ID, die bei der Registrierung der ersten Web-API als Server-App (App auf mittlerer Ebene) bereitgestellt wurde. Die Ressourcen-ID sollte der URL der zweiten Web-API entsprechen, die von der App auf mittlerer Ebene im Auftrag des Clients aufgerufen wird. |
| scope | Optional | Eine durch Leerzeichen getrennte Liste von Bereichen für die Tokenanforderung. |
Beachten Sie, dass die Parameter nahezu identisch sind. Dieses Beispiel ähnelt der Anforderung des gemeinsamen Geheimnisses, mit dem Unterschied, dass der Parameter „client_secret“ durch zwei Parameter ersetzt wird: „client_assertion_type“ und „client_assertion“.
Beispiel
Der folgende HTTP POST-Vorgang fordert ein Zugriffstoken für die Web-API mit einem Zertifikat an.
// line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id= https://webapi.com/
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNS…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope= openid
Zugriffstokenantwort zwischen Diensten
Eine erfolgreiche Antwort enthält eine JSON OAuth 2.0-Antwort mit den folgenden Parametern.
| Parameter | BESCHREIBUNG |
|---|---|
| token_type | Gibt den Wert des Tokentyps an. Der einzige von AD FS unterstützte Typ ist „Bearer“. |
| scope | Der durch das Token gewährte Zugriffsbereich. |
| expires_in | Die Zeitspanne in Sekunden, in der das Zugriffstoken gültig ist. |
| access_token | Das angeforderte Zugriffstoken. Der aufrufende Dienst kann dieses Token verwenden, um die Authentifizierung für den empfangenden Dienst durchzuführen. |
| id_token | Ein JSON-Webtoken (JWT). Die App kann die Segmente dieses Tokens entschlüsseln, um Informationen über den Benutzer, der sich angemeldet hat, anzufordern. Die App kann die Werte zwischenspeichern und anzeigen, aber sie sollte sich nicht auf sie verlassen, wenn es um Autorisierung oder Sicherheitsbegrenzungen geht. |
| refresh_token | Das Aktualisierungstoken für das angeforderte Zugriffstoken. Der aufrufende Dienst kann dieses Token verwenden, um nach Ablauf des aktuellen Zugriffstokens ein weiteres Zugriffstoken anzufordern. |
| Refresh_token_expires_in | Die Zeitspanne in Sekunden, in der das Aktualisierungstoken gültig ist. |
Beispiel für eine Erfolgsantwort
Das folgende Beispiel zeigt eine Erfolgsantwort auf eine Anforderung nach einem Zugriffstoken für die Web-API.
{
"token_type": "Bearer",
"scope": openid,
"expires_in": 3269,
"access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1t"
"id_token": "aWRfdG9rZW49ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKU1V6STFOa"
"refresh_token": "OAQABAAAAAABnfiG…"
"refresh_token_expires_in": 28800,
}
Verwenden Sie das Zugriffstoken, um auf die gesicherte Ressource zuzugreifen. Jetzt kann der Dienst auf mittlerer Ebene das im vorherigen Antwortbeispiel abgerufene Token verwenden, um authentifizierte Anforderungen an die Downstream-Web-API zu stellen, indem das Token im Autorisierungsheader festgelegt wird.
Beispiel
GET /v1.0/me HTTP/1.1
Host: https://secondwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQ…
Gewährungsflow für Clientanmeldeinformationen
Hinweis
Anstelle eines Upgrades auf die neueste Version von AD FS empfiehlt Microsoft dringend die Migration zu Microsoft Entra ID. Weitere Informationen zum Genehmigungsflow für Clientanmeldeinformationen in Microsoft Entra ID finden Sie unter Microsoft Identity Platform und der Fluss von OAuth 2.0-Clientanmeldeinformationen.
Sie können die in RFC 6749 angegebene Genehmigung der OAuth 2.0-Clientanmeldeinformationen verwenden, um anhand der Identität einer Anwendung auf im Web gehostete Ressourcen zuzugreifen. Diese Art der Gewährung wird häufig für Interaktionen zwischen Servern verwendet, die ohne Benutzereingriff im Hintergrund ausgeführt werden müssen. Diese Anwendungstypen werden oft als Daemons oder Dienstkonten bezeichnet.
Beim Fluss zur Gewährung von OAuth 2.0-Clientanmeldeinformationen kann ein Webdienst (ein vertraulicher Client) seine eigenen Anmeldeinformationen zum Authentifizieren verwenden, wenn ein anderer Webdienst aufgerufen wird, anstatt die Identität eines Benutzers anzunehmen. In diesem Szenario ist der Client normalerweise ein Webdienst der mittleren Ebene, ein Daemondienst oder eine Website. Für ein höheres Maß an Sicherheit erlaubt der AD FS dem aufrufenden Dienst auch die Verwendung eines Zertifikats (anstelle eines gemeinsamen Geheimnisses) als Anmeldeinformation.
Protokolldiagramm
Das folgende Diagramm zeigt den Gewährungsflow für Clientanmeldeinformationen.
Anfordern eines Tokens
Sende eine POST-Anforderung an den AD FS-Endpunkt „/token“, um ein Token unter Verwendung der Clientanmeldeinformationen abzurufen:
Erster Fall: Anforderung eines Zugriffstokens mit einem gemeinsamen Geheimnis
POST /adfs/oauth2/token HTTP/1.1
//Line breaks for clarity
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
| Parameter | erforderlich/optional | BESCHREIBUNG |
|---|---|---|
| client_id | Erforderlich | Die Anwendungs-ID (Client), die Ihrer App von AD FS zugewiesen wurde. |
| scope | Optional | Eine durch Leerzeichen getrennte Liste von Bereichen, denen die Benutzer*innen zustimmen sollen. |
| client_secret | Erforderlich | Der geheime Clientschlüssel, den Sie im App-Registrierungsportal für Ihre App generiert haben. Der geheime Clientschlüssel muss vor dem Senden mit einer URL codiert werden. |
| grant_type | Erforderlich | Muss auf client_credentials festgelegt sein. |
Zweiter Fall: Zugriffstokenanforderung mit einem Zertifikat
POST /adfs/oauth2/token HTTP/1.1
// Line breaks for clarity
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
&client_id=97e0a5b7-d745-40b6-94fe-5f77d35c6e05
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
| Parameter | erforderlich/optional | Beschreibung |
|---|---|---|
| client_assertion_type | Erforderlich | Der Wert muss auf „urn:ietf:params:oauth:client-assertion-type:jwt-bearer“ festgelegt sein. |
| client_assertion | required | Eine Assertion (ein JSON-Webtoken), die du mit dem Zertifikat, das als Berechtigungsnachweis für deine Anwendung registriert wurde, erstellen und signieren musst. |
| grant_type | Erforderlich | Muss auf client_credentials festgelegt sein. |
| client_id | Optional | Die Anwendungs-ID (Client), die Ihrer App von AD FS zugewiesen wurde. Sie ist ein Teil von client_assertion, sodass sie hier nicht übergeben werden muss. |
| scope | Optional | Eine durch Leerzeichen getrennte Liste von Bereichen, denen die Benutzer*innen zustimmen sollen. |
Verwenden eines Tokens
Nachdem du jetzt ein Token abgerufen hast, stelle die Anforderungen an die Ressource mit dem Token. Wenn das Token abläuft, wiederholst du die Anforderung an den „/token“-Endpunkt, um ein neues Zugriffstoken zu erhalten.
GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Gewährungsflow für Kennwortanmeldeinformationen des Ressourcenbesitzers (nicht empfohlen)
Hinweis
Anstelle eines Upgrades auf die neueste Version von AD FS empfiehlt Microsoft dringend die Migration zu Microsoft Entra ID. Weitere Informationen zum Genehmigungsflow für Kennwortanmeldeinformationen von Ressourcenbesitzer*innen in Microsoft Entra ID finden Sie unter Microsoft Identity Platform und OAuth 2.0-Kennwortanmeldeinformationen des Ressourcenbesitzers.
Die Gewährung von Ressourcenbesitzer-Kennwortanmeldeinformationen ermöglicht es einer Anwendung, den Benutzer durch direkte Verarbeitung seines Kennworts anzumelden. Der Flow für Kennwortanmeldeinformationen des Ressourcenbesitzers erfordert ein hohes Maß an Vertrauen und potenzieller Benutzergefährdung, und du solltest diesen Flow nur verwenden, wenn andere, sicherere Flows nicht verwendet werden können.
Protokolldiagramm
Dieses Diagramm zeigt den ROPC-Flow:
Autorisierungsanforderung
Der ROPC-Flow ist eine einzelne Anforderung. Er sendet die Client-ID und die Anmeldeinformationen des Benutzers an den IDP und empfängt dann im Gegenzug entsprechende Token. Der Client muss vorher die E-Mail-Adresse (UPN) und das Kennwort des Benutzers anfordern. Unmittelbar nach einer erfolgreichen Anforderung muss der Client die Anmeldeinformationen des Benutzers sicher aus dem Arbeitsspeicher freigeben. Er darf sie niemals speichern.
// Line breaks and spaces are for legibility only.
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope= openid
&username=myusername@contoso.com
&password=SuperS3cret
&grant_type=password
| Parameter | erforderlich/optional | BESCHREIBUNG |
|---|---|---|
| client_id | Erforderlich | Client-ID |
| grant_type | Erforderlich | Muss auf „password“ festgelegt werden. |
| username | Erforderlich | Dies ist die E-Mail-Adresse des Benutzers. |
| password | Erforderlich | Das Kennwort des Benutzers. |
| scope | Optional | Eine durch Leerzeichen getrennte Liste von Bereichen. |
Erfolgreiche Authentifizierungsantwort
Das folgende Beispiel stellt eine erfolgreiche Tokenantwort dar:
{
"token_type": "Bearer",
"scope": "openid",
"expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDR..."
}
| Parameter | BESCHREIBUNG |
|---|---|
| token_type | Immer auf „Bearer“ festgelegt. |
| scope | Wenn ein Zugriffstoken zurückgegeben wurde, listet dieser Parameter die Bereiche auf, für die das Zugriffstoken gültig ist. |
| expires_in | Anzahl der Sekunden, für die das enthaltene Zugriffstoken gültig ist. |
| access_token | Ausgestellt für die angeforderten Bereiche. |
| id_token | Ein JSON-Webtoken (JWT). Die App kann die Segmente dieses Tokens entschlüsseln, um Informationen über den Benutzer, der sich angemeldet hat, anzufordern. Die App kann die Werte zwischenspeichern und anzeigen, aber sie sollte sich nicht auf sie verlassen, wenn es um Autorisierung oder Sicherheitsbegrenzungen geht. |
| refresh_token_expires_in | Anzahl der Sekunden, für die das enthaltene Aktualisierungstoken gültig ist. |
| refresh_token | Wird ausgegeben, wenn der ursprüngliche Bereichsparameter offline_access enthalten hat. |
Sie können anhand des Aktualisierungstokens neue Zugriffstoken abrufen und Token aktualisieren, indem Sie denselben Flow verwenden, der in diesem Artikel im Abschnitt über die Genehmigung von Authentifizierungscode beschrieben wird.
Gerätecodefluss
Hinweis
Anstelle eines Upgrades auf die neueste Version von AD FS empfiehlt Microsoft dringend die Migration zu Microsoft Entra ID. Weitere Informationen zum Gerätecodefluss in Microsoft Entra ID finden Sie unter Microsoft Identity Platform und der OAuth 2.0-Flow für die Geräteautorisierungsgenehmigung.
Durch die Gewährung von Gerätecode kann sich der Benutzer an Geräten mit beschränkten Eingabemöglichkeiten anmelden, z. B. Smart-TV, IoT-Gerät oder Drucker. Um diesen Flow zu ermöglichen, lässt das Gerät den Benutzer eine Webseite in seinem Browser auf einem anderen Gerät besuchen, um sich anzumelden. Nach der Anmeldung des Benutzers ist das Gerät in der Lage, Zugriffstoken zu erhalten und die Token bei Bedarf zu aktualisieren.
Protokolldiagramm
Der gesamte Gerätecodeflow sieht ähnlich wie im nächsten Diagramm aus. Wir beschreiben die einzelnen Schritte weiter unten in diesem Artikel.
Geräteautorisierungsanforderung
Der Client muss zuerst den Authentifizierungsserver auf einen Geräte- und Benutzercode überprüfen, die zum Initiieren der Authentifizierung verwendet werden. Der Client erfasst diese Anforderung vom /devicecode-Endpunkt. In diese Anforderung sollte der Client außerdem die Berechtigungen aufnehmen, die er vom Benutzer erhalten muss. Ab dem Moment, in dem diese Anforderung gesendet wird, haben Benutzer*innen nur 15 Minuten Zeit, um sich anzumelden (der übliche Wert für expires_in). Daher sollte diese Anforderung erst dann gestellt werden, wenn Benutzer*innen signalisiert haben, dass sie zur Anmeldung bereit sind.
// Line breaks are for legibility only.
POST https://adfs.contoso.com/adfs/oauth2/devicecode
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
scope=openid
| Parameter | Condition | BESCHREIBUNG |
|---|---|---|
| client_id | Erforderlich | Die Anwendungs-ID (Client), die Ihrer App von AD FS zugewiesen wurde. |
| scope | Optional | Eine durch Leerzeichen getrennte Liste von Bereichen. |
Geräteautorisierungsantwort
Eine erfolgreiche Antwort ist ein JSON-Objekt mit den erforderlichen Informationen, die den Benutzer*innen die Anmeldung ermöglichen.
| Parameter | Beschreibung |
|---|---|
| device_code | Eine lange Zeichenfolge, die zur Überprüfung der Sitzung zwischen dem Client und dem Autorisierungsserver verwendet wird. Der Client verwendet diesen Parameter, um das Zugriffstoken vom Autorisierungsserver anzufordern. |
| user_code | Eine kurze, dem Benutzer angezeigte Zeichenfolge, die zur Identifizierung der Sitzung auf einem sekundären Gerät verwendet wird. |
| verification_uri | Der URI, zu dem Benutzer*innen mit dem user_code wechseln sollten, um sich anzumelden. |
| verification_uri_complete | Der URI, zu dem Benutzer*innen mit dem user_code wechseln sollten, um sich anzumelden. Dieser ist mit user_code vorab ausgefüllt, sodass Benutzer*innen keinen user_code eingeben müssen. |
| expires_in | Die Anzahl der Sekunden, bevor device_code und user_code ablaufen. |
| interval | Die Anzahl der Sekunden, die der Client zwischen den Abfrageanforderungen warten soll. |
| message | Eine von Menschen lesbare Zeichenfolge mit Anweisungen für den Benutzer. Dieser Wert kann lokalisiert werden, indem der Anforderung ein Abfrageparameter im Format „?mkt=xx-XX“ hinzugefügt wird. Setzen Sie dabei den entsprechenden Sprachkulturcode ein. |
Authentifizieren des Benutzers
Nachdem der Client user_code und verification_uri erhalten hat, zeigt er diese an und weist die Benutzer*innen an, sich über ein Mobiltelefon oder einen PC-Browser anzumelden. Zusätzlich kann der Client einen QR-Code oder einen ähnlichen Mechanismus zum Anzeigen von verification_uri_complete verwenden, der den Schritt zur Eingabe von user_code für die Benutzer*innen übernimmt. Während Benutzer*innen sich beim verification_uri authentifizieren, sollte der Client den /token-Endpunkt mit dem device_code nach dem angeforderten Token abfragen.
POST https://adfs.contoso.com /adfs/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type: urn:ietf:params:oauth:grant-type:device_code
client_id: 6731de76-14a6-49ae-97bc-6eba6914391e
device_code: GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8
| Parameter | Erforderlich | BESCHREIBUNG |
|---|---|---|
| grant_type | Erforderlich | Muss „urn:ietf:params:oauth:grant-type:device_code“ lauten. |
| client_id | Erforderlich | Muss mit der in der ursprünglichen Anforderung verwendeten client_id übereinstimmen. |
| code | Erforderlich | Der in der Geräteautorisierungsanforderung zurückgegebene device_code. |
Erfolgreiche Authentifizierungsantwort
Eine erfolgreiche Token-Antwort sieht wie folgt aus:
| Parameter | BESCHREIBUNG |
|---|---|
| token_type | Lautet immer „Bearer“. |
| scope | Wenn ein Zugriffstoken zurückgegeben wurde, werden darin die Bereiche aufgelistet, für die das Zugriffstoken gültig ist. |
| expires_in | Anzahl der Sekunden, bevor das enthaltene Zugriffstoken gültig ist. |
| access_token | Ausgestellt für die angeforderten Bereiche. |
| id_token | Wird ausgegeben, wenn der ursprüngliche Bereichsparameter den openid-Bereich enthielt. |
| refresh_token | Wird ausgegeben, wenn der ursprüngliche Bereichsparameter offline_access enthalten hat. |
| refresh_token_expires_in | Anzahl der Sekunden, bevor das enthaltene Aktualisierungstoken gültig ist. |
Verwandte Themen
Die vollständige Liste der Artikel mit exemplarischen Vorgehensweisen ist in AD FS-Entwicklung verfügbar, worin schrittweise Anweisungen zur Verwendung der entsprechenden Flows bereitgestellt werden.