OAuth 2.0-Autorisierungscodeerteilung

Der OAuth 2.0-Autorisierungscode gewährt Anmeldungen in einem Benutzer und ruft Token mit delegierten Berechtigungen ab. Der Benutzer meldet sich über einen Browser an, Microsoft Entra ID einen kurzlebigen Autorisierungscode zurückgibt, und der Client löst den Code am Tokenendpunkt ein.

Eine Agent-ID-Lösung kann die Erteilung auf zwei Arten verwenden:

Clienttyp Typische Rolle Clientanmeldeinformationen PKCE
Öffentlicher Client Ein lokaler Agent meldet sich direkt beim Benutzer an. No Required
Vertraulicher Client Ein serverseitiger Webclient meldet sich beim Benutzer an, bevor er einen gehosteten Agent aufruft. Yes Empfohlen

Verwenden Sie Microsoft Authentication Library (MSAL) (MSAL) oder Microsoft. Identity.Web statt diese Anforderungen direkt zu erstellen. Die Anforderungen in diesem Artikel zeigen die Protokollfelder für die Referenz.

Warning

Microsoft empfiehlt die Verwendung der genehmigten SDKs wie Microsoft. Identity.Web- und Microsoft Entra ID Auth SDK-Bibliotheken (Sidecar) zum Implementieren dieser Protokolle. Die manuelle Implementierung dieser Protokolle ist komplex und fehleranfällig, und die Verwendung der SDKs trägt dazu bei, Sicherheit und Compliance mit bewährten Methoden sicherzustellen.

Important

Unterstützung der Agent-ID für öffentliche Clients befindet sich in der Vorschau. Diese Vorschau wird ohne Vereinbarung auf Serviceebene bereitgestellt und wird für Produktionsworkloads nicht empfohlen. Einige Features werden möglicherweise nicht unterstützt oder verfügen über eingeschränkte Funktionen. Weitere Informationen finden Sie unter "Universelle Lizenzbedingungen für Onlinedienste".

Autorisierungsanforderung

Beide Clienttypen senden den Benutzer an den Autorisierungsendpunkt des Mandanten:

GET https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize?
    client_id={client-id}
    &response_type=code
    &redirect_uri={encoded-redirect-uri}
    &response_mode=query
    &scope=openid%20profile%20offline_access%20api://{resource-client-id}/{scope}
    &state={random-state}
    &nonce={random-nonce}
    &code_challenge={pkce-challenge}
    &code_challenge_method=S256
  • client_id identifiziert den öffentlichen oder vertraulichen Client. Ein CIMD-basierter öffentlicher Client verwendet seine HTTPS-Metadatendokument-URL als Client-ID.
  • redirect_uri muss genau mit einem für den Client konfigurierten Umleitungs-URI übereinstimmen.
  • scope enthält die delegierten Berechtigungen, die der Client anfordert. Lassen Sie den Ressourcenbereich aus, wenn sich der Client nur beim Benutzer anmelden muss.
  • state bindet die Antwort an die initiierende Sitzung und verhindert websiteübergreifende Anforderungsverfälschungen.
  • nonce bindet ein OpenID Connect-ID-Token an die initiierende Sitzung.
  • code_challenge wird mithilfe von SHA-256 von einem PKCE-Prüfer mit hoher Entropie abgeleitet.

Nach der Anmeldung und Zustimmung leitet Microsoft Entra ID den Browser an den registrierten Umleitungs-URI um:

GET {redirect-uri}?code={authorization-code}&state={state}

Bevor Sie den Code einlösen, überprüfen state und behandeln Sie alle OAuth-Fehler, die an den Umleitungs-URI zurückgegeben wurden.

Anforderung für öffentliches Clienttoken

Ein öffentlicher Client kann keine Clientanmeldeinformationen schützen. Er löst den Code mithilfe der PKCE-Prüfer ein:

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

client_id={agent-id-client-id-or-cimd-url}
&grant_type=authorization_code
&code={authorization-code}
&redirect_uri={redirect-uri}
&scope=openid profile offline_access api://{resource-client-id}/{scope}
&code_verifier={pkce-verifier}

Senden Sie in dieser Anforderung keinen geheimen Clientschlüssel, keine Zertifikat assertion oder Verbundanmeldeinformationen.

Eine registrierte PUBLIC-Client-Agent-ID muss den Einzelinstanzmodus verwenden. Ein Client, der ein Client-ID-Metadatendokument verwendet, kann die HTTPS-URL des Dokuments als Client-ID verwenden. Anleitungen zur Implementierung finden Sie unter Anmelden von Benutzern von einem lokalen Agent.

Vertrauliche Clienttokenanforderung

Ein vertraulicher Client wird auf einem Server ausgeführt, der Anmeldeinformationen schützen kann. Der Server, nicht der Browsercode, löst den Autorisierungscode ein. Die Anforderung enthält eine Clientanmeldeinformationen und die PKCE-Prüfer, wenn die Autorisierungsanforderung PKCE verwendet hat:

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

client_id={confidential-client-id}
&grant_type=authorization_code
&code={authorization-code}
&redirect_uri={redirect-uri}
&scope=openid profile offline_access api://{agent-blueprint-client-id}/{scope}
&code_verifier={pkce-verifier}
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={signed-client-assertion}

Im Beispiel wird eine zertifikatbasierte Client assertion verwendet. Ein geheimer Clientschlüssel wird auch unterstützt, aber verwenden Sie nach Möglichkeit ein Zertifikat oder einen Workload-Identitätsverbund.

In einer gehosteten Agent-ID-Lösung ist der vertrauliche Client normalerweise die upstream-Webanwendung, nicht die untergeordnete Agent-ID. Fordern Sie ein Zugriffstoken an, dessen Zielgruppe der Blueprint des gehosteten Agents ist, senden Sie dieses Zugriffstoken an die Agent-API, und verwenden Sie den On-Behalf-Of-Fluss , um nachgeschaltete APIs aufzurufen.

Bei einer Einzelinstanz-Agentidentität (Vorschau) wird die Client-ID bezeichnet, <agent-blueprint-client-id> die von der Blueprint- und Agent-Identität gemeinsam genutzt wird. Bei einer Flotte wird die Client-ID des Blueprints und nicht die ID eines einzelnen untergeordneten Agents bezeichnet. Konfigurieren Sie für den Einzelinstanzmodus die Genehmigung des Upstreamclients durch Erteilen des upstream-Clientzugriffs vor der Anmeldung; Die Browser-Zustimmung unterstützt die Agentidentität nicht als Ressource.

Senden Sie keinen Autorisierungscode oder ein ID-Token an die gehostete Agent-API. Untergeordnete Agent-IDs im vertraulichen Clientmuster initiieren keine interaktive /authorize Anforderung.

Tokenantwort

Wenn die Anforderung erfolgreich ist, gibt Microsoft Entra ID Token zurück, z. B.:

{
  "token_type": "Bearer",
  "scope": "api://<resource-client-id>/<scope>",
  "expires_in": 3599,
  "access_token": "<access-token>",
  "refresh_token": "<refresh-token>",
  "id_token": "<id-token>"
}

Die genaue Antwort hängt von den angeforderten Bereichen ab:

  • Verwenden Sie das Zugriffstoken nur mit der Ressource, die durch ihren aud Anspruch identifiziert wird.
  • Verwenden Sie das ID-Token, um die Anmeldesitzung des Benutzers einzurichten und keine API aufzurufen.
  • Ein Aktualisierungstoken wird zurückgegeben, wenn die Anforderung und Richtlinie den Offlinezugriff zulassen.

Sicherheitsanforderungen

  • Verwenden Sie PKCE mit der S256 Herausforderungsmethode für öffentliche Clients. Verwenden Sie PKCE auch für vertrauliche Clients, wenn die Bibliothek sie unterstützt.
  • Stimmen Sie den Umleitungs-URI genau in den Autorisierungs- und Tokenanforderungen ab.
  • Generieren Sie für jede Autorisierungsanforderung einen neuen state, nonceund PKCE-Prüfer.
  • Lösen Sie einen Autorisierungscode nur einmal und nur vom Client ein, der die Anforderung gestartet hat.
  • Protokollieren Sie keine Autorisierungscodes, Clientanmeldeinformationen, Zugriffstoken, Aktualisierungstoken oder ID-Token.
  • Überprüfen Sie Zugriffstoken in der API. Behandeln Sie den Besitz eines Autorisierungscodes oder ID-Tokens nicht als API-Autorisierung.