Freigeben über

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 verwendet nur delegierte Bereiche und keine Anwendungsrollen. Rollen bleiben dem Prinzipal (dem Benutzer) und nie an die Anwendung angefügt, die im Namen 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. Wenn möglich, empfehlen wir, stattdessen die unterstützten Microsoft-Authentifizierungsbibliotheken (MSAL) zu verwenden, um Token abzurufen und gesicherte Web-APIs aufzurufen. Weitere Informationen finden Sie in den Beispiel-Apps, die MSAL für Beispiele 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 Clientanmeldeinformationsfluss 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. Zugriffstoken, die über den impliziten Genehmigungsfluss erworben wurden, werden jedoch von einem vertraulichen Client eingelöst, auch wenn der initiierende Client eine Wildcardantwort-URL 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 nicht die Signatur des Zugriffstokens, das an ihn übergeben wird. Dies führt zu einem Fehler, da Token, die mit einem vom Client gesteuerten Schlüssel signiert wurden, nicht sicher akzeptiert werden können.

Protokolldiagramm

Gehen Sie davon aus, dass der Benutzer eine Anwendung mithilfe des OAuth 2.0-Autorisierungscodegenehmigungsflusses oder eines anderen Anmeldeflusses authentifiziert hat. An diesem Punkt verfügt die Anwendung über ein Zugriffstoken für API A (Token A) mit den Ansprüchen des Benutzers und der Zustimmung für den Zugriff auf die Web-API der mittleren Ebene (API A). 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.

Zeigt den OAuth2.0 On-Behalf-Of-Fluss an.

  1. Die Clientanwendung stellt mit Token A eine Anforderung an die API A (mit dem Anspruch aud von API A).
  2. API A wird beim Tokenausstellungs-Endpunkt der Microsoft Identity Platform authentifiziert und fordert ein Token für den Zugriff auf API B an.
  3. 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.
  4. Token B wird von API A im Autorisierungsheader der Anforderung auf API B festgelegt.
  5. 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. Informationen zum Implementieren dieser Informationen in Ihrer App finden Sie unter "Einholen der Zustimmung für die Anwendung auf mittlerer 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 KEINE Zugriffstoken, die an eine beliebige Stelle ausgegeben wurden, mit Ausnahme der vorgesehenen Zielgruppe für das Token. Zugriffstoken, die auf der mittleren Ebene ausgestellt wurden, sind nur für die Verwendung durch diese mittlere Ebene vorgesehen, um mit dem vorgesehenen Zielgruppenendpunkt zu kommunizieren.

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 dem Microsoft Entra Admin Center – App-Registrierungsseite zugewiesen ist, die Ihrer App 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, anstatt Anmeldeinformationen im Autorisierungsheader bereitzustellen, wird pro RFC 6749 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 dem Microsoft Entra Admin Center – App-Registrierungsseite zugewiesen ist, die Ihrer App 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 und des Formats der Assertion finden Sie unter 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 fast identisch sind wie bei der Anforderung durch einen freigegebenen geheimen Schlüssel, mit der Ausnahme, dass der client_secret Parameter durch zwei Parameter ersetzt wird: a client_assertion_type und client_assertion. 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 im OAuth 2.0-Autorisierungsframework: Bearer Token Usage (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 Verbindung steht, die zum Anfordern 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önnten darauf hinweisen, dass v2.0-Formattoken, v1.0-Formattoken oder sogar proprietäre oder verschlüsselte Tokenformate verwendet werden sollen. Die Endpunkte der Versionen 1.0 und 2.0 können jedes beliebige Tokenformat ausgeben. Auf diese Weise kann die Ressource unabhängig davon, wie oder wo das Token vom Client angefordert wird, immer das richtige Tokenformat abrufen.

Warnung

Versuchen Sie nicht, Token für eine API zu überprüfen oder zu lesen, die Sie nicht besitzen, einschließlich der Token in diesem Beispiel, in Ihrem Code. Token für Microsoft-Dienste können ein spezielles Format verwenden, das nicht als JWT überprüft wird, und kann auch für Verbraucherbenutzer (Microsoft-Konto) verschlüsselt werden. Während das Lesen von Token ein nützliches Debugging- und Lerntool ist, nehmen Sie keine Abhängigkeiten davon in Ihrem Code ab, oder gehen Sie von Besonderheiten zu Token aus, die nicht für eine von Ihnen gesteuerte API gelten.

Beispiel für eine fehlerhafte Antwort

Eine Fehlerantwort wird vom Tokenendpunkt zurückgegeben, wenn versucht wird, ein Zugriffstoken für die downstream-API abzurufen, wenn die downstream-API über eine Richtlinie für bedingten Zugriff (z. B. mehrstufige Authentifizierung) verfügt. 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 Anspruchsabfrage 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 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\":[\"00aa00aa-bb11-cc22-dd33-44ee44ee44ee\"]}}}"
}

Verwenden des Zugriffstokens für den Zugriff auf die gesicherte Ressource

Jetzt kann der Dienst auf mittlerer Ebene das zuvor erworbene Token verwenden, um authentifizierte Anforderungen an die downstream-Web-API durchzuführen, indem das Token im Authorization Header festgelegt wird.

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 On-Behalf-Of-Fluss, der es einer OAuth2-basierten Anwendung ermöglicht, auf Webdienst-API-Endpunkte zuzugreifen, 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
Authentifizierungstyp (grant_type) Erforderlich Typ der Tokenanforderung Bei Anforderungen mit einem JWT muss der Wert urn:ietf:params:oauth:grant-type:jwt-bearer lauten.
Aussage Erforderlich Der Wert des bei der Anforderung verwendeten Zugriffstoken.
Kunden-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 Entra>, und wählen Sie dann den Anwendungsnamen aus.
client_secret (Kunden-Geheimnis) Erforderlich Schlüssel, der für den aufrufenden Dienst in Microsoft Entra ID registriert ist. Dieser Wert sollte zum Zeitpunkt der Registrierung angegeben werden. Das Standardauthentifizierungsmuster, anstatt Anmeldeinformationen im Autorisierungsheader bereitzustellen, wird pro RFC 6749 ebenfalls unterstützt.
Umfang Erforderlich 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 resultierende Audience Element im SAML-Token, das für die SAML-Anwendung, die das Token empfängt, wichtig sein könnte.
requested_token_use Erforderlich Gibt an, wie die Anforderung verarbeitet werden soll. Im Im-Auftrag-Fluss muss der Wert on_behalf_of lauten.
angeforderter_Token_Typ Erforderlich 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 SAML-Token, das in UTF8 und Base 64url codiert ist.

  • SubjectConfirmationData für eine SAML-Assertion, die aus einem OBO-Aufruf stammt: Wenn für die Zielanwendung ein Recipient Wert SubjectConfirmationDataerforderlich ist, muss der Wert als erste nichtwildcardantwort-URL in der Ressourcenanwendungskonfiguration konfiguriert werden. Da die standardmäßige Antwort-URL nicht zum Ermitteln des Recipient Werts verwendet wird, müssen Sie die Antwort-URLs in der Anwendungskonfiguration möglicherweise neu anordnen, um sicherzustellen, dass die erste nichtwildcardantwort-URL verwendet wird. Weitere Informationen finden Sie unter Antwort-URLs.
  • The SubjectConfirmationData node: The node can't contain an InResponseTo attribute since it's not part of a SAML response. Die Anwendung, die das SAML-Token empfängt, muss die SAML-Assertion ohne InResponseTo-Attribut akzeptieren können.
  • API-Berechtigungen: Sie müssen die erforderlichen API-Berechtigungen für die Mittlere Ebene-Anwendung hinzufügen, um den Zugriff auf die SAML-Anwendung zu ermöglichen, damit es ein Token für den /.default Umfang der SAML-Anwendung anfordern kann.
  • Zustimmung: Die Zustimmung muss erteilt werden, um ein SAML-Token zu erhalten, das Benutzerdaten in einem OAuth-Fluss enthält. Weitere Informationen finden Sie unter "Einholen der Zustimmung für die mittlere Anwendung".

Antwort mit SAML-Assertion

Parameter BESCHREIBUNG
Token-Typ Gibt den Wert des Tokentyps an. Der einzige Von Microsoft Entra-ID unterstützte Typ ist Bearer. Weitere Informationen zu Bearertoken finden Sie unter OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750).
Umfang Der durch das Token gewährte Zugriffsbereich.
expires_in Gibt an, wie lange das Zugriffstoken gültig ist (in Sekunden).
läuft_ab_am Der Zeitpunkt, zu dem das Zugriffstoken abläuft. Das Datum wird als Anzahl von Sekunden zwischen 1970-01-01T0:0:0Z UTC bis zur Ablaufzeit dargestellt. Dieser Wert wird verwendet, um die Lebensdauer von zwischengespeicherten Token zu bestimmen.
Ressource Der App-ID-URI des empfangenden Diensts (geschützte Ressource).
access_token (Zugriffstoken) Der Parameter, der die SAML-Assertion zurückgibt.
Aktualisierungstoken Das Aktualisierungstoken. Der aufrufende Dienst kann dieses Token verwenden, um nach Ablauf der aktuellen SAML-Assertion ein neues Zugriffstoken anzufordern.
  • token_type: Bearer
  • läuft_ab_in: 3296
  • ext_expires_in: 0
  • abläuft_am: 1529627844
  • Ressource: https://api.contoso.com
  • access_token: <SAML-Assertion>
  • ausgestellter_Token-Typ: urn:ietf:params:oauth:token-type:saml2
  • refresh_token: <Aktualisierungstoken>

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. Je nach Architektur oder Verwendung Ihrer Anwendung sollten Sie Folgendes berücksichtigen, um sicherzustellen, dass der OBO-Fluss erfolgreich ist:

Die Anwendung der mittleren Ebene fügt den Client der Liste bekannter Clientanwendungen (knownClientApplications) im Manifest hinzu. Wenn eine Zustimmungsaufforderung vom Client ausgelöst wird, gilt der Zustimmungsfluss sowohl für sich selbst als auch für die Anwendung auf mittlerer Ebene. Auf der 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.

Beim Auslösen eines Zustimmungsbildschirms mithilfe bekannter Clientanwendungen und .defaultzeigt der Zustimmungsbildschirm Berechtigungen für den Client sowohl für die API der mittleren Ebene an, als auch alle Berechtigungen an, die von der API der mittleren Ebene benötigt werden. 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 Zustimmungsaufforderung mit allen erforderlichen Berechtigungen kombiniert, die für die Client-App konfiguriert sind. Alle erforderlichen Berechtigungen, die für jede api der mittleren Ebene konfiguriert sind, die in der Liste der erforderlichen Berechtigungen des Clients aufgeführt sind, die den Client als bekannte Clientanwendung identifiziert haben, sind ebenfalls enthalten.

Von Bedeutung

Es ist zwar gültig, in kombinierten Zustimmungsflüssen mit scope=openid https://resource/.default zu verwenden, sie dürfen jedoch nicht mit anderen delegierten Bereichen wie .default, , User.Read, Mail.Readoder profile in derselben Anforderung kombiniert werdenUser.ReadWrite.All. Dies führt zu AADSTS70011 Fehlern, da .default sie statische Vorberechtigungen darstellen, während die anderen zur Laufzeit eine dynamische Benutzereinstimmung erfordern.

offline_access wird manchmal akzeptiert .default , um Aktualisierungstoken zu aktivieren, sollte jedoch nicht mit zusätzlichen delegierten Bereichen kombiniert werden. Teilen Sie im Zweifelsfall die Tokenanforderungen auf, um Bereichstypenkonflikte zu vermeiden.

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 vorautorisierte Anwendungen (preAuthorizedApplications) im Manifest deklarieren. Jede dieser Anwendungen kann diese Berechtigungen in einem OBO-Flow anfordern und ohne Einwilligung des Benutzers empfangen.

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 Administratorzustimmung finden Sie in der Dokumentation zu Zustimmung und Berechtigungen.

Verwenden einer einzelnen Anwendung

In einigen Szenarien können Sie nur eine einzelne Kopplung des Clients zwischen mittlerer Ebene und Front-End haben. In diesem Szenario könnte es einfacher sein, dies zu einer einzelnen Anwendung zu machen, was die Notwendigkeit einer Anwendung auf mittlerer Ebene insgesamt negiert. 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.