# Control access to REST APIs using Amazon Cognito user pools as an authorizer As an alternative to using [IAM roles and policies](permissions.md) or [Lambda authorizers](apigateway-use-lambda-authorizer.md) (formerly known as custom authorizers), you can use an [Amazon Cognito user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) to control who can access your API in Amazon API Gateway. To use an Amazon Cognito user pool with your API, you must first create an authorizer of the `COGNITO_USER_POOLS` type and then configure an API method to use that authorizer. After the API is deployed, the client must first sign the user in to the user pool, obtain an [identity or access token](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) for the user, and then call the API method with one of the tokens, which are typically set to the request's `Authorization` header. The API call succeeds only if the required token is supplied and the supplied token is valid, otherwise, the client isn't authorized to make the call because the client did not have credentials that could be authorized. The identity token is used to authorize API calls based on identity claims of the signed-in user. The access token is used to authorize API calls based on the custom scopes of specified access-protected resources. For more information, see [Using Tokens with User Pools](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) and [Resource Server and Custom Scopes](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). To create and configure an Amazon Cognito user pool for your API, you perform the following tasks: + Use the Amazon Cognito console, CLI/SDK, or API to create a user pool—or use one that's owned by another AWS account. + Use the API Gateway console, CLI/SDK, or API to create an API Gateway authorizer with the chosen user pool. + Use the API Gateway console, CLI/SDK, or API to enable the authorizer on selected API methods. To call any API methods with a user pool enabled, your API clients perform the following tasks: + Use the Amazon Cognito CLI/SDK or API to sign a user in to the chosen user pool, and obtain an identity token or access token. To learn more about using the SDKs, see [Code examples for Amazon Cognito using AWS SDKs](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html). + Use a client-specific framework to call the deployed API Gateway API and supply the appropriate token in the `Authorization` header. As the API developer, you must provide your client developers with the user pool ID, a client ID, and possibly the associated client secrets that are defined as part of the user pool. **Note** To let a user sign in using Amazon Cognito credentials and also obtain temporary credentials to use with the permissions of an IAM role, use [Amazon Cognito Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html). For each API resource endpoint HTTP method, set the authorization type, category `Method Execution`, to `AWS_IAM`. In this section, we describe how to create a user pool, how to integrate an API Gateway API with the user pool, and how to invoke an API that's integrated with the user pool. **Topics** + [Create an Amazon Cognito user pool for a REST API](apigateway-create-cognito-user-pool.md) + [Integrate a REST API with an Amazon Cognito user pool](apigateway-enable-cognito-user-pool.md) + [Call a REST API integrated with an Amazon Cognito user pool](apigateway-invoke-api-integrated-with-cognito-user-pool.md) + [Configure cross-account Amazon Cognito authorizer for a REST API using the API Gateway console](apigateway-cross-account-cognito-authorizer.md) + [Create an Amazon Cognito authorizer for a REST API using CloudFormation](apigateway-cognito-authorizer-cfn.md) # Create an Amazon Cognito user pool for a REST API Before integrating your API with a user pool, you must create the user pool in Amazon Cognito. Your user pool configuration must follow all [resource quotas for Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/limits.html). All user-defined Amazon Cognito variables such as groups, users, and roles should use only alphanumeric characters. For instructions on how to create a user pool, see [Tutorial: Creating a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) in the *Amazon Cognito Developer Guide*. Note the user pool ID, client ID, and any client secret. The client must provide them to Amazon Cognito for the user to register with the user pool, to sign in to the user pool, and to obtain an identity or access token to be included in requests to call API methods that are configured with the user pool. Also, you must specify the user pool name when you configure the user pool as an authorizer in API Gateway, as described next. If you're using access tokens to authorize API method calls, be sure to configure the app integration with the user pool to set up the custom scopes that you want on a given resource server. For more information about using tokens with Amazon Cognito user pools, see [Using Tokens with User Pools](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). For more information about resource servers, see [Defining Resource Servers for Your User Pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). Note the configured resource server identifiers and custom scope names. You need them to construct the access scope full names for **OAuth Scopes**, which is used by the `COGNITO_USER_POOLS` authorizer. ![\[Amazon Cognito user pool resource servers and scopes\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/cognito-user-pool-custom-scopes-new-console.png) # Integrate a REST API with an Amazon Cognito user pool After creating an Amazon Cognito user pool, in API Gateway, you must then create a `COGNITO_USER_POOLS` authorizer that uses the user pool. The following procedure shows you how to do this using the API Gateway console. **Note** You can use the [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html) action to create a `COGNITO_USER_POOLS` authorizer that uses multiple user pools. You can use up to 1,000 user pools for one `COGNITO_USER_POOLS` authorizer. This limit cannot be increased. **Important** After performing any of the procedures below, you'll need to deploy or redeploy your API to propagate the changes. For more information about deploying your API, see [Deploy REST APIs in API Gateway](how-to-deploy-api.md). **To create a `COGNITO_USER_POOLS` authorizer by using the API Gateway console** 1. Create a new API, or select an existing API in API Gateway. 1. In the main navigation pane, choose **Authorizers**. 1. Choose **Create authorizer**. 1. To configure the new authorizer to use a user pool, do the following: 1. For **Authorizer name**, enter a name. 1. For **Authorizer type**, select **Cognito**. 1. For **Cognito user pool**, choose the AWS Region where you created your Amazon Cognito and select an available user pool. You can use a stage variable to define your user pool. Use the following format for your user pool: `arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}`. 1. For **Token source**, enter **Authorization** as the header name to pass the identity or access token that's returned by Amazon Cognito when a user signs in successfully. 1. (Optional) Enter a regular expression in the **Token validation** field to validate the `aud` (audience) field of the identity token before the request is authorized with Amazon Cognito. Note that when using an access token this validation rejects the request due to the access token not containing the `aud` field. 1. Choose **Create authorizer**. 1. After creating the `COGNITO_USER_POOLS` authorizer, you can test invoke it by supplying an identity token that's provisioned from the user pool. You can't use an access token to test invoke your authorizer. You can obtain this identity token by calling the [Amazon Cognito Identity SDK](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) to perform user sign-in. You can also use the [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) action. If you do not configure any **Authorization scopes**, API Gateway treats the supplied token as an identity token. The preceding procedure creates a `COGNITO_USER_POOLS` authorizer that uses the newly created Amazon Cognito user pool. Depending on how you enable the authorizer on an API method, you can use either an identity token or an access token that's provisioned from the integrated user pool. **To configure a `COGNITO_USER_POOLS` authorizer on methods** 1. Choose **Resources**. Choose a new method or choose an existing method. If necessary, create a resource. 1. On the **Method request** tab, under **Method request settings**, choose **Edit**. 1. For **Authorizer**, from the dropdown menu, select the **Amazon Cognito user pool authorizers** you just created. 1. To use an identity token, do the following: 1. Keep **Authorization Scopes** empty. 1. If needed, in the **Integration request**, add the `$context.authorizer.claims['property-name']` or `$context.authorizer.claims.property-name` expressions in a body-mapping template to pass the specified identity claims property from the user pool to the backend. For simple property names, such as `sub` or `custom-sub`, the two notations are identical. For complex property names, such as `custom:role`, you can't use the dot notation. For example, the following mapping expressions pass the claim's [standard fields](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) of `sub` and `email` to the backend: ``` { "context" : { "sub" : "$context.authorizer.claims.sub", "email" : "$context.authorizer.claims.email" } } ``` If you declared a custom claim field when you configured a user pool, you can follow the same pattern to access the custom fields. The following example gets a custom `role` field of a claim: ``` { "context" : { "role" : "$context.authorizer.claims.role" } } ``` If the custom claim field is declared as `custom:role`, use the following example to get the claim's property: ``` { "context" : { "role" : "$context.authorizer.claims['custom:role']" } } ``` 1. To use an access token, do the following: 1. For **Authorization Scopes**, enter one or more full names of a scope that has been configured when the Amazon Cognito user pool was created. For example, following the example given in [Create an Amazon Cognito user pool for a REST API](apigateway-create-cognito-user-pool.md), one of the scopes is `https://my-petstore-api.example.com/cats.read`. At runtime, the method call succeeds if any scope that's specified on the method in this step matches a scope that's claimed in the incoming token. Otherwise, the call fails with a `401 Unauthorized` response. 1. Choose **Save**. 1. Repeat these steps for other methods that you choose. With the `COGNITO_USER_POOLS` authorizer, if the **OAuth Scopes** option isn't specified, API Gateway treats the supplied token as an identity token and verifies the claimed identity against the one from the user pool. Otherwise, API Gateway treats the supplied token as an access token and verifies the access scopes that are claimed in the token against the authorization scopes declared on the method. Instead of using the API Gateway console, you can also enable an Amazon Cognito user pool on a method by specifying an OpenAPI definition file and importing the API definition into API Gateway. **To import a COGNITO\$1USER\$1POOLS authorizer with an OpenAPI definition file** 1. Create (or export) an OpenAPI definition file for your API. 1. Specify the `COGNITO_USER_POOLS` authorizer (`MyUserPool`) JSON definition as part of the `securitySchemes` section in OpenAPI 3.0 or the `securityDefinitions` section in Open API 2.0 as follows: ------ #### [ OpenAPI 3.0 ] ``` "securitySchemes": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ #### [ OpenAPI 2.0 ] ``` "securityDefinitions": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ 1. To use the identity token for method authorization, add `{ "MyUserPool": [] }` to the `security` definition of the method, as shown in the following GET method on the root resource. ``` "paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": [] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... } ``` 1. To use the access token for method authorization, change the above security definition to `{ "MyUserPool": [resource-server/scope, ...] }`: ``` "paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... } ``` 1. If needed, you can set other API configuration settings by using the appropriate OpenAPI definitions or extensions. For more information, see [OpenAPI extensions for API Gateway](api-gateway-swagger-extensions.md). # Call a REST API integrated with an Amazon Cognito user pool To call a method with a user pool authorizer configured, the client must do the following: + Enable the user to sign up with the user pool. + Enable the user to sign in to the user pool. + Obtain an [identity or access token](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) of the signed-in user from the user pool. + Include the token in the `Authorization` header (or another header you specified when you created the authorizer). You can use [AWS Amplify]() to perform these tasks. See [Integrating Amazon Cognito With Web and Mobile Apps](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) for more information. + For Android, see [Getting Started with Amplify for Android](https://docs.amplify.aws/android/build-a-backend/auth/). + To use iOS see [Getting started with Amplify for iOS](https://docs.amplify.aws/swift/build-a-backend/auth/). + To use JavaScript, see [Getting Started with Amplify for Javascript](https://docs.amplify.aws/javascript/build-a-backend/auth/). # Configure cross-account Amazon Cognito authorizer for a REST API using the API Gateway console You can now also use a Amazon Cognito user pool from a different AWS account as your API authorizer. The Amazon Cognito user pool can use bearer token authentication strategies such as OAuth or SAML. This makes it easy to centrally manage and share a central Amazon Cognito user pool authorizer across multiple API Gateway APIs. In this section, we show how to configure a cross-account Amazon Cognito user pool using the Amazon API Gateway console. These instructions assume that you already have an API Gateway API in one AWS account and a Amazon Cognito user pool in another account. ## Create a cross-account Amazon Cognito authorizer for a REST API Log in to the Amazon API Gateway console in the account that has your API in it, and then do the following: 1. Create a new API, or select an existing API in API Gateway. 1. In the main navigation pane, choose **Authorizers**. 1. Choose **Create authorizer**. 1. To configure the new authorizer to use a user pool, do the following: 1. For **Authorizer name**, enter a name. 1. For **Authorizer type**, select **Cognito**. 1. For **Cognito user pool**, enter the full ARN for the user pool that you have in your second account. **Note** In the Amazon Cognito console, you can find the ARN for your user pool in the **Pool ARN** field of the **General Settings** pane. 1. For **Token source**, enter **Authorization** as the header name to pass the identity or access token that's returned by Amazon Cognito when a user signs in successfully. 1. (Optional) Enter a regular expression in the **Token validation** field to validate the `aud` (audience) field of the identity token before the request is authorized with Amazon Cognito. Note that when using an access token this validation rejects the request due to the access token not containing the `aud` field. 1. Choose **Create authorizer**. # Create an Amazon Cognito authorizer for a REST API using CloudFormation You can use CloudFormation to create an Amazon Cognito user pool and an Amazon Cognito authorizer. The example CloudFormation template does the following: + Create an Amazon Cognito user pool. The client must first sign the user in to the user pool and obtain an [identity or access token](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). If you're using access tokens to authorize API method calls, be sure to configure the app integration with the user pool to set up the custom scopes that you want on a given resource server. + Creates an API Gateway API with a `GET` method. + Creates an Amazon Cognito authorizer that uses the `Authorization` header as the token source. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: UserPool: Type: AWS::Cognito::UserPool Properties: AccountRecoverySetting: RecoveryMechanisms: - Name: verified_phone_number Priority: 1 - Name: verified_email Priority: 2 AdminCreateUserConfig: AllowAdminCreateUserOnly: true EmailVerificationMessage: The verification code to your new account is {####} EmailVerificationSubject: Verify your new account SmsVerificationMessage: The verification code to your new account is {####} VerificationMessageTemplate: DefaultEmailOption: CONFIRM_WITH_CODE EmailMessage: The verification code to your new account is {####} EmailSubject: Verify your new account SmsMessage: The verification code to your new account is {####} UpdateReplacePolicy: Retain DeletionPolicy: Retain CogAuthorizer: Type: AWS::ApiGateway::Authorizer Properties: Name: CognitoAuthorizer RestApiId: Ref: Api Type: COGNITO_USER_POOLS IdentitySource: method.request.header.Authorization ProviderARNs: - Fn::GetAtt: - UserPool - Arn Api: Type: AWS::ApiGateway::RestApi Properties: Name: MyCogAuthApi ApiDeployment: Type: AWS::ApiGateway::Deployment Properties: RestApiId: Ref: Api DependsOn: - CogAuthorizer - ApiGET ApiDeploymentStageprod: Type: AWS::ApiGateway::Stage Properties: RestApiId: Ref: Api DeploymentId: Ref: ApiDeployment StageName: prod ApiGET: Type: AWS::ApiGateway::Method Properties: HttpMethod: GET ResourceId: Fn::GetAtt: - Api - RootResourceId RestApiId: Ref: Api AuthorizationType: COGNITO_USER_POOLS AuthorizerId: Ref: CogAuthorizer Integration: IntegrationHttpMethod: GET Type: HTTP_PROXY Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets Outputs: ApiEndpoint: Value: Fn::Join: - "" - - https:// - Ref: Api - .execute-api. - Ref: AWS::Region - "." - Ref: AWS::URLSuffix - / - Ref: ApiDeploymentStageprod - / ```