Teilen ü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 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.

Zeigt den On-Behalf-Of-Fluss von OAuth 2.0

  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. 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\":[\"00aa00aa-bb11-cc22-dd33-44ee44ee44ee\"]}}}"
}

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 in SubjectConfirmationData erfordert, muss der Wert in der Konfiguration der Ressourcenanwendung als erste Antwort-URL ohne Platzhalter konfiguriert werden. Da die Standardantwort-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 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 ohne InResponseTo-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>

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.

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.

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.