Microsoft Identity Platform und OAuth 2.0-Kennwortanmeldeinformationen des Ressourcenbesitzers

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:

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.