Teilen über

Microsoft Identity Platform und OAuth 2.0-Kennwortanmeldeinformationen des Ressourcenbesitzers

  • Artikel

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 MSALverwenden.

Warnung

Microsoft empfiehlt, den ROPC-Flow nicht zu verwenden; er ist nicht mit der Multi-Faktor-Authentifizierung (MFA) kompatibel. In den meisten Szenarien sind sicherere Alternativen verfügbar und empfohlen. Dieser Fluss erfordert ein sehr hohes Vertrauen in die Anwendung und trägt Risiken, die in anderen Flüssen nicht vorhanden sind. Sie sollten diesen Fluss nur verwenden, wenn sicherere Flüsse nicht lebensfähig sind.

Wichtig

  • Microsoft Identity Platform unterstützt die ROPC-Zuweisung nur bei Microsoft Entra-Mandanten, nicht für persönliche Konten. Dies bedeutet, dass Sie einen mandantenspezifischen Endpunkt (https://login.microsoftonline.com/{TenantId_or_Name}) oder den organizations-Endpunkt verwenden müssen.
  • Persönliche Konten, die zu einem Microsoft Entra-Mandanten eingeladen werden, können den ROPC-Flow nicht verwenden.
  • Konten, die nicht über Kennwörter verfügen, können sich nicht mit ROPC anmelden, was bedeutet, dass Features wie SMS-Anmeldung, FIDO und die Authenticator-App nicht mit diesem Fluss funktionieren. Wenn Ihre App oder Benutzer diese Features benötigen, verwenden Sie einen anderen Grant-Typ als ROPC.
  • Wenn Benutzer die Multi-Faktor-Authentifizierung (MFA) verwenden müssen, um sich bei der Anwendung anzumelden, werden Sie stattdessen blockiert.
  • ROPC wird in Hybrididentitätsverbund Szenarien nicht unterstützt (z. B. Microsoft Entra ID und AD FS, die zum Authentifizieren lokaler Konten verwendet werden). Wenn Benutzer auf der ganzen Seite zu einem lokalen Identitätsanbieter umgeleitet werden, kann Die Microsoft Entra-ID den Benutzernamen und das Kennwort für diesen Identitätsanbieter nicht 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 ältere Anwendungen.
  • Kennwörter mit führenden oder nachfolgenden Leerzeichen werden vom ROPC-Fluss nicht unterstützt.

So migrieren Sie von ROPC

Da MFA häufiger wird, akzeptieren einige Microsoft-Web-APIs nur Zugriffstoken, wenn sie MFA-Anforderungen bestanden haben. Anwendungen und Prüfstände, die auf ROPC vertrauen, werden gesperrt. Microsoft Entra gibt das Token nicht aus, oder die Ressource lehnt die Anforderung ab.

Wenn Sie ROPC zum Abrufen von Token zum Aufrufen geschützter downstreamer APIs verwenden, migrieren Sie zu einer sicheren Tokenakquisitionsstrategie.

Wenn der Benutzerkontext verfügbar ist

Wenn ein Endbenutzer auf eine Ressource zugreifen muss, sollte die Clientanwendung, die in ihrem Auftrag fungiert, eine Form der interaktiven Authentifizierung verwenden. Der Endbenutzer kann nur für MFA herausgefordert werden, wenn er im Browser dazu aufgefordert wird.

  • Für Webanwendungen:
  • Web-APIs können keinen Browser anzeigen. Stattdessen müssen sie ein Captcha zurück an die Clientanwendung zurückgeben. Ausführliche Informationen finden Sie unter Web-APIs und zu Nutzerherausforderungen in Web-APIs.
  • Desktopanwendungen sollten die brokerbasierte Authentifizierung verwenden. Broker verwenden browserbasierte Authentifizierung, sodass sie MFA erzwingen und die sicherste Sicherheitslage aktivieren können.
  • Mobile Anwendungen sollten auch für die Verwendung der brokerbasierten Authentifizierung (Authenticator, Unternehmensportal) konfiguriert werden.

Wenn der Benutzerkontext nicht verfügbar ist

Beispiele für Szenarien, in denen kein Benutzerkontext beteiligt ist, sind insbesondere Folgende:

  • Ein Skript, das als Teil einer CI-Pipeline ausgeführt wird.
  • Ein Dienst, der eine Ressource im Namen von sich selbst aufrufen muss, ohne Benutzerdetails.

Anwendungsentwickler sollten die Dienstprinzipalauthentifizierungverwenden, die in den Beispielen für Daemonsveranschaulicht wird. MFA gilt nicht für Dienstprinzipale.

Es gibt mehrere Möglichkeiten, sich als Dienstprinzipal zu authentifizieren:

  • Wenn Ihre App in der Azure-Infrastruktur ausgeführt wird, verwenden Sie managed Identity. Die verwaltete Identität beseitigt den Aufwand für das Verwalten und Rotieren von geheimen Schlüsseln und Zertifikaten.
  • Wenn Ihre App auf einem System ausgeführt wird, das von einem anderen OAuth2-kompatiblen Identitätsanbieter wie GitHub verwaltet wird, verwenden Sie Verbundidentitätsanmeldeinformationen.
  • Wenn Sie keine verwaltete Identität oder eine Verbundidentität verwenden können, verwenden Sie einen Zertifikatnachweis.

Warnung

Verwenden Sie die Dienstprinzipalauthentifizierung nicht, wenn ein Benutzerkontext verfügbar ist. Der ausschließlich App-basierte Zugriff ist inhärent hochprivilegiert, gewährt häufig mandantenweiten Zugriff und ermöglicht möglicherweise einem böswilligen Akteur, auf die Kundendaten jedes Benutzers zuzugreifen.

Protokolldiagramm

Das folgende Diagramm zeigt den ROPC-Fluss.

Diagramm mit dem Kennwortfluss des Ressourcenbesitzers

Autorisierungsanforderung

Der ROPC-Fluss ist eine einzige Anfrage; er sendet die Clientidentifikation und die Anmeldeinformationen des Benutzers an den Identitätsanbieter und empfängt Token im Gegenzug. Der Client muss die E-Mail-Adresse (UPN) und das Kennwort des Benutzers anfordern, bevor dies geschieht. Unmittelbar nach einer erfolgreichen Anforderung sollte der Client die Anmeldeinformationen des Benutzers sicher aus dem Arbeitsspeicher verwerfen. Er muss sie nie 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 Zustand Beschreibung
tenant Erforderlich Der Verzeichnismandant, bei dem Sie den Benutzer anmelden möchten. Der Mandant kann im GUID-Format oder als Anzeigename bereitgestellt werden. Der Parameter kann jedoch nicht auf common oder consumersfestgelegt werden, kann jedoch auf organizationsfestgelegt werden.
client_id Erforderlich Die Anwendungs-ID (Client-ID), die Ihrer App auf der Seite Microsoft Entra Admin Center – App-Registrierungen zugewiesen ist.
grant_type Erforderlich Muss auf passwordfestgelegt 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 Ablauf muss der Administrator oder der Benutzer diesen Bereichen im Voraus zustimmen.
client_secret Manchmal erforderlich Wenn Ihre App ein öffentlicher Client ist, können die client_secret oder client_assertion nicht einbezogen werden. Wenn es sich bei der App um einen vertraulichen Client handelt, muss sie einbezogen werden.
client_assertion Manchmal erforderlich Eine andere Form von client_secret, die mit einem Zertifikat 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 Schnur Immer auf Bearer festgelegt.
scope Durch Leerzeichen getrennte Zeichenfolgen Wenn ein Zugriffstoken zurückgegeben wurde, listet dieser Parameter die Bereiche auf, für die das Zugriffstoken gültig ist.
expires_in INT Die Anzahl der Sekunden, für die das enthaltene Zugriffstoken gültig ist.
access_token Nicht transparente Zeichenfolge Ausgestellt für die Bereiche, die angefordert wurden.
id_token JWT Wird ausgegeben, wenn der ursprüngliche scope Parameter den openid Bereich enthält.
refresh_token undurchsichtige Zeichenfolge Wird ausgegeben, wenn der ursprüngliche Parameter scopeoffline_accessenthält.

Sie können das Aktualisierungstoken verwenden, um neue Zugriffstoken und Aktualisierungstoken zu erwerben, indem Sie denselben Fluss verwenden, der in der OAuth-Codeflussdokumentationbeschrieben ist.

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.

Fehlerantwort

Wenn der Benutzer nicht den richtigen Benutzernamen oder das richtige Kennwort angegeben hat oder der Client die angeforderte Zustimmung nicht erhalten hat, schlägt die Authentifizierung fehl.

Fehler Beschreibung Clientaktion
invalid_grant Fehler bei der Authentifizierung Die Anmeldeinformationen waren falsch, oder der Client hat keine Zustimmung für die angeforderten Bereiche. Wenn die Bereiche nicht gewährt werden, wird ein Fehler vom Typ consent_required zurückgegeben. Um diesen Fehler zu beheben, sollte der Client den Benutzer über eine Webview oder einen Browser an eine interaktive Eingabeaufforderung senden.
invalid_request Die Anforderung wurde nicht ordnungsgemäß erstellt. Der Grant-Typ wird in den Authentifizierungskontexten /common und /consumers nicht unterstützt. Verwenden Sie stattdessen /organizations oder eine Mandanten-ID.

Weitere Informationen

Eine Beispielimplementierung des ROPC-Flusses finden Sie in der .NET-Konsolenanwendung Codebeispiel auf GitHub.