OAuth2 API Endpoints

 

Warning

This is still work in progress while the Cognito Service is being implemented and integrated with the Front End Application.

OAuth2 Endpoints

AWS Cognito provides several key OAuth 2.0 endpoints that your application will interact with during the authentication and authorization process. These endpoints are typically hosted on your Cognito User Pool domain.

Note

• Cognito Domain: Replace <cognito-domain> with <partition>-<infrastructure>.auth.<region>.amazoncognito.com.
• Region & User Pool ID: Replace and with the specific AWS region and User Pool ID for the JWKS URI.
• HTTPS: All these endpoints must be accessed over HTTPS.
• App Client Configuration: Ensure App Client in Cognito is correctly configured with the appropriate callback URLs, sign-out URLs, allowed OAuth flows (e.g., Authorization Code Grant, Implicit Grant), and allowed OAuth scopes.

Cognito domain Structure: https://<partition>-<infrastructure>.auth.<region>.amazoncognito.com

Note

The <partition>-<infrastructure> string is available as a CloudFormation Export with name <infrastructure>-<partition>-API-UserPoolDomain.

Main Endpoints.

• Authorization Endpoint (/oauth2/authorize)
  • URL Structure: https://<cognito-domain>/oauth2/authorize
  • partition: This is the endpoint where your application redirects the user’s browser to initiate the sign-in process. The user authenticates with Cognito here and grants (or denies) the requested permissions (scopes) to your application.
  • Common Parameters:
    • response_type: Specifies the type of grant requested (e.g., code for Authorization Code Grant, token for Implicit Grant).
    • client_id: The App Client ID of your application registered with Cognito.
    • redirect_uri: The URL in your application where Cognito should redirect the user after authentication. This must match one of the callback URLs configured in your App Client settings.
    • scope: A space-separated list of OAuth scopes being requested (e.g., openid profile email aws.cognito.signin.user.admin).
    • state: An opaque value used to maintain state between the request and the callback and to prevent CSRF attacks.
    • code_challenge (for PKCE): The code challenge derived from the code verifier.
    • code_challenge_method (for PKCE): The method used to derive the code challenge (e.g., S256).
• Token Endpoint (/oauth2/token)**
  • URL Structure: https://<cognito-domain>/oauth2/token
  • partition: After successful authentication and authorization (if using the Authorization Code Grant), your application makes a backend POST request to this endpoint to exchange an authorization code for ID, access, and refresh tokens. It’s also used for the Refresh Token Grant to get new access/ID tokens.
  • Common Parameters (for Authorization Code Grant):
    • grant_type: Set to authorization_code.
    • code: The authorization code received from the /oauth2/authorize redirect.
    • client_id: Your App Client ID.
    • redirect_uri: The same redirect URI used in the authorization request.
    • code_verifier (for PKCE): The plain text secret generated by the client.
  • Common Parameters (for Refresh Token Grant):
    • grant_type: Set to refresh_token.
    • refresh_token: The refresh token.
    • client_id: Your App Client ID.
  • Authentication: This endpoint typically requires client authentication (e.g., using client ID and client secret in the Authorization header or request body if the app client is configured with a secret).
• UserInfo Endpoint (/oauth2/userInfo)
  • URL Structure: https://<cognito-domain>/oauth2/userInfo
  • partition: Your application can make a GET or POST request to this endpoint, including a valid access token in the Authorization: Bearer header, to retrieve information (claims) about the authenticated user. The claims returned depend on the scopes associated with the access token.
  • Authentication: Requires a valid Access Token.
• JWKS (JSON Web Key Set) URI (/.well-known/jwks.json)
  • URL Structure: https://cognito-idp.<your-region>.amazonaws.com/<user-pool-id>/.well-known/jwks.json
  • partition: This endpoint provides the public keys that can be used to verify the signature of the JSON Web Tokens (JWTs) – specifically the ID token and access token – issued by your Cognito User Pool. Your application should fetch and cache these keys to validate tokens locally.
• Logout Endpoint (/logout)
  • URL Structure: https://<cognito-domain>/logout
  • partition: Redirecting the user’s browser to this endpoint logs them out of the Cognito session.
  • Common Parameters:
    • client_id: Your App Client ID.
    • logout_uri: The URL where Cognito should redirect the user after they have been logged out. This must match one of the sign-out URLs configured in your App Client settings.
    • response_type: Often code or token depending on desired flow post-logout, though typically just a redirect is sufficient.

Additional Endpoints

• OpenID Connect Discovery Endpoint (/.well-known/openid-configuration)

  • URL Structure: https://<cognito-domain>/.well-known/openid-configuration

    Alternatively, for User Pools (more common for client-side discovery): https://cognito-idp.<your-region>.amazonaws.com/<user-pool-id>/.well-known/openid-configuration

  • partition: This is a standard OpenID Connect (OIDC) metadata endpoint. It returns a JSON document containing important information about your Cognito User Pool’s OIDC configuration. This includes the URLs for the authorization endpoint, token endpoint, userinfo endpoint, JWKS URI, supported scopes, supported response types, supported claims, and other configuration details. Client libraries often use this endpoint to automatically configure themselves.
  • Revocation Endpoint (/oauth2/revoke)
  • URL Structure: https://<cognito-domain>/oauth2/revoke
  • partition: This endpoint is used to invalidate (revoke) an OAuth 2.0 refresh token or, in some OAuth 2.0 implementations (though less common for Cognito’s primary use case), an access token. When a refresh token is revoked, it can no longer be used to obtain new access tokens.
  • Common Parameters:
    • token: The refresh token (or access token) to be revoked.
    • client_id: Your App Client ID.
    • client_secret (if your app client has a secret): The client secret.
  • Authentication: Typically requires client authentication.
  • Hosted UI Paths for Specific Actions (Sign-up, Forgot Password, etc.)

  While the /oauth2/authorize endpoint is the primary entry for authentication, the Cognito Hosted UI has specific paths for user self-service actions. Users are often directed to these from the main sign-in page presented by the authorize endpoint.

  • partition: These allow users to sign up for new accounts, reset forgotten passwords, and confirm their accounts directly through the Hosted UI.
  • Examples (relative to your Cognito domain):
    • /signup?client_id=...&response_type=...&redirect_uri=...
    • /forgotPassword?client_id=...&response_type=...&redirect_uri=...
    • /confirmUser?client_id=...
  • Device Authorization Grant Endpoints (if using this flow)
    This is a less common flow for typical web/mobile apps but is available.
  • Device Authorization Endpoint: https://<cognito-domain>/oauth2/device_authorization
    • partition: Used by devices with limited input capabilities to initiate an authorization flow. The device requests a device_code, user_code, and verification_uri.
  • Token Endpoint (for Device Code grant type): https://<cognito-domain>/oauth2/token
    • Partition: The device polls this endpoint with the device_code and grant_type=urn:ietf:params:oauth:grant-type:device_code after the user has authorized the device on a separate browser using the verification_uri and user_code.

Required Endpoints for M2M scenario

• Token Endpoint

  • Path: /oauth2/token
  • Method: POST
  • Headers:
    • Content-Type: application/x-www-form-urlencoded

    • Authorization: Basic <base64_encoded_client_id:client_secret>

      To construct this:

      1. concatenate <app_client_id>:<app_client_secret>
      2. Base64 encode the resulting string.
      3. Prefix the encoded string with Basic (note the space).

      Alternatively, some implementations allow sending client_id and client_secret in the request body if not using the Basic Auth header, but Basic Auth is standard. Cognito supports both.

  • Body: (form-urlencoded):
    • grant_type: Must be set to client_credentials.
    • scope (Optional but Recommended): A space-separated list of OAuth scopes your application is requesting. These scopes must be allowed for the App Client in your Cognito User Pool configuration (under “Allowed OAuth Scopes”). If you don’t specify scopes, Cognito will grant all scopes allowed for that app client.
    • client_id (If not using Basic Auth header): Your App Client ID.
    • client_secret (If not using Basic Auth header and your app client has a secret): Your App Client Secret.
  • Successful Response (JSON):
    • access_token: The access token that your application can use to call protected APIs.
    • expires_in: The lifetime of the access token in seconds (e.g., 3600 for 1 hour).
    • token_type: Typically Bearer.
  • Error Response (JSON):
    • error: An error code (e.g., invalid_client, invalid_request, unauthorized_client).
    • error_description (Optional): A human-readable description of the error.
  • Other Related Endpoints (setup, verification)
  • JWKS URI. (see above)
  • OpenId Connect Discovery Endpoint (See Above).

Amplify Configuration

For Amplify Applications, the settings take advantage of direct integration with Cognito by requiring only to provide:

• Cognito User Pool ID: Provided by the Partition under the CloudFormation Export <infrastructure>-<partition>-API-UserPoolId.
• Cognito App Client ID: Provided by the Partition under the CloudFormation Export <infrastructure>-<partition>-API-WebClientId.

Comments