Microsoft Identity Platform und OAuth 2.0-Kennwortanmeldeinformationen des Ressourcenbesitzers

Artikel
04/08/2024

Die Microsoft Identity Platform unterstützt die Gewährung für OAuth 2.0-Kennwortanmeldeinformationen des Ressourcenbesitzers (ROPC). So kann eine Anwendung Benutzer anmelden, indem sie ihr Kennwort direkt verarbeitet. 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. Sehen Sie sich auch die Beispiel-Apps an, die MSAL verwenden.

Warnung

Microsoft empfiehlt, dass Sie nicht den ROPC-Flow verwenden. In den meisten Szenarien sind sicherere Alternativen verfügbar und werden daher empfohlen. Dieser Flow erfordert ein sehr hohes Maß an Vertrauen in die Anwendung und birgt Risiken, die in anderen Flows nicht vorhanden sind. Verwenden Sie diesen Flow nur, wenn kein anderer Flow verfügbar ist, der mehr Sicherheit bietet.

Wichtig

Microsoft Identity Platform unterstützt die ROPC-Gewährung nur bei Microsoft Entra-Mandanten, nicht für persönliche Konten. Das bedeutet, Sie müssen einen mandantenspezifischen Endpunkt (https://login.microsoftonline.com/{TenantId_or_Name}) oder den Endpunkt organizations verwenden.
Persönliche Konten, die zu einem Microsoft Entra-Mandanten eingeladen werden, können den ROPC-Flow nicht verwenden.
Konten ohne Kennwörter können sich nicht mit ROPC anmelden. Dies bedeutet, dass Features wie SMS-Anmeldung, FIDO und die Authenticator-App bei diesem Flow nicht funktionieren. Wenn Ihre Apps oder Ihre Benutzer diese Funktionen benötigen, müssen Sie anstelle von RPOC einen anderen Gewährungstyp verwenden.
Wenn Benutzer die mehrstufige Authentifizierung (Multi-Factor Authentication, MFA) verwenden müssen, um sich bei der Anwendung anzumelden, werden Sie stattdessen blockiert.
ROPC wird in Szenarien mit Hybrididentitätsverbund (also beispielsweise bei Verwendung von Microsoft Entra ID und AD FS für die Authentifizierung lokaler Konten) nicht unterstützt. Wenn Benutzer*innen vollständig auf eine Seite eines lokalen Identitätsanbieters weitergeleitet werden, kann Microsoft Entra ID den Benutzernamen und das Kennwort nicht anhand dieses Identitätsanbieters testen. Die Passthrough-Authentifizierung wird mit ROPC allerdings unterstützt.
Beispiel für eine Ausnahme für ein Szenario mit Hybrididentitätsverbund: Durch Festlegen von AllowCloudPasswordValidation auf „TRUE“ für die Richtlinie zur Startbereichsermittlung kann der ROPC-Flow für Verbundbenutzer verwendet werden, wenn das lokale Kennwort mit der Cloud synchronisiert wird. Weitere Informationen finden Sie unter Aktivieren der direkten ROPC-Authentifizierung von Verbundbenutzern für Legacyanwendungen.
Kennwörter mit voran- oder nachgestellten Leerzeichen werden vom ROPC-Flow nicht unterstützt.

Protokolldiagramm

Dieses Diagramm zeigt den ROPC-Flow:

Diagram showing the resource owner password credential flow

Autorisierungsanforderung

Der ROPC-Flow ist eine einzelne Anforderung: Die Client-ID und die Anmeldeinformationen des Benutzers werden an den Identitätsanbieter gesendet, im Gegenzug wird ein Token empfangen. Zuvor muss der Client die E-Mail-Adresse des Benutzers und das Kennwort anfordern. Unmittelbar nach einer erfolgreichen Anforderung muss der Client die Anmeldeinformationen des Benutzers sicher aus dem Arbeitsspeicher entfernen. Er darf sie niemals speichern.

// Line breaks and spaces are for legibility only.  This is a public client, so no secret is required.

POST {tenant}/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile%20offline_access
&username=MyUsername@myTenant.com
&password=SuperS3cret
&grant_type=password

Parameter	Condition	Beschreibung
`tenant`	Erforderlich	Der Verzeichnismandant, bei dem Sie den Benutzer anmelden möchten. Der Mandant kann im GUID-Format oder als Anzeigename bereitgestellt werden. Dieser Parameter kann nicht auf `common` oder `consumers`, sondern nur auf `organizations` festgelegt werden.
`client_id`	Erforderlich	Die Anwendungs-ID (Client-ID), die Ihrer App auf der Seite „App-Registrierungen“ im Microsoft Entra Admin Center zugewiesen ist.
`grant_type`	Erforderlich	Muss auf `password` festgelegt sein.
`username`	Erforderlich	Die E-Mail-Adresse des Benutzers.
`password`	Erforderlich	Das Kennwort des Benutzers.
`scope`	Empfohlen	Eine durch Leerzeichen getrennte Liste von Bereichen oder Berechtigungen, die die App benötigt. In einem interaktiven Flow müssen der Administrator oder der Benutzer diesen Bereichen vorab zustimmen.
`client_secret`	Manchmal erforderlich	Wenn es sich bei Ihrer App um einen öffentlichen Client handelt, kann `client_secret` oder `client_assertion` nicht eingeschlossen werden. Wenn es sich bei der App um einen vertraulichen Client handelt, muss es eingeschlossen werden.
`client_assertion`	Manchmal erforderlich	Eine andere Form von `client_secret`, die unter Verwendung eines Zertifikats generiert wird. Weitere Informationen finden Sie unter Zertifikatanmeldeinformationen.

Erfolgreiche Authentifizierungsantwort

Das folgende Beispiel stellt eine erfolgreiche Tokenantwort dar:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Parameter	Format	BESCHREIBUNG
`token_type`	String	Immer auf `Bearer` festgelegt.
`scope`	Durch Leerzeichen getrennte Zeichenfolgen	Wenn ein Zugriffstoken zurückgegeben wurde, führt dieser Parameter die Bereiche auf, für die das Zugriffstoken gültig ist.
`expires_in`	INT	Die Anzahl von Sekunden, die das enthaltene Zugriffstoken gültig ist.
`access_token`	Nicht transparente Zeichenfolge	Ausgestellt für die Bereiche, die angefordert wurden.
`id_token`	JWT	Ausgestellt, wenn der ursprüngliche `scope`-Parameter den `openid`-Bereich enthalten hat.
`refresh_token`	Nicht transparente Zeichenfolge	Ausgestellt, wenn der ursprüngliche `scope`-Parameter `offline_access` enthalten hat.

Sie können mit Aktualisierungstoken neue Zugriffstoken und Aktualisierungstoken abrufen. Verwenden Sie den in der Dokumentation für den OAuth-Code beschriebenen Flow.

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.

Fehlerantwort

Wenn der Benutzer nicht den richtigen Benutzernamen bzw. das richtige Kennwort angegeben hat oder der Client nicht über die erforderliche Berechtigung verfügt, schlägt die Authentifizierung fehl.

Fehler	BESCHREIBUNG	Clientaktion
`invalid_grant`	Fehler bei der Authentifizierung	Die Anmeldeinformationen waren falsch oder dem Client fehlt die Berechtigung für die angeforderten Bereiche. Wenn die Bereiche nicht gewährt werden, wird ein Fehler vom Typ `consent_required` zurückgegeben. Zum Beheben dieses Fehlers sollte der Client den Benutzer über eine Webansicht oder einen Browser zu einer interaktiven Eingabeaufforderung weiterleiten.
`invalid_request`	Anforderung war nicht ordnungsgemäß konstruiert	Der Gewährungstyp wird in den Authentifizierungskontexten `/common` oder `/consumers` nicht unterstützt. Verwenden Sie stattdessen `/organizations` oder eine Mandanten-ID.

Weitere Informationen

Ein Beispiel für die Implementierung des ROPC-Flows finden Sie im Codebeispiel .NET-Konsolenanwendung auf GitHub.

Freigeben über