OAuth 2.0 grants - Amazon Cognito

OAuth 2.0 grants

The Amazon Cognito user pool OAuth 2.0 authorization server issues tokens in response to three types of OAuth 2.0 authorization grants. You can set the supported grant types for each app client in your user pool. You can't enable client credentials grants in the same app client as either implicit or authorization code grants. Requests for implicit and authorization code grants begin at your Authorize endpoint and requests for client credentials grants start at your Token endpoint.

Authorization code grant

In response to your successful authentication request, the authorization server appends an authorization code in a code parameter to your callback URL. You must then exchange the code for ID, access, and refresh tokens with the Token endpoint. To request an authorization code grant, set response_type to code in your request. For an example request, see Authorization code grant.

The authorization code grant is the most secure form of authorization grant. It doesn't show token contents directly to your users. Instead, your app is responsible for retrieving and securely storing your user's tokens. In Amazon Cognito, an authorization code grant is the only way to get all three token types—ID, access, and refresh—from the authorization server. You can also get all three token types from authentication through the Amazon Cognito user pools API, but the API doesn't issues access tokens with scopes other than aws.cognito.signin.user.admin.

Implicit grant

In response to your successful authentication request, the authorization server appends an access token in an access_token parameter, and an ID token in an id_token parameter, to your callback URL. An implicit grant requires no additional interaction with the Token endpoint. To request an implicit grant, set response_type to token in your request. The implicit grant only generates an ID and access token. For an example request, see Token grant without openid scope.

The implicit grant is a legacy authorization grant. Unlike with the authorization code grant, users can intercept and inspect your tokens. To prevent token delivery through implicit grant, configure your app client to support authorization code grant only.

Client credentials

Client credentials is an authorization-only grant for machine-to-machine access. To receive a client credentials grant, bypass the Authorize endpoint and generate a request directly to the Token endpoint. Your app client must have a client secret and support client credentials grants only. In response to your successful request, the authorization server returns an access token.

The access token from a client credentials grant is an authorization mechanism that contains OAuth 2.0 scopes. Typically, the token contains custom scope claims that authorize HTTP operations to access-protected APIs. For more information, see Scopes, M2M, and API authorization with resource servers.

Client credentials grants add costs to your AWS bill. For more information, see Amazon Cognito Pricing.

For more perspective on these grants and their implementation, see How to use OAuth 2.0 in Amazon Cognito: Learn about the different OAuth 2.0 grants in the AWS Security Blog.