API authorization with resource servers and OAuth 2.0 scopes
After you configure a domain for your user pool, Amazon Cognito automatically provisions 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.
A resource server is an OAuth 2.0 API
server
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 app should treat the access token as opaque when it passes the token in the access request. The resource server inspects the access token to determine if access should be granted.
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 and using
user pool tokens, see Integrating Amazon Cognito User Pools with API Gateway
A scope is a level of access that an app can request to a resource.
The aws.cognito.signin.user.admin
scope authorizes the bearer of an access
token to query and update information about a user pool user. When you authenticate with a
third-party IdP, the standard scopes that Amazon Cognito can include in your access token are an
upper limit to the user information you can query from the IdP. You can authorize your app
client to issue access tokens with the following standard OAuth 2.0 scopes.
- openid
-
A mandatory scope for OpenID Connect (OIDC) queries. Authorizes the unique-identifier claim
sub
. - profile
-
Authorizes the standard claims
name
,family_name
,given_name
,middle_name
,nickname
,preferred_username
,profile
,picture
,website
,gender
,birthdate
,zoneinfo
,locale
, andupdated_at
. -
Authorizes the claim
email
. - phone
-
Authorizes the claim
phone_number
. - aws.cognito.signin.user.admin
-
Authorizes all token-authorized Amazon Cognito user pools API operations.
You can also add your own scopes to a user pool. 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.
Resource server 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.

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.
Example:
-
Resource server name: A friendly name for the resource server, such as
Weather API
orPhoto API
. -
Resource server identifier: A unique identifier for the resource server. This can be your own custom string or a reference to the URL path of your API. For example,
my-weather-api
orhttps://my-weather-api.example.com
. -
Scope name: The value that you want in your
scope
claims. For example,weather.read
. -
Description: A friendly description of the scope. For example,
Retrieve weather information
.
Amazon Cognito can include custom scopes in access tokens for any users, whether local or federated
with a third-party identity provider. Your user's authentication must begin at the Authorize endpoint or the Login endpoint with scope
as one
of the request parameters. To request a custom scope, format its value as follows.
resourceServerIdentifier
/scopeName
For example, if the resource server identifier is
https://myphotosapi.example.com
and the scope name is
photos.read
, request
scope=https://myphotosapi.example.com/photos.read
.
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
-
Sign in to the Amazon Cognito console
. -
In the navigation pane, choose User Pools, and choose the user pool you want to edit.
-
Choose the App integration tab and locate Resource servers.
-
Choose Create a resource server.
-
Enter a Resource server name. For example,
Photo Server
. -
Enter a Resource server identifier. For example,
com.example.photos
. -
Enter Custom scopes for your resources, such as
read
andwrite
. -
For each Scope name, enter a Description, such as
view your photos
andupdate your photos
. -
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
-
AWS CLI:
aws cognito-idp create-resource-server
-
AWS API: CreateResourceServer
To get information about your resource server settings
-
AWS CLI:
aws cognito-idp describe-resource-server
-
AWS API: DescribeResourceServer
To list information about all resource servers for your user pool
-
AWS CLI:
aws cognito-idp list-resource-servers
-
AWS API: ListResourceServers
To delete a resource server
-
AWS CLI:
aws cognito-idp delete-resource-server
-
AWS API: DeleteResourceServer
To update the settings for a resource server
-
AWS CLI:
aws cognito-idp update-resource-server
-
AWS API: UpdateResourceServer