Autorisieren des Endpunkts

Der /oauth2/authorize-Endpunkt ist ein Umleitungsendpunkt, der zwei Umleitungsziele unterstützt. Wenn Sie einen identity_provider- oder idp_identifier-Parameter in der URL angeben, werden Ihre Benutzer im Hintergrund auf die Anmeldeseite für diesen Identitätsanbieter (IDP) umgeleitet. Andernfalls erfolgt die Umleitung an Login-Endpunkt mit denselben URL-Parametern, die Sie in Ihre Anfrage aufgenommen haben.

Der Autorisierungs-Endpunkt leitet Benutzer entweder zur gehosteten Benutzeroberfläche oder zu einer IdP-Anmeldeseite weiter. Das Ziel einer Benutzersitzung an diesem Endpunkt ist eine Webseite, mit der Ihr Benutzer direkt in seinem Browser interagieren muss.

Wenn Sie den Autorisierungsendpunkt verwenden möchten, rufen Sie den Browser Ihres Benutzers unter /oauth2/authorize mit Parametern auf, die Ihrem Benutzerpool Informationen zu den folgenden Benutzerpool-Details liefern.

• Der App-Client, bei dem Sie sich anmelden möchten.

• Die Rückruf-URL, zu der Sie gelangen möchten.

• Die OAuth-2.0-Bereiche, die Sie im Zugriffstoken Ihres Benutzers anfordern möchten.

• Optionaler Drittanbieter-IDP, den Sie für die Anmeldung verwenden möchten.

Sie können auch state- und nonce-Parameter angeben, die Amazon Cognito verwendet, um eingehende Ansprüche zu validieren.

GET /oauth2/authorize

Der /oauth2/authorize Endpunkt unterstützt ausschließlich HTTPS GET. Ihre App initiiert diese Anfrage normalerweise im Browser Ihres Benutzers. Sie können nur über HTTPS Anfragen an den /oauth2/authorize-Endpunkt stellen.

Weitere Informationen über die Definition des Autorisierungsendpunkts im OpenID Connect (OIDC)-Standard finden Sie unter Authorisierungsendpunkt.

Anforderungsparameter

response_type

(Erforderlich) Der Antworttyp. Es muss sich entweder um code oder token handeln.

Eine erfolgreiche Anfrage mit einem response_type von code gibt eine Autorisierungscode-Erteilung zurück. Eine Autorisierungscode-Erteilung ist ein code-Parameter, den Amazon Cognito an Ihre Umleitungs-URL anhängt. Ihre App kann den Code durch Zugriffs-, ID- und Aktualisierungstoken austauschen. Verwenden Sie als bewährte Sicherheitsmethode und zum Abrufen von Aktualisierungstoken für Ihre Benutzer eine Autorisierungscode-Erteilung in Ihrer App.

Eine erfolgreiche Anfrage mit dem response_type token gibt eine implizite Erteilung zurück. Eine implizite Erteilung besteht aus einer ID und einem Zugriffstoken, die Amazon Cognito an Ihre Umleitungs-URL anhängt. Eine implizite Erteilung ist weniger sicher, da sie Token und potenzielle identifizierende Informationen für Benutzer verfügbar macht. Sie können die Unterstützung für implizite Erteilungen in der Konfiguration Ihres App-Clients deaktivieren.

client_id

(Erforderlich) Die App-Client-ID.

Der Wert client_id muss die ID eines App-Clients in dem Benutzerpool sein, in dem Sie die Anfrage stellen. Ihr App-Client muss die Anmeldung durch lokale Benutzer von Amazon Cognito oder mindestens eines externen IdPs unterstützen.

redirect_uri

(Erforderlich) Die URL, an die der Authentifizierungsserver den Browser umleitet, nachdem Amazon Cognito den Benutzer autorisiert hat.

Ein Umleitungs-URI (Uniform Resource Identifier) muss die folgenden Attribute aufweisen:

• Es muss ein absoluter URI sein.

• Sie müssen die URI im Vorfeld mit einem Client registriert haben.

• Sie darf keine Fragmentkomponente enthalten.

Weitere Informationen finden Sie unter OAuth 2.0 – redirection endpoint (OAuth 2.0 – Umleitungsendpunkt).

Amazon Cognito erfordert, dass Ihr Umleitungs-URI HTTPS verwendet, mit Ausnahme von http://localhost, was Sie als Rückruf-URL für Testzwecke festlegen können.

Amazon Cognito unterstützt auch App-Callback-URLs wie myapp://example.

state

(Optional, empfohlen) Wenn Ihre App einer Anfrage einen State-Parameter hinzufügt, gibt Amazon Cognito seinen Wert an Ihre App zurück, wenn der /oauth2/authorize Endpunkt Ihren Benutzer weiterleitet.

Fügen Sie diesen Wert Ihren Anfragen hinzu, um sich vor CSRF-Angriffen zu schützen.

Sie können den Wert eines Parameters state nicht auf eine URL-codierte JSON-Zeichenfolge festlegen. Um eine Zeichenfolge, die diesem Format entspricht, in einem state Parameter zu übergeben, kodieren Sie die Zeichenfolge auf Base64 und dekodieren Sie sie dann in Ihrer App.

identity_provider

(Optional) Fügen Sie diesen Parameter hinzu, um die gehostete Benutzeroberfläche zu umgehen und Ihren Benutzer auf eine Anmeldeseite eines Anbieters umzuleiten. Der Wert des identity_provider-Parameters ist der Name des Identitätsanbieters (IDP), wie er in Ihrem Benutzerpool angezeigt wird.

• Für soziale Anbieter können Sie die identity_provider-WerteFacebook,, und Google verwenden. LoginWithAmazon SignInWithApple

• Verwenden Sie für Amazon Cognito Cognito-Benutzerpools den WertCOGNITO.

• Verwenden Sie für SAML 2.0- und OpenID Connect (OIDC-) Identitätsanbieter (IdPs) den Namen, den Sie dem IdP in Ihrem Benutzerpool zugewiesen haben.

idp_identifier

(Optional) Fügen Sie diesen Parameter hinzu, um zu einem Anbieter mit einem alternativen Namen für den Namen identity_provider umzuleiten. Sie können Kennungen für Ihre SAML 2.0 und OIDC auf der Registerkarte Anmeldeerfahrung der Amazon IdPs Cognito Cognito-Konsole eingeben.

scope

(Optional) Kann eine Kombination aus beliebigen systemreservierten Bereichen oder benutzerdefinierten Bereichen sein, die einem Client zugeordnet sind. Bereiche müssen durch Leerzeichen getrennt werden. Für das System reservierte Bereiche sind openidemail, phone, profile und aws.cognito.signin.user.admin. Jeder Bereich muss dem Client zugeordnet werden, sonst wird der Client zur Laufzeit ignoriert.

Falls der Client keine Bereiche anfordert, verwendet der Authentifizierungsserver alle Bereiche im Zusammenhang mit dem Client.

Ein ID-Token wird nur zurückgegeben, wenn der openid-Bereich angefordert wird. Das Zugriffs-Token kann nur gegen Amazon-Cognito-Benutzerpools verwendet werden, wenn der Bereich aws.cognito.signin.user.admin angefordert wird. Die Bereiche phone, email und profile können nur angefordert werden, wenn der Bereich openid ebenfalls angefordert wird. Diese Bereiche bestimmen die Anträge, die im ID-Token eingesetzt werden.

code_challenge_method

(Optional) Das Hashing-Protokoll, mit dem Sie die Herausforderung generiert haben. Die PKCE RFC definiert zwei Methoden, die S256-Methode und eine einfache. Der Amazon-Cognito-Authentifikationsserver unterstützt jedoch nur die S256-Methode.

code_challenge

(Optional) Die Herausforderung, die Sie anhand der code_verifier generiert haben.

Nur erforderlich, wenn Sie einen code_challenge_method-Parameter angeben.

nonce

(Optional) Ein zufälliger Wert, den Sie der Anfrage hinzufügen können. Der von Ihnen bereitgestellte Nonce-Wert ist im ID-Token enthalten, das Amazon Cognito ausgibt. Zum Schutz vor Replay-Angriffen kann Ihre App den nonce-Anspruch im ID-Token untersuchen und mit dem vergleichen, den Sie generiert haben. Weitere Informationen zum nonce-Anspruch finden Sie unter ID-Token-Validierung im OpenID Connect-Standard.

Beispielanfragen mit positiven Antworten

Die folgenden Beispiele veranschaulichen das Format von HTTP-Anfragen an den /oauth2/authorize Endpunkt.

Erteilung des Autorisierungscodes

Dies ist ein Beispiel für eine Anfrage zur Erteilung eines Autorisierungscodes.

Beispiel — GET-Anfrage

Die folgende Anfrage initiiert eine Sitzung zum Abrufen eines Autorisierungscodes, den Ihr Benutzer am redirect_uri Ziel an Ihre App weitergibt. In dieser Sitzung werden Bereiche für Benutzerattribute und für den Zugriff auf Amazon Cognito-Self-Service-API-Operationen angefordert.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin

Beispiel — Antwort

Der Amazon-Cognito-Authentifikationsserver leitet Autorisierungs-Code und -Status zurück an Ihre App. Der Autorisierungscode ist fünf Minuten gültig.

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

Erteilung des Autorisierungscodes mit PKCE

Dies ist ein Beispiel für einen Antrag auf Erteilung eines Autorisierungscodes bei PKCE.

Beispiel — GET-Anfrage

Die folgende Anfrage fügt der vorherigen Anfrage einen code_challenge Parameter hinzu. Um den Austausch eines Codes gegen ein Token abzuschließen, müssen Sie den code_verifier Parameter in Ihre Anfrage für den /oauth2/token Endpunkt aufnehmen.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin&
code_challenge_method=S256&
code_challenge=a1b2c3d4...

Beispiel — Antwort

Der Authentifizierungsserver leitet mit dem Autorisierungscode und dem Status zurück zu Ihrer Anwendung. Der Code und der Status müssen in den Parametern der Abfragezeichenfolge und nicht im Fragment zurückgegeben werden:

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

Token gewähren, ohne openid-Umfang

Dies ist eine Beispielanforderung, die einen impliziten Grant generiert und JWTs direkt an die Sitzung des Benutzers zurückgibt.

Beispiel — GET-Anfrage

Die folgende Anfrage bezieht sich auf eine implizite Erteilung durch Ihren Autorisierungsserver. Das Zugriffstoken von Amazon Cognito autorisiert Self-Service-API-Operationen.

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=token&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin

Beispiel — Antwort

Der Amazon-Cognito-Autorisierungsserver leitet das Zugriffs-Token zurück an Ihre App. Da der openid-Bereich nicht angefordert wurde, gibt Amazon Cognito kein ID-Token aus. Außerdem gibt Amazon Cognito in diesem Flow kein Aktualisierungs-Token aus. Amazon Cognito gibt das Zugriffstoken und den Status im Fragment und nicht in der Abfragezeichenfolge zurück:

HTTP/1.1 302 Found
Location: https://YOUR_APP/redirect_uri#access_token=ACCESS_TOKEN&token_type=bearer&expires_in=3600&state=STATE

Token gewähren, mit openid-Umfang

Dies ist eine Beispielanforderung, die eine implizite Gewährung generiert und JWTs direkt an die Sitzung des Benutzers zurückgibt.

Beispiel — GET-Anfrage

Die folgende Anfrage bezieht sich auf eine implizite Erteilung durch Ihren Autorisierungsserver. Das Zugriffstoken von Amazon Cognito autorisiert den Zugriff auf Benutzerattribute und Self-Service-API-Operationen.

GET
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize? 
response_type=token& 
client_id=1example23456789& 
redirect_uri=https://www.example.com& 
state=abcdefg&
scope=aws.cognito.signin.user.admin+openid+profile
                    

Beispiel — Antwort

Der Autorisierungsserver leitet mit Zugriffstoken und ID-Token zurück zu Ihrer App (da der openid Bereich enthalten war):

HTTP/1.1 302 Found
Location: https://www.example.com#id_token=eyJra67890EXAMPLE&access_token=eyJra12345EXAMPLE&token_type=bearer&expires_in=3600&state=abcdefg

Beispiele für negative Antworten

Amazon Cognito lehnt Ihre Anfrage möglicherweise ab. Negative Anfragen enthalten einen HTTP-Fehlercode und eine Beschreibung, anhand derer Sie Ihre Anforderungsparameter korrigieren können. Im Folgenden finden Sie Beispiele für negative Antworten.

• Wenn client_id und gültig redirect_uri sind, die Anforderungsparameter jedoch nicht korrekt formatiert sind, leitet der Authentifizierungsserver den Fehler an den des Clients weiter redirect_uri und fügt eine Fehlermeldung an einen URL-Parameter an. Im Folgenden finden Sie Beispiele für falsche Formatierungen.

  • Die Anfrage enthält keinen response_type Parameter.

  • Die Autorisierungsanfrage lieferte einen code_challenge Parameter, aber keinen code_challenge_method Parameter.

  • Der Wert des code_challenge_method Parameters ist nichtS256.

  Im Folgenden finden Sie die Antwort auf eine Beispielanfrage mit falscher Formatierung.

  HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request

• Wenn der Client eine Anfrage code oder token eingibtresponse_type, aber keine Genehmigung für diese Anfragen hat, kehrt der Amazon Cognito Cognito-Autorisierungsserver wie folgt unauthorized_client zum Client-Autorisierungsserver zurück: redirect_uri

  HTTP 1.1 302 Found Location: https://client_redirect_uri?error=unauthorized_client

• Falls die Anforderung des Clients unbekannt, falsch formatiert oder ungültig ist, sollte der Amazon-Cognito-Autorisierungsserver invalid_scope folgendermaßen zur redirect_uri des Clients zurückgeben:

  HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_scope

• Wenn auf dem Server ein unerwarteter Fehler auftritt, kehrt der Authentifizierungsserver server_error zum Server des redirect_uri Clients zurück. Da der HTTP 500-Fehler nicht an den Client gesendet wird, wird der Fehler nicht im Browser des Benutzers angezeigt. Der Autorisierungsserver gibt den folgenden Fehler zurück.

  HTTP 1.1 302 Found Location: https://client_redirect_uri?error=server_error

• Wenn Amazon Cognito sich über einen Verbund mit einem Drittanbieter authentifiziert IdPs, kann es bei Amazon Cognito zu Verbindungsproblemen kommen, wie z. B. die folgenden:

  • Wenn es bei der Token-Anforderung vom IdP zu einem Verbindungs-Timeout kommt, leitet der Authentifizierungsserver den Fehler wie folgt an den redirect_uri des Clients weiter:

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Timeout+occurred+in+calling+IdP+token+endpoint

  • Wenn beim Aufrufen des jwks_uri Endpunkts zur Überprüfung des ID-Tokens ein Verbindungs-Timeout auftritt, leitet der Authentifizierungsserver mit einem Fehler wie folgt an den des Clients weiter: redirect_uri

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=error_description=Timeout+in+calling+jwks+uri

• Bei der Authentifizierung über einen Verbund mit einem Drittanbieter IdPs geben die Anbieter möglicherweise Fehlerantworten zurück. Dies kann auf Konfigurationsfehler oder andere Gründe zurückzuführen sein, z. B. auf die folgenden:

  • Wenn eine Fehlermeldung von anderen Anbietern empfangen wird, leitet der Authentifizierungsserver den Fehler wie folgt an den redirect_uri des Clients weiter:

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=[IdP name]+Error+-+[status code]+error getting token

  • Wenn eine Fehlerantwort von Google empfangen wird, leitet der Authentifizierungsserver den Fehler wie folgt an den redirect_uri des Clients weiter:

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Google+Error+-+[status code]+[Google-provided error code]

• Wenn Amazon Cognito bei der Verbindung zu einem externen IdP auf eine Kommunikationsausnahme stößt, leitet der Authentifizierungsserver mit einer der folgenden Meldungen redirect_uri mit einem Fehler an den des Kunden weiter:

  • HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Connection+reset

  • HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Read+timed+out