OAuth 2.0 scopes and API authorization with resource servers - Amazon Cognito

OAuth 2.0 scopes and API authorization with resource servers

After you configure a domain for your user pool, Amazon Cognito automatically provisions an OAuth 2.0 authorization server and a hosted web UI with sign-up and sign-in pages that your app can present to your users. For more information see Add an app client and set up the hosted UI. You can choose the scopes that you want the authorization server to add to access tokens. Scopes authorize access to resource servers and user data.

A resource server is an OAuth 2.0 API server. To secure access-protected resources, it validates that access tokens from your user pool contain the scopes that authorize the requested method and path in the API that it protects. It verifies the issuer based on the token signature, validity based on token expiration time, and access level based on the scopes in token claims. User pools present scopes in the access-token claim scope. For more information about the claims in Amazon Cognito access tokens, see Using the access token.

Whether your users are local to your user pool or third-party, and whether they authenticate with the hosted UI or in the Amazon Cognito user pools API, your user profile can generate access tokens with scopes that authorize your app to work with user attributes.

About scopes

A scope is a level of access that an app can request to a resource. In an Amazon Cognito access token, the scope is backed up by the trust that you set up with your user pool: a trusted issuer of access tokens with a known digital signature. User pools can generate access tokens with scopes that prove your customer is allowed to manage some or all of their own user profile, or to retrieve data from a back-end API. Amazon Cognito user pools issue access tokens with the user pools reserved API scope, custom scopes, and standard scopes.

The user pools reserved API scope

The aws.cognito.signin.user.admin scope authorizes the Amazon Cognito user pools API. It authorizes the bearer of an access token to query and update all information about a user pool user with, for example, the GetUser and UpdateUserAttributes API operations. When you authenticate your user with the Amazon Cognito user pools API, this is the only scope you receive in the access token. It's also the only scope you need to read and write user attributes that you've authorized your app client to read and write. You can also request this scope in requests to your Authorize endpoint. This scope alone isn't sufficient to request user attributes from the UserInfo endpoint. For access tokens that authorize both user pools API and userInfo requests for your users, you must request both of the scopes openid and aws.cognito.signin.user.admin in an /oauth2/authorize request.

Custom scopes

Custom scopes authorize requests to the external APIs that resource servers protect. You can request custom scopes with other types of scopes. You can find more information about custom scopes throughout this page.

Standard scopes

When you authenticate users with your user pool OAuth 2.0 authorization server, including with the hosted UI, you must request scopes. You can authenticate user pool local users and third-party federated users in your Amazon Cognito authorization server. Standard OAuth 2.0 scopes authorize your app to read user information from the UserInfo endpoint of your user pool. The OAuth model, where you query user attributes from the userInfo endpoint, can optimize your app for a high volume of requests for user attributes. The userInfo endpoint returns attributes at a permission level that's determined by the scopes in the access token. You can authorize your app client to issue access tokens with the following standard OAuth 2.0 scopes.

openid

The minimum scope for OpenID Connect (OIDC) queries. Authorizes the ID token, the unique-identifier claim sub, and the ability to request other scopes.

Note

When you request the openid scope and no others, your user pool ID token and userInfo response include claims for all user attributes that your app client can read. When you request openid and other standard scopes like profile, email, and phone, the contents of the ID token and userInfo response are limited to the constraints of the additional scopes.

For example, a request to the Authorize endpoint with the parameter scope=openid+email returns an ID token with sub, email, and email_verified. The access token from this request returns the same attributes from UserInfo endpoint. A request with parameter scope=openid returns all client-readable attributes in the ID token and from userInfo.

profile

Authorizes all user attributes that the app client can read.

email

Authorizes the user attributes email and email_verified. Amazon Cognito returns email_verified if it has had a value explicitly set.

phone

Authorizes the user attributes phone_number and phone_number_verified.

About resource servers

A resource server API might grant access to the information in a database, or control your IT resources. An Amazon Cognito access token can authorize access to APIs that support OAuth 2.0. Amazon API Gateway REST APIs have built-in support for authorization with Amazon Cognito access tokens. Your app passes the access token in the API call to the resource server. The resource server inspects the access token to determine if access should be granted.

Amazon Cognito might make future updates to the schema of user pool access tokens. If your app analyzes the contents of the access token before it passes it to an API, you must engineer your code to accept updates to the schema.

Custom scopes are defined by you, and extend the authorization capabilities of a user pool to include purposes unrelated to querying and modifying users and their attributes. For example, if you have a resource server for photos, it might define two scopes: photos.read for read access to the photos and photos.write for write/delete access. You can configure an API to accept access tokens for authorization, and grant HTTP GET requests to access tokens with photos.read in the scope claim, and HTTP POST requests to tokens with photos.write. These are custom scopes.

Note

Your resource server must verify the access token signature and expiration date before processing any claims inside the token. For more information about verifying tokens, see Verifying a JSON Web Token. For more information about verifying and using user pool tokens in Amazon API Gateway, see the blog Integrating Amazon Cognito User Pools with API Gateway. API Gateway is a good option for inspecting access tokens and protecting your resources. For more about API Gateway Lambda authorizers, see Use API Gateway Lambda authorizers.

Overview

With Amazon Cognito, you can create OAuth 2.0 Resource servers and associate Custom scopes with them. Custom scopes in an access token authorize specific actions in your API. You can authorize any app client in your user pool to issue custom scopes from any of your resource servers. Associate your custom scopes with an app client and request those scopes in OAuth 2.0 authorization code grants, implicit grants, and client credentials grants from the Token endpoint. Amazon Cognito adds custom scopes to the scope claim in an access token. A client can use the access token against its resource server, which makes the authorization decision based on the scopes present in the token. For more information about access token scope, see Using Tokens with User Pools.


                An overview of the flow of a resource server. The client requests a grant
                    with a custom scope, the user pool returns an access token with the custom
                    scope, and the client presents the access token to an API.

To get an access token with custom scopes, your app must make a request to the Token endpoint to redeem an authorization code or to request a client credentials grant. In the hosted UI, you can also request custom scopes in an access token from an implicit grant.

Note

Because they are designed for human-interactive authentication with the user pool as the IdP, InitiateAuth and AdminInitiateAuth requests only produce a scope claim in the access token with the single value aws.cognito.signin.user.admin.

Managing the Resource Server and Custom Scopes

When creating a resource server, you must provide a resource server name and a resource server identifier. For each scope you create in the resource server, you must provide the scope name and description.

  • Resource server name: A friendly name for the resource server, such as Solar system object tracker or Photo API.

  • Resource server identifier: A unique identifier for the resource server. The identifier is any name that you want to associate with your API, for example solar-system-data. You can configure longer identifiers like https://solar-system-data-api.example.com as a more direct reference to API URI paths, but longer strings increase the size of access tokens.

  • Scope name: The value that you want in your scope claims. For example, sunproximity.read.

  • Description: A friendly description of the scope. For example, Check current proximity to sun.

Amazon Cognito can include custom scopes in access tokens for any users, whether they are local to your user pool or federated with a third-party identity provider. You can choose scopes for your users' access tokens during authentication flows with the OAuth 2.0 authorization server that includes the hosted UI. Your user's authentication must begin at the Authorize endpoint with scope as one of the request parameters. The following is a recommended format for resource servers. For an identifier, use an API friendly name. For a custom scope, use the action that they authorize.

resourceServerIdentifier/scopeName

For example, you've discovered a new asteroid in the Kuiper belt and you want to register it through your solar-system-data API. The scope that authorizes write operations to the database of asteroids is asteroids.add. When you request the access token that will authorize you to register your discovery, format your scope HTTPS request parameter as scope=solar-system-data/asteroids.add.

Deleting a scope from a resource server does not delete its association with all clients. Instead, the scope is marked inactive. Amazon Cognito doesn't add inactive scopes to access tokens, but otherwise proceeds as normal if your app requests one. If you add the scope to your resource server again later, then Amazon Cognito again writes it to the access token. If you request a scope that you haven't associated with your app client, regardless of whether you deleted it from your user pool resource server, authentication fails.

You can use the AWS Management Console, API, or CLI to define resource servers and scopes for your user pool.

Defining a resource server for your user pool (AWS Management Console)

You can use the AWS Management Console to define a resource server for your user pool.

To define a resource server
  1. Sign in to the Amazon Cognito console.

  2. In the navigation pane, choose User Pools, and choose the user pool you want to edit.

  3. Choose the App integration tab and locate Resource servers.

  4. Choose Create a resource server.

  5. Enter a Resource server name. For example, Photo Server.

  6. Enter a Resource server identifier. For example, com.example.photos.

  7. Enter Custom scopes for your resources, such as read and write.

  8. For each Scope name, enter a Description, such as view your photos and update your photos.

  9. Choose Create.

Your custom scopes can be reviewed in the App integration tab under Resource servers, in the Custom scopes column. Custom scopes can be enabled for app clients from the App integration tab under App clients. Select an app client, locate Hosted UI settings and choose Edit. Add Custom scopes and choose Save changes.

Defining a resource server for your user pool (AWS CLI and AWS API)

Use the following commands to specify resource server settings for your user pool.

To create a resource server
To get information about your resource server settings
To list information about all resource servers for your user pool
To delete a resource server
To update the settings for a resource server