Microsoft Identity Platform und der On-Behalf-Of-Fluss von OAuth2.0
Der On-Behalf-Of-Flow (OBO) beschreibt das Szenario einer Web-API, in der eine andere Identität als die eigene verwendet wird, um eine andere Web-API aufzurufen. In OAuth wird dies als Delegation bezeichnet und zielt darauf ab, die Identität und die Berechtigungen eines Benutzers durch die Anforderungskette zu leiten.
Damit der Dienst auf der mittleren Ebene Authentifizierungsanforderungen an den Downstreamdienst stellen kann, muss ein Zugriffstoken der Microsoft Identity Platform gesichert werden. Es werden nur delegierte Bereiche und keine Anwendungsrollen verwendet. Rollen bleiben an den Prinzipal (den Benutzer) angefügt – nie an der Anwendung, die im Auftrag des Benutzers ausgeführt wird. Dies geschieht, um zu verhindern, dass der Benutzer Berechtigungen für Ressourcen erhält, auf die er keinen Zugriff haben sollte.
In diesem Artikel wird beschrieben, wie Sie direkt mit dem Protokoll in Ihrer Anwendung programmieren. Es wird stattdessen empfohlen, ggf. die unterstützten Microsoft Authentication Libraries (MSAL) zu verwenden, um Token zu erhalten und gesicherte Web-APIs aufzurufen. Weitere Informationen finden Sie unter Beispiel-Apps, die MSAL verwenden.
Clienteinschränkungen
Wenn ein Dienstprinzipal ein Nur-App-Token angefordert und an eine API gesendet hat, würde diese API ein Token austauschen, das nicht den ursprünglichen Dienstprinzipal darstellt. Dies liegt daran, dass der OBO-Flow nur für Benutzerprinzipale funktioniert. Stattdessen muss der Clientanmeldeinformationenflow verwendet werden, um ein Nur-App-Token abzurufen. Single-Page-Webanwendungen (SPAs) müssen ein Zugriffstoken an einen vertraulichen Client der mittleren Ebene übergeben, um stattdessen OBO-Flows auszuführen.
Wenn ein Client den impliziten Flow verwendet, um ein „id_token“ abzurufen, und auch über Platzhalter in einer Antwort-URL verfügt, kann das „id_token“ nicht für einen OBO-Flow verwendet werden. Eine Wildcard ist eine URL, die mit einem *-Zeichen endet. Wenn https://myapp.com/* beispielsweise die Antwort-URL ist, kann das id_token nicht verwendet werden, da es nicht spezifisch genug ist, um den Client zu identifizieren. Dies würde verhindern, dass das Token ausgestellt wird. Allerdings kann ein vertraulicher Client Zugriffstoken einlösen, die über den Flow für implizite Gewährung erworben wurden, selbst wenn der initiierende Client eine Antwort-URL mit Platzhaltern registriert hat. Dies liegt daran, dass der vertrauliche Client den Client identifizieren kann, der das Zugriffstoken erworben hat. Der vertrauliche Client kann das Zugriffstoken dann verwenden, um ein neues Zugriffstoken für die Downstream-API abzurufen.
Darüber hinaus können Anwendungen mit benutzerdefinierten Signaturschlüsseln nicht als APIs der mittleren Ebene im OBO-Flow verwendet werden. Dazu gehören Unternehmensanwendungen, die für einmaliges Anmelden konfiguriert sind. Wenn die API der mittleren Ebene einen benutzerdefinierten Signaturschlüssel verwendet, überprüft die Downstream-API die Signatur des Zugriffstokens nicht, das an sie übergeben wird. Dies führt zu einem Fehler, da Token, die mit einem vom Client gesteuerten Schlüssel signiert sind, nicht sicher akzeptiert werden können.
Protokolldiagramm
Angenommen, der Benutzer sich mit dem OAuth 2.0-Flow zum Erteilen eines Autorisierungscodes oder einem anderen Anmeldeflow in einer Anwendung authentifiziert. In diesem Fall verfügt die Anwendung über ein Zugriffstoken für API A (Token A), das die Benutzeransprüche und die Genehmigung für den Zugriff auf die Web-API der mittleren Ebene (API A) enthält. API A muss nun eine authentifizierte Anfrage an die nachgelagerte Web-API stellen (API B).
Die folgenden Schritte bilden den OBO-Flow und werden mithilfe des folgenden Diagramms erläutert.
- Die Clientanwendung stellt mit Token A eine Anforderung an die API A (mit dem Anspruch
audvon API A). - API A wird beim Tokenausstellungs-Endpunkt der Microsoft Identity Platform authentifiziert und fordert ein Token für den Zugriff auf API B an.
- Der Tokenausstellungs-Endpunkt von Microsoft Identity Platform überprüft neben Token A die Anmeldeinformationen von API A und stellt das Zugriffstoken für API B (Token B) für API A aus.
- Token B wird von API A im Autorisierungsheader der Anforderung auf API B festgelegt.
- Daten von der sicheren Ressource werden von API B an API A und dann an den Client zurückgegeben.
In diesem Szenario interagiert der Dienst auf der mittleren Ebene nicht mit dem Benutzer, um dessen Zustimmung für den Zugriff auf die nachgelagerte API zu erlangen. Aus diesem Grund muss die Zugriffsgewährung auf die nachgelagerte API zuvor als Teil des Genehmigungsschrittes während der Authentifizierung als Option angezeigt werden. Um zu erfahren, wie Sie dies in Ihrer App implementieren, lesen Sie Erhalten der Zustimmung für die Anwendung der mittleren Ebene.
Zugriffstokenanforderung auf der mittleren Ebene
Verwenden Sie zum Anfordern eines Zugriffstokens einen HTTP POST-Aufruf an das mandantenspezifischen Token der Microsoft Identity Platform unter Verwendung der folgenden Parameter:
https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
Warnung
Senden Sie Zugriffstoken, die für die mittlere Ebene ausgegeben wurden, NUR an die Zielgruppe, für die sie bestimmt sind. Für die mittlere Ebene ausgestellte Zugriffstoken sind ausschließlich für die Verwendung durch diese mittlere Ebene zur Kommunikation mit dem vorgesehenen Endpunkt der Zielgruppe vorgesehen.
Zu den Sicherheitsrisiken beim Weiterleiten von Zugriffstoken von einer Ressource der mittleren Ebene an einen Client (anstatt dass der Client selbst die Zugriffstoken erhält) gehören u. a.:
- Erhöhtes Risiko des Abfangens von Token über kompromittierte SSL/TLS-Kanäle
- Unfähigkeit, Szenarien der Tokenbindung und des bedingten Zugriffs zu erfüllen, die ein Step-up des Anspruchs erfordern (z. B. MFA, Anmeldehäufigkeit)
- Inkompatibilität mit vom Administrator konfigurierten gerätebasierten Richtlinien (z. B. Verwaltung mobiler Geräte, standortbasierte Richtlinien)
Es sind zwei Fälle denkbar – je nachdem, ob die Clientanwendung durch ein gemeinsames Geheimnis oder durch ein Zertifikat geschützt wird.
Erster Fall: Zugriffstokenanforderung mit einem gemeinsamen Geheimnis
Bei Verwendung eines gemeinsamen Geheimnisses enthält eine Dienst-zu-Dienst-Zugriffstokenanforderung die folgenden Parameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
grant_type |
Erforderlich | Der Typ der Tokenanforderung. Bei einer Anforderung mit JWT muss der Wert urn:ietf:params:oauth:grant-type:jwt-bearer sein. |
client_id |
Erforderlich | Die Anwendungs-ID (Client-ID), die Ihrer App auf der Seite „App-Registrierungen“ im Microsoft Entra Admin Center zugewiesen ist. |
client_secret |
Erforderlich | Der geheime Clientschlüssel, den Sie für Ihre App auf der Seite „App-Registrierungen“ im Microsoft Entra Admin Center generiert haben. Das Standardauthentifizierungsmuster der Bereitstellung von Anmeldeinformationen im Autorisierungsheader gemäß RFC 6749 wird ebenfalls unterstützt. |
assertion |
Erforderlich | Das Zugriffstoken, das an die API der mittleren Ebene gesendet wurde. Dieses Token muss über einen Zielgruppenanspruch (aud) der App verfügen, von der diese OBO-Anforderung stammt (durch das Feld client-id gekennzeichnete App). Anwendungen können kein Token für eine andere App einlösen. Wenn also beispielsweise ein Client ein für Microsoft Graph vorgesehenes Token an eine API sendet, kann die API dieses nicht mit OBO einlösen. Sie sollte stattdessen das Token zurückweisen. |
scope |
Erforderlich | Eine durch Leerzeichen getrennte Liste von Bereichen für die Tokenanforderung. Weitere Informationen finden Sie unter Bereiche. |
requested_token_use |
Erforderlich | Gibt an, wie die Anforderung verarbeitet werden soll. Im OBO-Fluss muss der Wert muss auf on_behalf_of festgelegt werden. |
Beispiel
Mit dem folgenden HTTP POST-Element wird ein Zugriffstoken und Aktualisierungstoken mit dem Bereich user.read für die Web-API https://graph.microsoft.com angefordert. Die Anforderung ist mit dem geheimen Clientschlüssel signiert und wird von einem vertraulichen Client erstellt.
//line breaks for legibility only
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=sampleCredentia1s
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiOiIyO{a lot of characters here}
&scope=https://graph.microsoft.com/user.read+offline_access
&requested_token_use=on_behalf_of
Zweiter Fall: Zugriffstokenanforderung mit einem Zertifikat
Eine Zugriffstokenanforderung zwischen Diensten mit einem Zertifikat enthält zusätzlich zu den Parametern aus dem vorherigen Beispiel die folgenden Parameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
grant_type |
Erforderlich | Typ der Tokenanforderung Bei einer Anforderung mit JWT muss der Wert urn:ietf:params:oauth:grant-type:jwt-bearer sein. |
client_id |
Erforderlich | Die Anwendungs-ID (Client-ID), die Ihrer App auf der Seite „App-Registrierungen“ im Microsoft Entra Admin Center zugewiesen ist. |
client_assertion_type |
Erforderlich | Der Wert muss urn:ietf:params:oauth:client-assertion-type:jwt-bearer sein. |
client_assertion |
Erforderlich | Eine Assertion (ein JSON-Webtoken), die Sie benötigen, um das Zertifikat, das Sie als Anmeldeinformationen für Ihre Anwendung registriert haben, zu erstellen und sich damit anzumelden. Informationen zum Registrieren Ihres Zertifikats sowie zum Format der Assertion finden Sie im Abschnitt Zertifikatanmeldeinformationen. |
assertion |
Erforderlich | Das Zugriffstoken, das an die API der mittleren Ebene gesendet wurde. Dieses Token muss über einen Zielgruppenanspruch (aud) der App verfügen, von der diese OBO-Anforderung stammt (durch das Feld client-id gekennzeichnete App). Anwendungen können kein Token für eine andere App einlösen. Wenn also beispielsweise ein Client ein für Microsoft Graph vorgesehenes Token an eine API sendet, kann die API dieses nicht mit OBO einlösen. Sie sollte stattdessen das Token zurückweisen. |
requested_token_use |
Erforderlich | Gibt an, wie die Anforderung verarbeitet werden soll. Im OBO-Fluss muss der Wert muss auf on_behalf_of festgelegt werden. |
scope |
Erforderlich | Eine durch Leerzeichen getrennte Liste von Bereichen für die Tokenanforderung. Weitere Informationen finden Sie unter Bereiche. |
Beachten Sie, dass die Parameter nahezu identisch mit den Parametern der Anforderung mit dem gemeinsamen geheimen Schlüssel sind. Einziger Unterschied: Anstelle des Parameters client_secret werden die beiden Parameter client_assertion_type und client_assertion verwendet. Der client_assertion_type-Parameter wird auf urn:ietf:params:oauth:client-assertion-type:jwt-bearer und der client_assertion-Parameter auf das JWT-Token festgelegt, das mit dem privaten Schlüssel des Zertifikats signiert ist.
Beispiel
Mit dem folgenden HTTP POST-Element wird ein Zugriffstoken mit dem Bereich user.read für die Web-API https://graph.microsoft.com mit einem Zertifikat angefordert. Die Anforderung ist mit dem geheimen Clientschlüssel signiert und wird von einem vertraulichen Client erstellt.
// line breaks for legibility only
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiO{a lot of characters here}
&requested_token_use=on_behalf_of
&scope=https://graph.microsoft.com/user.read+offline_access
Zugriffstokenantwort auf der mittleren Ebene
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. Microsoft Identity Platform unterstützt nur den Typ Bearer. Weitere Informationen zu Bearertoken finden Sie unter OAuth 2.0-Autorisierungsframework: Verwendung von Bearertoken (RFC 6750). |
scope |
Der durch das Token gewährte Zugriffsbereich. |
expires_in |
Gibt an, wie lange das Zugriffstoken in Sekunden 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. |
refresh_token |
Das Aktualisierungstoken für das angeforderte Zugriffstoken. Der aufrufende Dienst kann dieses Token verwenden, um nach Ablauf des aktuellen Zugriffstokens ein neues Zugriffstoken anzufordern. Das Aktualisierungstoken wird nur bereitgestellt, wenn der Bereich offline_access angefordert wurde. |
Beispiel für eine erfolgreiche Antwort
Das folgende Beispiel zeigt eine erfolgreiche Antwort auf eine Anforderung eines Zugriffstokens für die Web-API https://graph.microsoft.com. Die Antwort enthält ein Zugriffstoken sowie ein Aktualisierungstoken und wird mit dem privaten Schlüssel des Zertifikats signiert.
{
"token_type": "Bearer",
"scope": "https://graph.microsoft.com/user.read",
"expires_in": 3269,
"ext_expires_in": 0,
"access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQTZOVGFlN0NkV1c3UWZkQ0NDYy0tY0hGa18wZE50MVEtc2loVzRMd2RwQVZISGpnTVdQZ0tQeVJIaGlDbUN2NkdyMEpmYmRfY1RmMUFxU21TcFJkVXVydVJqX3Nqd0JoN211eHlBQSIsImFsZyI6IlJTMjU2IiwieDV0IjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIiwia2lkIjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIn0.eyJhdWQiOiJodHRwczovL2dyYXBoLm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaWF0IjoxNDkzOTMwMzA1LCJuYmYiOjE0OTM5MzAzMDUsImV4cCI6MTQ5MzkzMzg3NSwiYWNyIjoiMCIsImFpbyI6IkFTUUEyLzhEQUFBQU9KYnFFWlRNTnEyZFcxYXpKN1RZMDlYeDdOT29EMkJEUlRWMXJ3b2ZRc1k9IiwiYW1yIjpbInB3ZCJdLCJhcHBfZGlzcGxheW5hbWUiOiJUb2RvRG90bmV0T2JvIiwiYXBwaWQiOiIyODQ2ZjcxYi1hN2E0LTQ5ODctYmFiMy03NjAwMzViMmYzODkiLCJhcHBpZGFjciI6IjEiLCJmYW1pbHlfbmFtZSI6IkNhbnVtYWxsYSIsImdpdmVuX25hbWUiOiJOYXZ5YSIsImlwYWRkciI6IjE2Ny4yMjAuMC4xOTkiLCJuYW1lIjoiTmF2eWEgQ2FudW1hbGxhIiwib2lkIjoiZDVlOTc5YzctM2QyZC00MmFmLThmMzAtNzI3ZGQ0YzJkMzgzIiwib25wcmVtX3NpZCI6IlMtMS01LTIxLTIxMjc1MjExODQtMTYwNDAxMjkyMC0xODg3OTI3NTI3LTI2MTE4NDg0IiwicGxhdGYiOiIxNCIsInB1aWQiOiIxMDAzM0ZGRkEwNkQxN0M5Iiwic2NwIjoiVXNlci5SZWFkIiwic3ViIjoibWtMMHBiLXlpMXQ1ckRGd2JTZ1JvTWxrZE52b3UzSjNWNm84UFE3alVCRSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInVuaXF1ZV9uYW1lIjoibmFjYW51bWFAbWljcm9zb2Z0LmNvbSIsInVwbiI6Im5hY2FudW1hQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJWR1ItdmtEZlBFQ2M1dWFDaENRSkFBIiwidmVyIjoiMS4wIn0.cubh1L2VtruiiwF8ut1m9uNBmnUJeYx4x0G30F7CqSpzHj1Sv5DCgNZXyUz3pEiz77G8IfOF0_U5A_02k-xzwdYvtJUYGH3bFISzdqymiEGmdfCIRKl9KMeoo2llGv0ScCniIhr2U1yxTIkIpp092xcdaDt-2_2q_ql1Ha_HtjvTV1f9XR3t7_Id9bR5BqwVX5zPO7JMYDVhUZRx08eqZcC-F3wi0xd_5ND_mavMuxe2wrpF-EZviO3yg0QVRr59tE3AoWl8lSGpVc97vvRCnp4WVRk26jJhYXFPsdk4yWqOKZqzr3IFGyD08WizD_vPSrXcCPbZP3XWaoTUKZSNJg",
"refresh_token": "OAQABAAAAAABnfiG-mA6NTae7CdWW7QfdAALzDWjw6qSn4GUDfxWzJDZ6lk9qRw4An{a lot of characters here}"
}
Dieses Zugriffstoken ist ein Token mit v1.0-Formatierung für Microsoft Graph. Dies liegt daran, dass das Tokenformat auf der Ressource basiert, auf die zugegriffen wird, und nicht mit den Endpunkten in Zusammenhang steht, die für deren Anforderung verwendet werden. Microsoft Graph ist dafür eingerichtet, v1.0-Token zu akzeptieren. Microsoft Identity Platform generiert daher v1.0-Zugriffstoken, wenn ein Client Token für Microsoft Graph anfordert. Andere Apps können signalisieren, dass sie Token im v2.0- oder v1.0-Format oder sogar proprietäre oder verschlüsselte Tokenformate bevorzugen. Die Endpunkte der Versionen 1.0 und 2.0 können jedes beliebige Tokenformat ausgeben. Dadurch kann die Ressource immer das richtige Tokenformat abrufen, unabhängig davon, wie oder wo das Token vom Client angefordert wird.
Warnung
Versuchen Sie nicht, Token für eine API zu überprüfen oder zu lesen, die Sie nicht besitzen, einschließlich der Token in Ihrem Code in diesem Beispiel. Token für Microsoft-Dienste können ein spezielles Format verwenden, das nicht als JWT überprüft und auch für Consumerbenutzer (Microsoft-Konto) verschlüsselt werden kann. Das Lesen von Token ist zwar ein nützliches Debug- und Lerntool, aber integrieren Sie weder Abhängigkeiten davon in Ihren Code noch setzen Sie Einzelheiten über Token voraus, die nicht für eine von Ihnen kontrollierte API gelten.
Beispiel für eine fehlerhafte Antwort
Beim Versuch, ein Zugriffstoken für die Downstream-API abzurufen, gibt der Tokenendpunkt einen Fehler zurück, wenn bei dieser API eine Richtlinie für bedingten Zugriff (z. B. mehrstufige Authentifizierung) festgelegt ist. Der Dienst der mittleren Ebene zeigt diesen Fehler der Clientanwendung an, damit die Clientanwendung die entsprechende Benutzerinteraktion bereitstellen kann, um die Richtlinie für bedingten Zugriff zu erfüllen.
Um diesen Fehler wieder auf dem Client anzuzeigen, antwortet der Dienst der mittleren Ebene mit „HTTP 401 Nicht autorisiert“ und mit einem WWW-Authenticate HTTP-Header, der den Fehler und die Anspruchsaufforderung enthält. Der Client muss diesen Header analysieren und ein neues Token vom Tokenaussteller abrufen, indem er die Anspruchsaufforderun angibt, falls vorhanden. Clients sollten nicht erneut versuchen, mithilfe eines zwischengespeicherten Zugriffstokens auf den Dienst der mittleren Ebene zuzugreifen.
{
"error":"interaction_required",
"error_description":"AADSTS50079: Due to a configuration change made by your administrator, or because you moved to a new location, you must enroll in multifactor authentication to access 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2017-05-01 22:43:20Z",
"error_codes":[50079],
"timestamp":"2017-05-01 22:43:20Z",
"trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd",
"claims":"{\"access_token\":{\"polids\":{\"essential\":true,\"values\":[\"9ab03e19-ed42-4168-b6b7-7001fb3e933a\"]}}}"
}
Verwenden des Zugriffstokens für den Zugriff auf die gesicherte Ressource
Der Dienst der mittleren Ebene kann nun mit dem zuvor erhaltenen Token bei der nachgelagerte Web-API authentifizierte Anforderungen stellen. Hierfür wird das Token in den Authorization-Header eingetragen.
Beispiel
GET /v1.0/me HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
SAML-Assertionen, die mit einem OAuth 2.0-OBO-Fluss abgerufen wurden
Einige OAuth-basierte Webdienste benötigen Zugriff auf andere Webdienst-APIs, die SAML-Assertionen in nicht interaktiven Flüssen akzeptieren. Microsoft Entra ID kann es eine SAML-Assertion als Antwort auf einen Im-Namen-von-Fluss mit einem SAML-basierten Webdienst als Zielressource bereitstellen.
Dies ist eine nicht standardmäßige Erweiterung für den OAuth 2.0-Im-Namen-von-Fluss, der einer OAuth2-basierten Anwendung Zugriff auf Webdienst-API-Endpunkte ermöglicht, die SAML-Token nutzen.
Tipp
Wenn Sie einen geschützten SAML-Webdienst über eine Front-End-Anwendung aufrufen, können Sie einfach die API aufrufen und einen normalen interaktiven Authentifizierungsfluss initiieren, der die vorhandene Sitzung eines Benutzers verwendet. Sie müssen lediglich einen OBO-Fluss verwenden, wenn ein Dienst-zu-Dienst-Aufruf ein SAML-Token für die Bereitstellung des Benutzerkontexts erfordert.
Abrufen eines SAML-Tokens mithilfe einer OBO-Anforderung mit einem gemeinsamen Geheimnis
Eine Dienst-zu-Dienst-Anforderung für eine SAML-Assertion weist die folgenden Parameter auf:
| Parameter | Typ | BESCHREIBUNG |
|---|---|---|
| grant_type | required | Typ der Tokenanforderung Bei Anforderungen mit einem JWT muss der Wert urn:ietf:params:oauth:grant-type:jwt-bearer lauten. |
| assertion | required | Der Wert des bei der Anforderung verwendeten Zugriffstoken. |
| client_id | Erforderlich | Die dem aufrufenden Dienst während der Registrierung bei Microsoft Entra ID zugewiesene App-ID. Um die App-ID im Microsoft Entra Admin Center zu finden, navigieren Sie zu Identität>Anwendungen>App-Registrierungen, und wählen Sie dann den Anwendungsnamen aus. |
| client_secret | Erforderlich | Schlüssel, der für den aufrufenden Dienst in Microsoft Entra ID registriert ist. Dieser Wert sollte zum Zeitpunkt der Registrierung notiert werden. Das Standardauthentifizierungsmuster der Bereitstellung von Anmeldeinformationen im Autorisierungsheader gemäß RFC 6749 wird ebenfalls unterstützt. |
| scope | required | Eine durch Leerzeichen getrennte Liste von Bereichen für die Tokenanforderung. Weitere Informationen finden Sie unter Bereiche. SAML selbst verfügt nicht über ein Konzept von Bereichen, sondern wird verwendet, um die SAML-Zielanwendung zu identifizieren, für die Sie ein Token erhalten möchten. Für diesen OBO-Flow muss der Bereichswert immer die SAML-Entitäts-ID mit angefügtem /.default sein. Wenn die Entitäts-ID der SAML-Anwendung beispielsweise https://testapp.contoso.com lautet, sollte der angeforderte Bereich https://testapp.contoso.com/.default sein. Falls die Entitäts-ID nicht mit einem URI-Schema wie https: beginnt, stellt Microsoft Entra der Entitäts-ID spn: voran. In diesem Fall müssen Sie den Bereich spn:<EntityID>/.default anfordern, z. B. spn:testapp/.default für den Fall, dass die Entitäts-ID testapp ist. Der hier angeforderte Bereichswert bestimmt das sich ergebende Audience-Element im SAML-Token. Dies kann für die SAML-Anwendung wichtig sein, die das Token empfängt. |
| requested_token_use | Erforderlich | Gibt an, wie die Anforderung verarbeitet werden soll. Im Im-Auftrag-Fluss muss der Wert on_behalf_of lauten. |
| requested_token_type | required | Gibt den Typ des angeforderten Token an. Abhängig von den Anforderungen der Ressource, auf die zugegriffen wird, kann der Wert urn:ietf:params:oauth:token-type:saml2 oder urn:ietf:params:oauth:token-type:saml1 lauten. |
Die Antwort enthält ein UTF8- und Base 64url-codiertes SAML-Token.
- SubjectConfirmationData für eine SAML-Assertion von einem OBO-Aufruf: Wenn die Zielanwendung einen
Recipient-Wert inSubjectConfirmationDataerfordert, muss der Wert in der Konfiguration der Ressourcenanwendung als erste Antwort-URL ohne Platzhalter konfiguriert werden. Da die Standardantwort-URL nicht zum Ermitteln desRecipient-Werts verwendet wird, müssen Sie die Antwort-URLs in der Anwendungskonfiguration möglicherweise neu anordnen, um sicherzustellen, dass die erste Antwort-URL ohne Platzhalter verwendet wird. Weitere Informationen finden Sie unter Antwort-URLs. - Der SubjectConfirmationData-Knoten: Der Knoten darf kein
InResponseTo-Attribut enthalten, da er nicht Teil einer SAML-Antwort ist. Die Anwendung, die das SAML-Token empfängt, muss die SAML-Assertion ohneInResponseTo-Attribut akzeptieren können. - API-Berechtigungen: Sie müssen die erforderlichen API-Berechtigungen für die Anwendung der mittleren Ebene hinzufügen, um den Zugriff auf die SAML-Anwendung zuzulassen, damit sie ein Token für den
/.default-Bereich der SAML-Anwendung anfordern kann. - Zustimmung: Um ein SAML-Token zu empfangen, das Benutzerdaten zu einem OAuth-Flow enthält, muss Zustimmung erteilt werden. Weitere Informationen finden Sie unter Erhalten der Zustimmung für die Anwendung der mittleren Ebene.
Antwort mit SAML-Assertion
| Parameter | BESCHREIBUNG |
|---|---|
| token_type | Gibt den Wert des Tokentyps an. Der einzige Typ, der Microsoft Entra ID unterstützt, ist Bearer. Weitere Informationen zu Bearertoken finden Sie unter OAuth 2.0-Autorisierungsframework: Verwendung von Bearertoken (RFC 6750). |
| scope | Der durch das Token gewährte Zugriffsbereich. |
| expires_in | Gibt an, wie lange das Zugriffstoken gültig ist (in Sekunden). |
| expires_on | Die Uhrzeit, zu der das Zugriffstoken abläuft. Das Datum wird als Anzahl der Sekunden ab 1970-01-01T0:0:0Z UTC bis zur Ablaufzeit dargestellt. Dieser Wert wird verwendet, um die Lebensdauer von zwischengespeicherten Token zu bestimmen. |
| resource | Der App-ID-URI des empfangenden Diensts (geschützte Ressource). |
| access_token | Der Parameter, der die SAML-Assertion zurückgibt. |
| refresh_token | Das Aktualisierungstoken. Der aufrufende Dienst kann dieses Token verwenden, um nach Ablauf der aktuellen SAML-Assertion ein neues Zugriffstoken anzufordern. |
- token_type: Bearer
- expires_in: 3296
- ext_expires_in: 0
- expires_on: 1529627844
- resource:
https://api.contoso.com - access_token: <SAML-Assertion>
- issued_token_type: urn:ietf:params:oauth:token-type:saml2
- refresh_token: <Aktualisierungstoken>
Erhalten der Zustimmung für die Anwendung der mittleren Ebene
Ziel des OBO-Flows ist es, sicherzustellen, dass eine ordnungsgemäße Einwilligung erteilt wird, damit die Clientanwendung die Anwendung auf der mittleren Ebene aufrufen kann und die Anwendung auf der mittleren Ebene berechtigt ist, die Back-End-Ressource aufzurufen. Abhängig von der Architektur oder Nutzung Ihrer Anwendung sollten Sie die folgenden Punkte berücksichtigen, um einen erfolgreichen OBO-Flow zu gewährleisten.
/.default und kombinierten Einwilligung
Die Anwendung der mittleren Ebene fügt den Client der Liste der bekannten Clientanwendungen (knownClientApplications) im Manifest hinzu. Wenn eine Zustimmungsaufforderung vom Client ausgelöst wird, gilt der Zustimmungsablauf sowohl für sich selbst als auch für die Anwendung der mittleren Ebene. Für Microsoft Identity Platform erfolgt dies mithilfe des .default-Bereichs. Der .default-Bereich ist ein spezieller Bereich, der zum Anfordern der Einwilligung zum Zugriff auf alle Bereiche verwendet wird, für die die Anwendung über Berechtigungen verfügt. Dies ist nützlich, wenn die Anwendung auf mehrere Ressourcen zugreifen muss, der Benutzer aber nur ein Mal zur Einwilligung aufgefordert werden sollte.
Wenn Sie einen Zustimmungsbildschirm mit bekannten Clientanwendungen und .default auslösen, zeigt der Bildschirm die Berechtigungen des Client für die API der mittleren Ebene an und fordert auch die von der API der mittleren Ebene benötigten Berechtigungen an. Der Benutzer gibt die Einwilligung für beide Anwendungen, und dann funktioniert der OBO-Fluss.
Der in der Anforderung identifizierte Ressourcendienst (API) sollte die API sein, für die die Clientanwendung ein Zugriffstoken als Ergebnis der Anmeldung des Benutzers an fordert. Beispiel: scope=openid https://middle-tier-api.example.com/.default (zum Anfordern eines Zugriffstokens für die API der mittleren Ebene) oder scope=openid offline_access .default (wenn eine Ressource nicht identifiziert wird, wird standardmäßig Microsoft Graph verwendet).
Unabhängig davon, welche API in der Autorisierungsanforderung identifiziert wird, wird die Einwilligungsaufforderung mit allen erforderlichen Berechtigungen kombiniert, die für die Client-App konfiguriert sind. Alle erforderlichen Berechtigungen, die für jede in der Liste der erforderlichen Berechtigungen des Clients aufgeführte API der mittleren Ebene konfiguriert wurden und die den Client als bekannte Clientanwendung identifiziert haben, werden ebenfalls berücksichtigt.
Vorautorisierte Anwendungen
Ressourcen können angeben, dass eine bestimmte Anwendung immer die Berechtigung hat, bestimmte Bereiche zu empfangen. Dies ist nützlich, um die Verbindungen zwischen einem Front-End-Client und einer Back-End-Ressource reibungslos zu gestalten. Eine Ressource kann mehrere vorab autorisierte Anwendungen (preAuthorizedApplications) in ihrem Manifest deklarieren. Jede dieser Anwendungen kann diese Berechtigungen in einem OBO-Flow anfordern und ohne Einwilligung des Benutzers empfangen.
Administratorzustimmung
Ein Mandantenadministrator kann garantieren, dass Anwendungen die Berechtigung haben, ihre erforderlichen APIs aufzurufen, indem er die Einwilligung des Administrators für die Anwendung der mittleren Ebene erteilt. Dazu kann der Administrator die Anwendung der mittleren Ebene in seinem Mandanten suchen, die erforderliche Berechtigungsseite öffnen und die Berechtigung für die App erteilen. Weitere Informationen zur Einwilligung des Administrators finden Sie in der Dokumentation zu Einwilligungen und Berechtigungen.
Verwenden einer einzelnen Anwendung
In einigen Szenarios kann es vorkommen, dass Sie nur eine einzige Paarung eines Clients der mittleren Ebene und eines Front-End-Clients haben. In diesem Szenario ist es möglicherweise einfacher, eine einzige Anwendung zu erstellen, wodurch die Notwendigkeit einer Anwendung auf mittlerer Ebene ganz entfällt. Um zwischen der Front-End- und der Web-API zu authentifizieren, können Sie Cookies, ein "id_token" oder ein Zugriffstoken für die Anwendung selbst angefordert. Fordern Sie dann die Einwilligung dieser einzelnen Anwendung zur Back-End-Ressource an.
Siehe auch
Erfahren Sie mehr über das OAuth 2.0-Protokoll und eine andere Möglichkeit, Dienst-zu-Dienst-Authentifizierungen mit Client-Anmeldedaten auszuführen.