Menu
Sign In to the Console
Amazon Cognito
Developer Guide

AWS Documentation » Amazon Cognito » Developer Guide » Amazon Cognito API References » Amazon Cognito User Pools Auth API Reference » AUTHORIZATION Endpoint

AUTHORIZATION Endpoint

The /oauth2/authorize endpoint signs the user in.

GET /oauth2/authorize

The /oauth2/authorize endpoint only supports HTTPS GET. The user pool client typically makes this request through the system browser, which would typically be Custom Chrome Tab in Android and Safari View Control in iOS.

Request Parameters

response_type

The response type. Must be code or token. Indicates whether the client wants an authorization code (authorization code grant flow) for the end user or directly issues tokens for end user (implicit flow).

Required

client_id

The Client ID.

Must be a pre-registered client in the user pool and must be enabled for federation.

Required

redirect_uri

The URL to which the authentication server redirects the browser after authorization has been granted by the user.

Must have been pre-registered with a client.

Required

state

An opaque value the clients adds to the initial request. The authorization server includes this value when redirecting back to the client.

This value must be used by the client to prevent CSRF attacks.

Optional but strongly recommended.

identity_provider

Used by the developer to directly authenticate with a specific provider.

Optional

idp_identifier

Used by the developer to map to a provider name without exposing the provider name.

Optional

scope

Can be a combination of any system-reserved scopes or custom scopes associated with a client. Scopes must be separated by spaces. System reserved scopes are openid, email, phone, profile, and aws.cognito.signin.user.admin. Any scope used must be preassociated with the client or it will be ignored at runtime.

If the client doesn't request any scopes, the authentication server uses all scopes associated with the client.

An ID token is only returned if openid scope is requested. The access token can be only used against Amazon Cognito User Pools if aws.cognito.signin.user.admin scope is requested. The phone, email, and profile scopes can only be requested if openid scope is also requested. These scopes dictate the claims that go inside the ID token.

Optional

code_challenge_method

The method used to generate the challenge. The PKCE RFC defines two methods, S256 and plain; however, Amazon Cognito authentication server supports only S256.

Optional

code_challenge

The generated challenge from the code_verifier.

Required only when the code_challenge_method is specified.

Examples of Positive Requests

Authorization Code Grant

Sample Request

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

Sample Response

The Amazon Cognito authentication server redirects back to your app with the authorization code and state. The code and state must be returned in the query string parameters and not in the fragment. A query string is the part of a web request that appears after a '?' character; the string can contain one or more parameters separated by '&' characters. A fragment is the part of a web request that appears after a '#' character to specify a subsection of a document. 

HTTP/1.1 302 Found
Location: https://YOUR_APP/redirect_uri?code=AUTHORIZATION_CODE&state=STATE

Authorization Code Grant with PKCE

Sample Request

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=ad398u21ijw3s9w3939&
redirect_uri=https://YOUR_APP/redirect_uri&
state=STATE&
scope=aws.cognito.signin.user.admin&
code_challenge_method=S256&
code_challenge=CODE_CHALLENGE

Sample Response

The authentication server redirects back to your app with the authorization code and state. The code and state must be returned in the query string parameters and not in the fragment. 

HTTP/1.1 302 Found
Location: https://YOUR_APP/redirect_uri?code=AUTHORIZATION_CODE&state=STATE

Token grant without openid scope

Sample Request

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

Sample Response

The Amazon Cognito authorization server redirects back to your app with access token. Since openid scope was not requested, an ID token is not returned. A refresh token is never returned in this flow. Token and state are returned in the fragment and not in the query string. 

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

Token grant with openid scope

Sample Request

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

Sample Response

The authorization server redirects back to your app with access token and ID token (because openid scope was included). 

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

Examples of Negative Requests

The following are examples of negative requests:

  • If client_id and redirect_uri are valid but there are other problems with the request parameters (for example, if response_type is not included; if code_challenge is supplied but code_challenge_method is not supplied; or if code_challenge_method is not 'S256'), the authentication server redirects the error to client's redirect_uri.

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

  • If the client requests 'code' or 'token' in response_type but does not have permission for these requests, the Amazon Cognito authorization server should return unauthorized_client to client's redirect_uri, as follows:

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

  • If the client requests invalid, unknown, malformed scope, the Amazon Cognito authorization server should return invalid_scope to the client's redirect_uri, as follows:

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

  • If there is any unexpected error in the server, the authentication server should return server_error to client's redirect_uri. It should not be the HTTP 500 error displayed to the end user in the browser, because this error doesn't get sent to the client. The following error should return:

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

On this page: