User Pool Auth API (AWS Guide)

User Pool Auth API

https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-userpools-server-contract-reference.html

Once a domain has been configured for your user pool, Amazon Cognito hosts an authentication server that allows you to add sign-up and sign-in webpages to your app.

This section contains the HTTPS contract to the Amazon Cognito authentication server from a user pool client, including sample requests and responses. It describes the expected behavior from the authentication server for positive and negative conditions.

In addition to the server contract REST API, Amazon Cognito also provides Auth SDKs for Android, iOS, and JavaScript that make it easier to form requests and interact with the server.

AUTHORIZATION Endpoint
https://docs.aws.amazon.com/cognito/latest/developerguide/authorization-endpoint.html

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 a browser. Web browsers include Chrome or Firefox. Android browsers include Custom Chrome Tab. iOS browsers include Safari View Control.

The authorization server requires HTTPS instead of HTTP as the protocol when accessing the authorization endpoint.
- Request Parameters
  ‘response_type’
  
  Required
  
  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).
  
  ‘client_id’
  
  Required
  
  Must be a pre-registered client in the user pool and must be enabled for federation.
  
  ‘redirect_uri’
  Required
  
  The URL to which the authentication server redirects the browser after authorization has been granted by the user. A redirect URI must:
  - Be an absolute URI.
  - Be pre-registered with a client.
  - Not include a fragment component.
  Amazon Cognito requires HTTPS over HTTP except for http://localhost for testing purposes only. App callback URLs such as myapp://example are also supported.
  ‘state’
  
  Optional but recommended
  
  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.
  
  ‘identity_provider’
  Optional
  
  Used by the developer to directly authenticate with a specific provider.
  - For social sign-in the valid values are Facebook, Google, and LoginWithAmazon.
  - For Amazon Cognito user pools, the value is ‘COGNITO’.
  - For other identity providers this would be the name you assigned to the IdP in your user pool.
  ‘idp_identifier’
  
  Optional
  
  Used by the developer to map to a provider name without exposing the provider name.
  
  ‘scope’
  Optional
  
  Can be a combination of any system-reserved scopes or custom scopes associated with a client. Scopes must be separated by spaces. 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.
  
  System reserved scopes are:
  - openid
    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.
  - email
  - phone
  - profile
  - aws.cognito.signin.user.admin
  ‘code_challenge_method’
  
  Optional
  
  The method used to generate the challenge. Amazon Cognito authentication server supports only ‘S256’.
  
  ‘code_challenge’
  
  Required only when the code_challenge_method is specified.
  
  The generated challenge from the code_verifier.
- Example Requests with Positive Responses
  - 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
    
    the part of a web request that appears after a ’?’ character; the string can contain one or more parameters separated by ’&’ characters.
    
    A fragment
    
    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
```
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 Reqponse
    
    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 Responses
  The following are examples of negative responses:
  - 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
```
  - When authenticating by federating to third-party identity providers, Cognito may experience connection issues such as the following:
    - If a connection timeout occurs while requesting token from the identity provider, the authentication server redirects the error to the client’s redirect_uri as follows:
      HTTP 1.1 302 Found Location: https://client_redirect_uri? error=invalid_request& error_description=Timeout+occurred+in+calling+IdP+token+endpoint
    - If a connection timeout occurs while calling jwks endpoint for id_token validation, the authentication server redirects the error to the client’s redirect_uri as follows:
      HTTP 1.1 302 Found Location: https://client_redirect_uri? error=invalid_request& error_description=error_description=Timeout+in+calling+jwks+uri
  - When authenticating by federating to third-party identity providers, the providers may return error responses due to configuration errors or otherwise such as the following:
    - If an error response is received from other providers, the authentication server redirects the error to the client’s redirect_uri as follows:
      HTTP 1.1 302 Found Location: https://client_redirect_uri? error=invalid_request& error_description=[IdP name]+Error+-+[status code]+error getting token
    - If an error response is received from Google, the authentication server redirects the error to the client’s redirect_uri as follows:
      HTTP 1.1 302 Found Location: https://client_redirect_uri? error=invalid_request& error_description=Google+Error+-+[status code]+[Google provided error code]
  - In the rare case where Cognito encounters an exception in the communication protocol while making any connection to an external identity provider, the authentication server redirects the error to the client’s redirect_uri with either of the following messages:
```
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
```
TOKEN Endpoint
USERINFO Endpoint
LOGIN Endpoint
https://docs.aws.amazon.com/cognito/latest/developerguide/login-endpoint.html

The /login endpoint signs the user in. It loads the login page and presents the authentication options configured for the client to the user.

GET /login

The /login endpoint only supports HTTPS GET. The user pool client makes this request through a system browser. System browsers for JavaScript include Chrome or Firefox. Android browsers include Custom Chrome Tab. iOS browsers include Safari View Control.
- Request Parameters
  ‘client_id’
  
  Required. The app client ID for your app. To obtain an app client ID, register the app in the user pool.
  
  ‘redirect_uri’
  
  Required. The URI where the user is redirected after a successful authentication. It should be configured on ‘response_type’ of the specified ‘client_id’.
  
  ‘response_type’
  
  Required. The OAuth response type, which can be code for code grant flow and token for implicit flow.
  
  ‘state’
  Optional but recommended. Can be a combination of any system-reserved scopes or custom scopes associated with a client. Scopes must be separated by spaces. If the client doesn’t request any scopes, the authentication server uses all scopes associated with the client.
  
  System reserved scopes are:
  - openid,
    An ID token is only returned if an ‘openid’ scope is requested. The access token can only be used against Amazon Cognito user pools if an ‘aws.cognito.signin.user.admin’ scope is requested. The ‘phone’, ‘email’, and ‘profile’ scopes can only be requested if an ‘openid’ scope is also requested. These scopes dictate the claims that go inside the ID token.
  - email,
  - phone,
  - profile, and
  - aws.cognito.signin.user.admin.
  Any scope used must be preassociated with the client or it is ignored at runtime.
  Sample Request
  
  This example displays the login screen.
```
GET https://mydomain.auth.us-east-1.amazoncognito.com/login?
response_type=code&
client_id=ad398u21ijw3s9w3939&
redirect_uri=https://YOUR_APP/redirect_uri&
state=STATE&
scope=openid+profile+aws.cognito.signin.user.admin
```
LOGOUT Endpoint

User Pool Auth API

Sample Request

Sample Response

Sample Request

Sample Response

Sample Request

Sample Response

Sample Request

Sample Reqponse

GET /login

Sample Request