Microsoft Identity Platform und der Fluss von OAuth 2.0-Clientanmeldeinformationen

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. Die Gewährung von OAuth 6749-Clientanmeldeinformationen, die in RFC 6749 angegeben ist und gelegentlich als zweibeinige OAuth-Autorisierung bezeichnet wird, kann für den Zugriff auf webgehostete Ressourcen über die Identität einer Anwendung verwendet werden. Dieser Typ wird häufig für Server-zu-Server-Interaktionen verwendet, die ohne Benutzereingriff im Hintergrund ausgeführt werden müssen, und wird häufig als Daemons oder Dienstkonten bezeichnet.

Im Flow zum Gewähren von Clientanmeldeinformationen werden Berechtigungen von einem Administrator direkt an die eigentliche Anwendung erteilt. Wenn die App einer Ressource ein Token präsentiert, macht die Ressource geltend, dass die App selbst für die Durchführung einer Aktion autorisiert ist, da an der Authentifizierung kein Benutzer beteiligt ist. In diesem Artikel werden die beiden Schritte behandelt, die für Folgendes erforderlich sind:

• Autorisieren einer Anwendung zum Aufrufen einer API
• Erhalten der Token, die zum Aufrufen dieser API erforderlich sind.

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 auch unter Beispiel-Apps, die MSAL verwenden. Nebenbei bemerkt werden Aktualisierungstoken nie mit diesem Flow gewährt, da client_id und client_secret (die zum Abrufen eines Aktualisierungstokens erforderlich wären) stattdessen zum Abrufen eines Zugriffstokens verwendet werden können.

Für ein höheres Maß an Sicherheit erlaubt die Microsoft-Identitätsplattform dem aufrufenden Dienst auch die Authentifizierung mit einem Zertifikat oder einem föderierten Berechtigungsnachweis anstelle eines gemeinsamen Geheimnisses. Da die eigenen Anmeldeinformationen der Anwendung verwendet werden, müssen diese Anmeldeinformationen sicher aufbewahrt werden. Veröffentlichen Sie diese Anmeldeinformationen niemals in Ihrem Quellcode, betten Sie sie nicht in Webseiten ein, und verwenden Sie sie nicht in weit verbreiteten nativen Anwendungen.

Protokolldiagramm

Der gesamte Clientanmeldeinformations-Flow ist im folgenden Diagramm dargestellt. Wir beschreiben die einzelnen Schritte weiter unten in diesem Artikel.

Erhalten der direkten Autorisierung

Eine App empfängt die direkte Autorisierung für den Zugriff auf eine Ressource in der Regel auf zwei Arten:

• Über eine Zugriffssteuerungsliste (Access Control List, ACL) der Ressource
• Durch Zuweisung einer Anwendungsberechtigung in Microsoft Entra ID

Diese beiden Methoden sind in Microsoft Entra ID am gebräuchlichsten und werden von uns für Clients und Ressourcen empfohlen, die den Clientanmeldeinformations-Flow ausführen. Eine Ressource kann auch wählen, dass die Clients auf andere Weise autorisiert werden sollen. Jeder Ressourcenserver kann die Methode auswählen, die am sinnvollsten für seine Anwendung ist.

Zugriffssteuerungslisten

Ein Ressourcenanbieter erzwingt möglicherweise eine Autorisierungsprüfung anhand einer Liste von Anwendungs-IDs (Client-IDs), die ihm bekannt sind, und erteilt eine bestimmte Zugriffsebene. Empfängt die Ressource ein Token von der Microsoft Identity Platform, kann sie das Token decodieren und die Anwendungs-ID des Clients aus den Ansprüchen appid und iss extrahieren. Anschließend vergleicht sie die Anwendung mit der von ihr verwalteten Zugriffssteuerungsliste. Granularität der Zugriffssteuerungsliste und Methode können sich zwischen Ressourcen erheblich unterscheiden.

Ein allgemeiner Anwendungsfall ist die Verwendung einer Zugriffssteuerungsliste zum Ausführen von Tests für eine Webanwendung oder eine Web-API. Die Web-API gewährt einem bestimmten Client möglicherweise nur eine Teilmenge der vollständigen Berechtigungen. Zum Ausführen von End-to-End-Tests auf der API können Sie einen Testclient erstellen, der Token von der Microsoft Identity Platform erhält und diese anschließend an die API sendet. Die API überprüft die Anwendungs-ID des Testclients anschließend anhand der Zugriffssteuerungsliste, um Vollzugriff auf die gesamte Funktionalität der API zu gewähren. Wenn Sie eine solche Zugriffssteuerungsliste verwenden, müssen Sie nicht nur den appid-Wert des Aufrufers überprüfen, sondern auch sicherstellen, dass der iss-Wert des Tokens vertrauenswürdig ist.

Diese Art der Autorisierung wird häufig für Daemons und Dienstkonten eingesetzt, die auf Daten zugreifen müssen, die sich im Besitz von Privatnutzern mit persönlichen Microsoft-Konten befinden. Für Daten, die Organisationen gehören, empfiehlt es sich, die erforderliche Autorisierung über Anwendungsberechtigungen zu erhalten.

Steuern von Token ohne den roles-Anspruch

Microsoft Entra ID setzt nicht voraus, dass Anwendungen zum Abrufen von Token für eine andere Anwendung autorisiert sind, um dieses ACL-basierte Autorisierungsmuster zu aktivieren. Daher können nur für Apps gültige Token ohne einen roles-Anspruch ausgestellt werden. Bei Anwendungen, die APIs verfügbar machen, müssen zum Akzeptieren von Token Berechtigungsüberprüfungen implementiert werden.

Wenn Sie verhindern möchten, dass Anwendungen nur für Apps gültige Zugriffstoken ohne Rollen abrufen, sollten Sie sicherstellen, dass die Zuweisungsanforderungen für Ihre App aktiviert sind. Dadurch wird verhindert, dass Benutzer und Anwendungen ohne zugewiesene Rollen ein Token für diese Anwendung abrufen können.

Anwendungsberechtigungen

Anstelle von Zugriffssteuerungslisten können Sie APIs verwenden, um einen Satz von Anwendungsberechtigungen verfügbar zu machen. Diese werden einer Anwendung von einem Administrator einer Organisation gewährt und können nur für den Zugriff auf Daten verwendet werden, die sich im Besitz der jeweiligen Organisation und deren Mitarbeiter befinden. Microsoft Graph macht beispielsweise verschiedene Anwendungsberechtigungen für Folgendes verfügbar:

• Lesen von E-Mails in allen Postfächern
• Lesen und Schreiben von E-Mails in allen Postfächern
• Senden von E-Mails als beliebiger Benutzer
• Verzeichnisdaten lesen

Wenn Sie App-Rollen (Anwendungsberechtigungen) mit Ihrer eigenen API (und nicht mit Microsoft Graph) verwenden möchten, müssen Sie zunächst im Microsoft Entra Admin Center in der App-Registrierung der API die App-Rollen verfügbar machen. Konfigurieren Sie dann die erforderlichen App-Rollen, indem Sie diese Berechtigungen in der App-Registrierung Ihrer Clientanwendung auswählen. Wenn Sie in der App-Registrierung Ihrer API keine App-Rollen verfügbar gemacht haben, können Sie im Microsoft Entra Admin Center in der App-Registrierung Ihrer Clientanwendung keine Anwendungsberechtigungen für diese API angeben.

Wenn Sie sich als Anwendung authentifizieren (im Gegensatz zu einem Benutzer), können Sie keine delegierten Berechtigungen verwenden, weil es keinen Benutzer gibt, in dessen Namen die App agieren kann. Sie müssen Anwendungsberechtigungen (auch als App-Rollen bezeichnet) verwenden, die von einem Administrator oder vom Besitzer der API erteilt werden.

Weitere Informationen zu Anwendungsberechtigungen finden Sie unter Berechtigungen und Einwilligung.

Empfohlen: Melden Sie den Administrator bei Ihrer App an, um App-Rollen zugewiesen zu bekommen

Wenn Sie eine Anwendung erstellen, die Anwendungsberechtigungen verwendet, erfordert die App in der Regel eine Seite oder eine Sicht, auf der der Administrator Berechtigungen für die App genehmigt. Diese Seite kann Teil des Anmelde-Flows der App, Teil der App-Einstellungen oder ein dedizierter Verbinden-Flow sein. Oft ist es sinnvoll, dass die App diese Verbinden-Ansicht erst anzeigt, wenn ein Benutzer sich mit einem Geschäfts-, Schul- oder Unikonto von Microsoft angemeldet hat.

Durch das Anmelden des Benutzers bei Ihrer App können Sie die Organisation identifizieren, der der Benutzer angehört, bevor Sie ihn zur Genehmigung der Anwendungsberechtigungen auffordern. Auch wenn es nicht unbedingt erforderlich ist, können Sie für Ihre Benutzer auf diese Weise eine intuitivere Benutzeroberfläche erstellen. Gehen Sie gemäß den Tutorials zum Microsoft Identity Platform-Protokoll vor, um den Benutzer anzumelden.

Anfordern der Berechtigungen von einem Verzeichnisadministrator

Wenn Sie dazu bereit sind, vom Administrator der Organisation Berechtigungen anzufordern, können Sie den Benutzer zum Endpunkt für die Administratorzustimmung von Microsoft Identity Platform umleiten.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&state=12345
&redirect_uri=http://localhost/myapp/permissions

Profitipp: Versuchen Sie, die folgende Anforderung in einem Browser einzufügen.

https://login.microsoftonline.com/common/adminconsent?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&state=12345&redirect_uri=http://localhost/myapp/permissions

An diesem Punkt erzwingt Microsoft Entra ID, dass sich nur ein Mandantenadministrator anmelden kann, um die Anforderung abzuschließen. Der Administrator wird aufgefordert, alle direkten Anwendungsberechtigungen zu genehmigen, die Sie für Ihre App im App-Registrierungsportal angefordert haben.

Erfolgreiche Antwort

Wenn der Administrator die Berechtigungen für Ihre Anwendung genehmigt, lautet die erfolgreiche Antwort wie folgt:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True

Fehlerantwort

Wenn der Administrator die Berechtigungen für Ihre Anwendung nicht genehmigt, lautet die Fehlerantwort wie folgt:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request

Nachdem Sie eine erfolgreiche Antwort vom App-Bereitstellungsendpunkt erhalten haben, erhält Ihre App die direkten Anwendungsberechtigungen, die sie angefordert hat. Als Nächstes können Sie ein Token für eine gewünschte Ressource anfordern.

Abrufen von Token

Sobald Sie die notwendige Autorisierung für Ihre Anwendung erhalten haben, können Sie mit dem Abrufen von Zugriffstoken für APIs fortfahren. Um ein Token über die Gewährung von Clientanmeldeinformationen zu erhalten, senden Sie eine POST-Anforderung an die /token-Microsoft Identity Platform. Es lassen sich verschiedene Fälle unterscheiden:

• Zugriffstokenanforderung mit einem gemeinsamen Geheimnis
• Zugriffstokenanforderung mit einem Zertifikat
• Anforderung eines Zugriffstokens mit einem föderierten Berechtigungsnachweis

Erster Fall: Zugriffstokenanforderung mit einem gemeinsamen Geheimnis

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

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials

# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=00001111-aaaa-2222-bbbb-3333cccc4444&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=A1bC2dE3f...&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'

Zweiter Fall: Zugriffstokenanforderung mit einem Zertifikat

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

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&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}M8U3bSUKKJDEg
&grant_type=client_credentials

Die Parameter für die zertifikatbasierte Anforderung stimmen mit nur einer Ausnahme mit den Parametern für die Anforderung basierend auf einem gemeinsamen Geheimnis überein: der client_secret-Parameter wird durch die Parameter client_assertion_type und client_assertion ersetzt.

Dritter Fall: Anforderung eines Zugriffstokens mit einem föderierten Berechtigungsnachweis

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

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&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}M8U3bSUKKJDEg
&grant_type=client_credentials

Alles in der Anfrage entspricht dem obigen zertifikatsbasierten Fluss, mit einer entscheidenden Ausnahme: der Quelle der client_assertion. Bei diesem Ablauf erstellt Ihre Anwendung die JWT-Assertion nicht selbst. Stattdessen verwendet Ihre Anwendung ein JWT, das von einem anderen Identitätsanbieter erstellt wurde. Dies wird als workload identity federation bezeichnet, bei der die Identität Ihrer Anwendungen in einer anderen Identitätsplattform verwendet wird, um Token innerhalb der Microsoft-Identitätsplattform zu erwerben. Dies eignet sich am besten für Cloud-übergreifende Szenarien, z. B. wenn Sie Ihre Rechenleistung außerhalb von Azure hosten, aber auf APIs zugreifen, die durch die Microsoft Identitätsplattform geschützt sind. Informationen zum erforderlichen Format von JWTs, die von anderen Identitätsanbietern erstellt werden, finden Sie unter Assertionsformat.

Erfolgreiche Antwort

Eine erfolgreiche Antwort von einer beliebigen Methode sieht wie folgt aus:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}

Fehlerantwort

Eine Fehlerantwort (400 Bad Request) sieht wie folgt aus:

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

Verwenden eines Tokens

Da Sie jetzt ein Token abgerufen haben, können Sie dieses Token verwenden, um Anforderungen an die Ressource zu stellen. Wenn das Token abläuft, wiederholen Sie die Anforderung an den /token-Endpunkt, um ein neues Zugriffstoken abzurufen.

GET /v1.0/users HTTP/1.1
Host: graph.microsoft.com:443
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...

Führen Sie den folgenden Befehl in Ihrem Terminal aus, und stellen Sie sicher, dass Sie das Token durch Ihr eigenes ersetzen.

curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG..." 'https://graph.microsoft.com/v1.0/users'

Codebeispiele und anderes Dokumentationsmaterial

Lesen Sie die Übersichtsdokumentation zu Clientanmeldeinformationen aus der Microsoft-Authentifizierungsbibliothek.