# Integrating Amazon Cognito authentication and authorization with web and mobile apps
Integrating with apps

Implementation of Amazon Cognito is a mix of AWS Management Console or AWS SDK administrative tools, and SDK libraries in applications. The Amazon Cognito console is the visual interface for setup and management of your Amazon Cognito user pools and identity pools.

The lowest-effort integration you can create with Amazon Cognito user pools is with [managed login](cognito-terms.md#terms-managedlogin). Managed login is a ready-to-use web-based sign-in application for quick testing and deployment of Amazon Cognito user pools. User pool authentication with managed login requires OpenID Connect (OIDC) libraries that direct users to hosted sign-in pages. In this series of user-interactive and redirect web endpoints, Amazon Cognito handles the flow of authentication, including third-party sign-in, multi-factor authentication (MFA), and choosing an authentication flow. Your application only has to process the authentication outcome that Amazon Cognito returns in the response.

You can also add an AWS SDK to your application, custom-build authentication interfaces, and invoke API operations for authentication and authorization of your users. [AWS Amplify](https://docs.amplify.aws/) is an AWS service for building full-stack applications, with Amazon Cognito authentication in the back end.

For example, your app might invoke managed login for user sign-in, then call the token endpoint from your app code to exchange your user's authorization code for tokens. Then your app must interpret and store your user's tokens, and present them in the appropriate context for authentication and authorization. Amplify adds guided integration tools with built-in functions for these processes.

You can also build your Amazon Cognito resources entirely in code. Identity pools don't have the same managed authentication options as user pools—for access to AWS credentials in your applications, implement identity pools operations in imported SDK modules. To get started with your own custom-built application code, visit the Amazon Cognito [code examples](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html) for [AWS SDKs](https://aws.amazon.com/developer/tools/). For integration with the Amazon Cognito as an OpenID Connect identity provider, use [OpenID Connect developer tools](https://openid.net/certified-open-id-developer-tools/).

Before you use Amazon Cognito authentication and authorization, choose an app platform and prepare your code to integrate with the service. For available platforms for AWS SDKs, see [Authentication with AWS SDKs](#amazon-cognito-authentication-with-sdks). The AWS CLI is a command-line SDK for Amazon Cognito and other AWS services, and is a valuable place to begin to familiarize yourself with Amazon Cognito API operations and their syntax.

**Note**  
Some components of Amazon Cognito can be configured only with the API. For example, you can only set a user pool [custom SMS or email sender](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-custom-sender-triggers.html) Lambda trigger with a request that updates the `LambdaConfig` property of the [UserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UserPoolType.html) class in a [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) or [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) API request.

The Amazon Cognito user pools API shares its namespace with several classes of API operations. One class configures user pools and their processes, identity providers and users. Another includes unauthenticated operations for your users in a public client to sign in, sign out, and manage their profiles. The final class of API operations performs user operations that you authorize with your own AWS credentials in a confidential server-side client. You must know your intended app architecture before you begin to implement app code. For more information, see [Understanding API, OIDC, and managed login pages authentication](authentication-flows-public-server-side.md#user-pools-API-operations).

**Topics**
+ [

## Authentication with AWS Amplify
](#cognito-integrate-apps-amplify)
+ [

## Authentication with AWS SDKs
](#amazon-cognito-authentication-with-sdks)
+ [

# How authentication works with Amazon Cognito
](cognito-how-to-authenticate.md)
+ [

# Using this service with an AWS SDK
](sdk-general-information-section.md)
+ [

# Authorization with Amazon Verified Permissions
](amazon-cognito-authorization-with-avp.md)

## Authentication with AWS Amplify


AWS Amplify is a complete solution for building web and mobile applications. With Amplify, you can connect to existing resources with the Amplify libraries, or you can create and configure new resources with the Amplify command line interface (CLI). Amplify also has connected UI components like [Authenticator](https://ui.docs.amplify.aws/react/connected-components/authenticator) for setup and customization of the sign-in and sign-up experience in your app.

To use Amplify authentication features in your front-end app, see the following documentation by platform.
+ [Amplify authentication for React](https://docs.amplify.aws/react/start/)
+ [Amplify authentication for React Native](https://docs.amplify.aws/react-native/start/)
+ [Amplify authentication for Swift (iOS)](https://docs.amplify.aws/swift/start/)
+ [Amplify authentication for Android](https://docs.amplify.aws/android/start/)
+ [Amplify authentication for Flutter](https://docs.amplify.aws/flutter/start/)

The Amplify libraries are open source and are available on [GitHub](https://github.com/aws-amplify). To learn more about how Amplify Auth implements Amazon Cognito authentication, visit the following libraries.
+ [amplify-js](https://github.com/aws-amplify/amplify-js/tree/main/packages/auth)
+ [amplify-swift](https://github.com/aws-amplify/amplify-swift/tree/main/Amplify/Categories/Auth)
+ [amplify-flutter](https://github.com/aws-amplify/amplify-flutter/tree/main/packages/auth)
+ [amplify-android](https://github.com/aws-amplify/amplify-android/tree/main/aws-auth-cognito)

### Creating a user interface (UI) with Amplify


[User pool managed login](cognito-user-pools-managed-login.md) can fulfill the essential needs of an authentication front-end for a web or mobile app. To customize your user interface (UI) beyond the parameters that managed login accommodates, custom-build an application. [Amplify UI](https://ui.docs.amplify.aws/) is a customizable collection of front-end components in a variety of languages.

![\[A screenshot of an example Amplify Authenticator application.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/amplify-authenticator-ui.png)


To get started with your custom authentication component, visit the following documentation for the Authenticator component.
+ [Authenticator for Android](https://ui.docs.amplify.aws/android/connected-components/authenticator)
+ [Authenticator for Angular](https://ui.docs.amplify.aws/angular/connected-components/authenticator)
+ [Authenticator for Flutter](https://ui.docs.amplify.aws/flutter/connected-components/authenticator)
+ [Authenticator for React](https://ui.docs.amplify.aws/react/connected-components/authenticator)
+ [Authenticator for React Native](https://ui.docs.amplify.aws/react-native/connected-components/authenticator)
+ [Authenticator for Swift](https://ui.docs.amplify.aws/swift/connected-components/authenticator)
+ [Authenticator for Vue](https://ui.docs.amplify.aws/vue/connected-components/authenticator)

## Authentication with AWS SDKs


To use a secure backend to build your own identity microservice that interacts with Amazon Cognito, connect to the Amazon Cognito user pools and Amazon Cognito identity pools API with an AWS SDK in the language of your choice.

For details on each API operation, see the [Amazon Cognito user pools API Reference](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_Operations.html) and the [Amazon Cognito API Reference](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/Welcome.html). These documents contain [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html#API_InitiateAuth_SeeAlso](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html#API_InitiateAuth_SeeAlso) sections with resources for using a variety of SDKs in supported platforms.
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/index.html#cli-aws-cognito-idp)
+ [AWS SDK for .NET](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CognitoIdentityProvider/TCognitoIdentityProviderClient.html)
+ [AWS SDK for C\$1\$1](https://sdk.amazonaws.com/cpp/api/LATEST/aws-cpp-sdk-cognito-idp/html/class_aws_1_1_cognito_identity_provider_1_1_cognito_identity_provider_client.html)
+ [AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go/api/service/cognitoidentityprovider/#CognitoIdentityProvider)
+ [AWS SDK for Java V2](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cognitoidentityprovider/CognitoIdentityProviderClient.html)
+ [AWS SDK for JavaScript](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityServiceProvider.html)
+ [AWS SDK for PHP V3](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.CognitoIdentityProvider.CognitoIdentityProviderClient.html)
+ [AWS SDK for Python](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/cognito-idp.html)
+ [AWS SDK for Ruby V3](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/CognitoIdentityProvider/Client.html)

# How authentication works with Amazon Cognito
How authentication works

When your customer signs in to an Amazon Cognito user pool, your application receives JSON web tokens (JWTs).

When your customer signs in to an identity pool, either with a user pool token or another provider, your application receives temporary AWS credentials.

With user pool sign-in, you can implement authentication and authorization entirely with an AWS SDK. If you don't want to build your own user interface (UI) components, you can invoke a prebuilt web UI (managed login) or the sign-in page for your third-party identity provider (IdP). 

This topic is an overview of some of the ways that your application can interact with Amazon Cognito to authenticate with ID tokens, authorize with access tokens, and access AWS services with identity pool credentials.

**Topics**
+ [

## User pool authentication with managed login
](#cognito-authentication-concepts-managed-login)
+ [

## User pool API authentication and authorization with an AWS SDK
](#cognito-authentication-concepts-apiauth)
+ [

## User pool authentication with a third-party identity provider
](#cognito-authentication-concepts-thirdparty)
+ [

## Identity pool authentication
](#cognito-authentication-concepts-identitypools)

## User pool authentication with managed login
Managed login authentication

[Managed login](cognito-user-pools-managed-login.md) is a website that is linked to your user pool and app client. It can perform sign-in, sign-up, and password-reset operations for your users. An application with a managed login component for authentication can require less developer effort to implement. An application can skip UI components for authentication and invoke managed login webpages in the user's browser. 

Applications collect users' JWTs with a web or app redirect location. Applications that implement managed login can connect to user pools for authentication as if they were an OpenID Connect (OIDC) IdP.

Managed login fits the model where applications require the authentication services of an OIDC authorization server, but don't immediately require features like custom authentication, identity pools integration, or user attribute self-service. When you want to use some of these advanced options, you can implement them with a user pools component for an SDK. 

Managed login and third-party IdP authentication models, with a primary reliance on OIDC implementation, are best for advanced authorization models with OAuth 2.0 scopes.

The following diagram illustrates a typical sign-in session for managed login authentication.

![\[A flowchart that shows an application that prompts a user for input and signs them in with managed login.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/authentication-managed-login.png)


**Managed login authentication flow**

1. A user accesses your application.

1. They select a "Sign in" link.

1. The application directs the user to a sign-in prompt in the managed login pages of your user pool domain.

1. They enter their username and password.

1. The user pool validates the user's credentials and determines that the user has activated multi-factor authentication (MFA).

1. The managed login page prompts the user to enter an MFA code.

1. The user enters their MFA code.

1. Your user pool redirects the user to the application URL.

1. The application collects the authorization code from the URL request parameter that managed login appended to the [callback URL](cognito-terms.md#term-callbackurl).

1. The application requests tokens with the authorization code.

1. The token endpoint returns JWTs to the application.

1. The application decodes, validates, and stores or caches the user's JWTs.

1. The application displays the requested access-controlled component.

1. The user views their content.

1. Later, the user's access token has expired, and they request to view an access-controlled component.

1. The application determines that the user's session should persist. It requests new tokens from the token endpoint with the refresh token.

**Variants and customization**  
You can customize the look and feel of your managed login pages with the [branding editor](managed-login-brandingeditor.md) for your entire user pool, or at the level of any [app client](cognito-terms.md#term-appclient). You can also [configure app clients](user-pool-settings-client-apps.md) with their own identity providers, scopes, access to user attributes, and advanced security configuration.

**Related resources**
+ [User pool managed login](cognito-user-pools-managed-login.md)
+ [Scopes, M2M, and resource servers](cognito-user-pools-define-resource-servers.md)
+ [User pool endpoints and managed login reference](cognito-userpools-server-contract-reference.md)

## User pool API authentication and authorization with an AWS SDK
SDK authentication

AWS has developed components for Amazon Cognito user pools, or *Amazon Cognito identity provider*, in [a variety of developer frameworks](cognito-integrate-apps.md#amazon-cognito-authentication-with-sdks). The methods built into these SDKs call the [Amazon Cognito user pools API](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/Welcome.html). The same user pools API namespace has operations for configuration of user pools and for user authentication. For a more thorough overview, see [Understanding API, OIDC, and managed login pages authentication](authentication-flows-public-server-side.md#user-pools-API-operations).

API authentication fits the model where your applications have existing UI components and primarily rely on the user pool as a user directory. This design adds Amazon Cognito as a component within a larger application. It requires programmatic logic to handle complex chains of challenge and response. 

This application doesn't need to implement a full OpenID Connect (OIDC) relying party implementation. Instead, it has the ability to decode and use JWTs. When you want access to the full set of user pool features for [local users](cognito-terms.md#terms-localuser), build your authentication with the Amazon Cognito SDK in your development environment.

API authentication with custom OAuth scopes is less oriented toward external API authorization. To add custom scopes to an access token from API authentication, modify the token at runtime with a [Pre token generation Lambda trigger](user-pool-lambda-pre-token-generation.md).

The following diagram illustrates a typical sign-in session for API authentication.

![\[A flowchart that shows an application that prompts a user for input and signs them in with an AWS SDK.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/authentication-api.png)


**API authentication flow**

1. A user accesses your application.

1. They select a "Sign in" link.

1. They enter their username and password.

1. The application invokes the method that makes an [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API request. The request passes the user's credentials to a user pool.

1. The user pool validates the user's credentials and determines that the user has activated multi-factor authentication (MFA).

1. The user pool responds with a challenge that requests an MFA code.

1. The application generates a prompt that collects the MFA code from the user.

1. The application invokes the method that makes a [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) API request. The request passes the user's MFA code.

1. The user pool validates the user's MFA code.

1. The user pool responds with the user's JWTs.

1. The application decodes, validates, and stores or caches the user's JWTs.

1. The application displays the requested access-controlled component.

1. The user views their content.

1. Later, the user's access token has expired, and they request to view an access-controlled component.

1. The application determines that the user's session should persist. It invokes the [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) method again with the refresh token and retrieves new tokens.

**Variants and customization**  
You can augment this flow with additional challenges—for example, your own custom authentication challenges. You can automatically restrict access for users whose passwords have been compromised, or whose unexpected sign-in characteristics might indicate a malicious sign-in attempt. This flow looks much the same for operations to sign up, update user attributes, and reset passwords. Most of these flows have duplicate public (client-side) and confidential (server-side) API operations.

**Related resources**
+ [Amazon Cognito user pools API](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/Welcome.html)
+ [Getting started with user pools](getting-started-user-pools.md)
+ [Integrating Amazon Cognito authentication and authorization with web and mobile apps](cognito-integrate-apps.md)
+ [Understanding API, OIDC, and managed login pages authentication](authentication-flows-public-server-side.md#user-pools-API-operations)

## User pool authentication with a third-party identity provider
Third-party identity provider authentication

Sign-in with an external identity provider (IdP), or *federated authentication*, is a similar model to [managed login](#cognito-authentication-concepts-managed-login). Your application is an OIDC relying party to your user pool, while your user pool serves as a passthrough to an IdP. The IdP can be a consumer user directory like Facebook or Google, or it can be a SAML 2.0 or OIDC enterprise directory like Azure. 

Instead of managed login in the user's browser, your application invokes a redirect endpoint on the user pool [authorization server](cognito-terms.md#term-authzserver). From the user's view, they choose the sign-in button in your application. Then their IdP prompts them to sign in. Like with managed login authentication, an application collects JWTs at a redirect location in the app.

Authentication with a third-party IdP fits a model where users might not want to come up with a new password when they sign up for your application. Third-party authentication can be added with low effort to an application that's implemented managed login authentication. In effect, managed login and third-party IdPs produce a consistent authentication outcome from minor variations in what you invoke in users' browsers. 

Like managed login authentication, federated authentication is best for advanced authorization models with OAuth 2.0 scopes.

The following diagram illustrates a typical sign-in session for federated authentication.

![\[A flowchart that shows an application that prompts a user for input and signs them in with a third-party IdP.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/authentication-federated.png)


**Federated authentication flow**

1. A user accesses your application.

1. They select a "Sign in" link.

1. The application directs the user to a sign-in prompt with their IdP.

1. They enter their username and password.

1. The IdP validates the user's credentials and determines that the user has activated multi-factor authentication (MFA).

1. The IdP prompts the user to enter an MFA code.

1. The user enters their MFA code.

1. The IdP redirects the user to the user pool with a SAML response or an authorization code.

1. If the user passed an authorization code, the user pool silently exchanges the code for IdP tokens. The user pool validates the IdP tokens and redirects the user to the application with a new authorization code.

1. The application collects the authorization code from the URL request parameter that the user pool appended to the [callback URL](cognito-terms.md#term-callbackurl).

1. The application requests tokens with the authorization code.

1. The token endpoint returns JWTs to the application.

1. The application decodes, validates, and stores or caches the user's JWTs.

1. The application displays the requested access-controlled component.

1. The user views their content.

1. Later, the user's access token has expired, and they request to view an access-controlled component.

1. The application determines that the user's session should persist. It requests new tokens from the token endpoint with the refresh token.

**Variants and customization**  
You can initiate federated authentication in [managed login](#cognito-authentication-concepts-managed-login), where users can choose from a list of IdPs that you assigned to your [app client](cognito-terms.md#term-appclient). Managed login can also prompt for an email address and [automatically route a user's request](cognito-user-pools-managing-saml-idp-naming.md) to the corresponding SAML IdP. Authentication with a third-party identity provider doesn't *require* user interaction with managed login. Your application can add a request parameter to a user's [authorization server request](cognito-terms.md#term-authorizationserver) and cause the user to silently redirect to their IdP sign-in page.

**Related resources**
+ [User pool sign-in with third party identity providers](cognito-user-pools-identity-federation.md)
+ [Scopes, M2M, and resource servers](cognito-user-pools-define-resource-servers.md)
+ [User pool endpoints and managed login reference](cognito-userpools-server-contract-reference.md)

## Identity pool authentication


An identity pool is a component for your application that is distinct from a user pool in function, API namespace, and SDK model. Where user pools offer token-based authentication and authorization, identity pools offer authorization for AWS Identity and Access Management (IAM).

You can assign a set of IdPs to identity pools and sign in users with them. User pools are closely integrated as identity pool IdPs and give identity pools the most options for access control. At the same time, there is a wide selection of authentication options for identity pools. User pools join SAML, OIDC, social, developer, and guest identity sources as routes to temporary AWS credentials from identity pools. 

Authentication with an identity pool is external—it follows one of the previously illustrated user pool flows, or a flow that you develop independently with another IdP. After your application performs initial authentication, it passes the proof to an identity pool and receives a temporary session in return.

Authentication with an identity pool fits a model where you enforce the access control for application assets and data in AWS services with IAM authorization. Like with [API authentication in user pools](#cognito-authentication-concepts-apiauth), a successful application includes AWS SDKs for each of the services that you want to access for your users' benefit. AWS SDKs apply the credentials from identity pool authentication as signatures to API requests.

The following diagram illustrates a typical sign-in session for identity pool authentication with an IdP.

![\[A flowchart that shows an application that prompts a user for input and signs them in with a third-party IdP.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/authentication-identity-pool.png)


**Identity pool authentication flow**

1. A user accesses your application.

1. They select a "Sign in" link.

1. The application directs the user to a sign-in prompt with their IdP.

1. They enter their username and password.

1. The IdP validates the user's credentials.

1. The IdP redirects the user to the application with a SAML response or an authorization code.

1. If the user passed an authorization code, the application exchanges the code for IdP tokens.

1. The application decodes, validates, and stores or caches the user's JWTs or assertion.

1. The application invokes the method that makes a [GetId](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_GetId.html) API request. It passes the user's token or assertion and requests an identity ID.

1. The identity pool validates the token or assertion against configured identity providers.

1. The identity pool returns an identity ID.

1. The application invokes the method that makes a [GetCredentialsForIdentity](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_GetCredentialsForIdentity.html) API request. It passes the user's token or assertions and requests an IAM role.

1. The identity pool generates a new JWT. The new JWT contains claims that request an IAM role. The identity pool determines the role based on the user's request and the role-selection criteria in the identity pool configuration for the IdP.

1. AWS Security Token Service (AWS STS) responds to the [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) request from the identity pool. The response contains API credentials for a temporary session with an IAM role.

1. The application stores the session credentials.

1. The user takes an action in the app that requires access-protected resources in AWS.

1. The application applies the temporary credentials as [signatures](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) to API requests for the required AWS services.

1. IAM evaluates the policies attached to the role in the credentials. It compares them to the request.

1. The AWS service returns the requested data.

1. The application renders the data in the user's interface.

1. The user views the data.

**Variants and customization**  
To visualize authentication with a user pool, insert one of the previous user-pool overviews after the **Issue token/assertion** step. Developer authentication replaces all steps before **Request identity** with a request signed by [developer credentials](cognito-terms.md#term-developercredentials). Guest authentication also skips straight to **Request identity**, doesn't validate authentication, and returns credentials for a [limited-access](iam-roles.md#access-policies-scope-down-services) IAM role.

**Related resources**
+ [Amazon Cognito identity pools](cognito-identity.md)
+ [User IAM roles](identity-pools.md#user-iam-roles)
+ [Identity pools authentication flow](authentication-flow.md)

# Using this service with an AWS SDK
Working with AWS SDKs

AWS software development kits (SDKs) are available for many popular programming languages. Each SDK provides an API, code examples, and documentation that make it easier for developers to build applications in their preferred language.


| SDK documentation | Code examples | 
| --- | --- | 
| [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/sdk-for-cpp) | [AWS SDK for C\$1\$1 code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp) | 
| [AWS CLI](https://docs.aws.amazon.com/cli) | [AWS CLI code examples](https://docs.aws.amazon.com/code-library/latest/ug/cli_2_code_examples.html) | 
| [AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go) | [AWS SDK for Go code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2) | 
| [AWS SDK for Java](https://docs.aws.amazon.com/sdk-for-java) | [AWS SDK for Java code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2) | 
| [AWS SDK for JavaScript](https://docs.aws.amazon.com/sdk-for-javascript) | [AWS SDK for JavaScript code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3) | 
| [AWS SDK for Kotlin](https://docs.aws.amazon.com/sdk-for-kotlin) | [AWS SDK for Kotlin code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin) | 
| [AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net) | [AWS SDK for .NET code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv3) | 
| [AWS SDK for PHP](https://docs.aws.amazon.com/sdk-for-php) | [AWS SDK for PHP code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php) | 
| [AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell) | [AWS Tools for PowerShell code examples](https://docs.aws.amazon.com/code-library/latest/ug/powershell_5_code_examples.html) | 
| [AWS SDK for Python (Boto3)](https://docs.aws.amazon.com/pythonsdk) | [AWS SDK for Python (Boto3) code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python) | 
| [AWS SDK for Ruby](https://docs.aws.amazon.com/sdk-for-ruby) | [AWS SDK for Ruby code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby) | 
| [AWS SDK for Rust](https://docs.aws.amazon.com/sdk-for-rust) | [AWS SDK for Rust code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1) | 
| [AWS SDK for SAP ABAP](https://docs.aws.amazon.com/sdk-for-sapabap) | [AWS SDK for SAP ABAP code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap) | 
| [AWS SDK for Swift](https://docs.aws.amazon.com/sdk-for-swift) | [AWS SDK for Swift code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift) | 

**Example availability**  
Can't find what you need? Request a code example by using the **Provide feedback** link at the bottom of this page.

# Authorization with Amazon Verified Permissions


[Amazon Verified Permissions](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/what-is-avp.html) is an authorization service for the applications that you build. When you add an Amazon Cognito user pool as an identity source, your app can pass user pool access or identity (ID) tokens to Verified Permissions for an allow or deny decision. Verified Permissions considers your user's properties and request context based on policies that you write in [Cedar Policy Language](https://docs.cedarpolicy.com/). The request context can include an identifier for the document, image, or other resource they requested, and the action that your user wants to take on the resource.

Your app can provide your user's identity or access tokens to Verified Permissions in [IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html) or [BatchIsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_BatchIsAuthorizedWithToken.html) API requests. These API operations accept your users as a `Principal` and make authorization decisions for the `Action` on the `Resource` that they want to access. Additional custom `Context` can contribute to a detailed access decision.

When your app presents a token in an `IsAuthorizedWithToken` API request, Verified Permissions performs the following validations.

1. Your user pool is a configured Verified Permissions [identity source](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/identity-providers.html) for the requested policy store.

1. The `client_id` or `aud` claim, in your access or identity token respectively, matches a user pool app client ID that you provided to Verified Permissions. To verify this claim, you must [configure client ID validation](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/cognito-validation.html) in your Verified Permissions identity source.

1. Your token isn't expired.

1. The value of the `token_use` claim in your token matches the parameters that you passed to `IsAuthorizedWithToken`. The `token_use` claim must be `access` if you passed it to the `accessToken` parameter, and `id` if you passed it to the `identityToken` parameter.

1. The signature in your token comes from the published JSON web keys (JWKs) of your user pool. You can view your JWKs at `https://cognito-idp.Region.amazonaws.com/your user pool ID/.well-known/jwks.json`.

**Revoked tokens and deleted users**  
Verified Permissions only validates the information it knows from your identity source and from the expiration time of your user's token. Verified Permissions doesn't check for token revocation or user existence. If you revoked your user's token or deleted your user's profile from your user pool, Verified Permissions still considers the token valid until it expires.

**Policy evaluation**  
Configure your user pool as an [identity source](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/identity-providers.html) for your [policy store](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/terminology.html#term-policy-store). Configure your app to submit your users' tokens in requests to Verified Permissions. For each request, Verified Permissions compares the claims in the token to a policy. A Verified Permissions policy is like an IAM policy in AWS. It declares a *principal*, *resource*, and *action*. Verified Permissions responds to your request with `Allow` if it matches an allowed action and doesn't match an explicit `Deny` action; otherwise, it responds with `Deny`. For more information, see [Amazon Verified Permissions policies](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policies.html) in the *Amazon Verified Permissions User Guide*.

**Customizing tokens**  
To change, add, and remove the user claims that you want to present to Verified Permissions, customize the content in your access and identity tokens with a [Pre token generation Lambda trigger](user-pool-lambda-pre-token-generation.md). With a pre token generation trigger, you can add and modify claims in your tokens. For example, you can query a database for additional user attributes and encode them into your ID token.

**Note**  
Because of the way that Verified Permissions processes claims, don't add claims named `cognito`, `dev`, or `custom` in your pre token generation function. When you present these reserved claim prefixes not in colon-delimited format like `cognito:username` but as full claim names, your authorization requests fail.

**Additional resources**
+ [Mapping Amazon Cognito tokens to Verified Permissions schema](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/identity-sources_map-token-to-schema.html)
+ [Authorize API Gateway APIs using Amazon Verified Permissions and Amazon Cognito](https://aws.amazon.com/blogs/security/authorize-api-gateway-apis-using-amazon-verified-permissions-and-amazon-cognito/)
+ [Workshop: Authentication and authorization with Amazon Cognito and Verified Permissions](https://catalog.workshops.aws/app-auth)

## API authorization with Verified Permissions


Your ID or access tokens can authorize requests to back-end Amazon API Gateway REST APIs with Verified Permissions. You can create a [policy store](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policy-stores.html) with immediate links to your user pool and API. With the [Set up with API Gateway and an identity source](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policy-stores_create.html) starting option, Verified Permissions adds a user pool identity source to the policy store, and a Lambda authorizer to the API. When your application passes a user pool bearer token to the API, the Lambda authorizer invokes Verified Permissions. The authorizer passes the token as a principal and the request path and method as an action.

The following diagram illustrates the authorization flow for an API Gateway API with Verified Permissions. For a detailed breakdown, see [API-linked policy stores](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policy-stores_api-userpool.html) in the Amazon Verified Permissions User Guide.

![\[A diagram that illustrates the flow of API authorization with Amazon Verified Permissions. An application makes a request to an Amazon API Gateway API. The API invokes a Lambda authorizer. The authorizer makes an API request to Verified Permissions. Verified Permissions checks token validity and returns an authorization decision.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/amazon-cognito-avp-use-case.png)


Verified Permissions structures API authorization around [user pool groups](cognito-user-pools-user-groups.md). Because both ID and access tokens include a `cognito:groups` claim, your policy store can manage role-based access control (RBAC) for your APIs in a variety of application contexts.

### Choosing policy store settings


When you configure an identity source on a policy store, you must choose whether you want to process access or ID tokens. This decision is significant to the way that your policy engine operates. ID tokens contain user attributes. Access tokens contain user access-control information: [OAuth scopes](cognito-user-pools-define-resource-servers.md). Although both token types have group-membership information, we generally recommend the access token for RBAC with a Verified Permissions policy store. The access token adds to group membership with scopes that can contribute to the authorization decision. The claims in an access token become [context](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/context.html) in the authorization request.

You must also configure the user and group entity types when you configure a user pool as an identity source. Entity types are principal, action, and resource identifiers that you can reference in Verified Permissions policies. Entities in policy stores can have a *membership* relationship, where one entity can be a member of a *parent* entity. With membership, you can reference principal groups, action groups, and resource groups. In the case of user pool groups, the user entity type that you specify must be a member of the group entity type. When you set up an [API-linked policy store](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policy-stores_api-userpool.html) or follow **Guided setup** in the Verified Permissions console, your policy store automatically has this parent-member relationship.

The ID token can combine RBAC with attribute-based access control (ABAC). After you create an [API-linked policy store](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policy-stores_api-userpool.html), you can enhance your policies with [user attributes](#amazon-cognito-authorization-with-avp-example-policy) *and* group membership. The attribute claims in an ID token become [principal attributes](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policies_examples-abac.html) in the authorization request. Your policies can make authorization decisions based on principal attributes.

You can also configure a policy store to accept tokens with an `aud` or `client_id` claim that matches a list of acceptable app clients that you provide.

### Example policy for role-based API authorization


The following example policy was created by the setup of a Verified Permissions policy store for a [PetStore](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-api-from-example.html) example REST API.

```
permit(
  principal in PetStore::UserGroup::"us-east-1_EXAMPLE|MyGroup",
  action in [ PetStore::Action::"get /pets", PetStore::Action::"get /pets/{petId}" ],
  resource
  );
```

Verified Permissions returns an `Allow` decision to the authorization request from your application when:

1. Your application passed an ID or access token in an `Authorization` header as a bearer token.

1. Your application passed a token with a `cognito:groups` claim that contains the string `MyGroup`.

1. Your application made an `HTTP GET` request to, for example, `https://myapi.example.com/pets` or `https://myapi.example.com/pets/scrappy`.

## Example policy for an Amazon Cognito user


Your user pool can also generate authorization requests to Verified Permissions in conditions other than API requests. You can submit any access control decisions in your application to your policy store. For example, you can supplement Amazon DynamoDB or Amazon S3 security with attribute-based access control before any requests transit the network, reducing quota use.

The following example uses the [Cedar Policy Language](https://docs.cedarpolicy.com/) to permit Finance users who authenticate with one user pool app client to read and write `example_image.png`. John, a user in your app, receives an ID token from your app client and passes it in a GET request to a URL that requires authorization, `https://example.com/images/example_image.png`. John's ID token has an `aud` claim of your user pool app client ID `1234567890example`. Your pre token generation Lambda function also inserted a new claim `costCenter` with a value, for John, of `Finance1234`.

```
permit (
   principal,
   actions in [ExampleCorp::Action::"readFile", "writeFile"],
   resource == ExampleCorp::Photo::"example_image.png"
)
when {
   principal.aud == "1234567890example" &&
   principal.custom.costCenter like "Finance*"
};
```

The following request body results in an `Allow` response.

```
{
   "accesstoken": "[John's ID token]",
   "action": {
      "actionId": "readFile",
      "actionType": "Action"
   },
   "resource": {
      "entityId": "example_image.png",
      "entityType": "Photo"
   }
}
```

When you want to specify a principal in a Verified Permissions policy, use the following format:

```
permit (
   principal == [Namespace]::[Entity]::"[user pool ID]|[user sub]",
   action,
   resource
);
```

The following is an example principal for a user in a user pool with ID `us-east-1_Example` with sub, or user ID, `973db890-092c-49e4-a9d0-912a4c0a20c7`.

```
principal == ExampleCorp::User::"us-east-1_Example|973db890-092c-49e4-a9d0-912a4c0a20c7",
```

When you want to specify a user group in a Verified Permissions policy, use the following format:

```
permit (
   principal in [Namespace]::[Group Entity]::"[Group name]",
   action,
   resource
);
```

**Attribute-based access control**  
Authorization with Verified Permissions for your apps, and the [attributes for access control](https://docs.aws.amazon.com/cognito/latest/developerguide/attributes-for-access-control.html) feature of Amazon Cognito identity pools for AWS credentials, are both forms of attribute-based access control (ABAC). The following is a comparison of the features of Verified Permissions and Amazon Cognito ABAC. In ABAC, a system examines the attributes of an entity and makes an authorization decision from conditions that you define.


| Service | Process | Result | 
| --- |--- |--- |
| Amazon Verified Permissions | Returns an Allow or Deny decision from analysis of a user pool JWT. | Access to application resources succeeds or fails based on Cedar policy evaluation. | 
| Amazon Cognito identity pools (attributes for access control) | Assigns [session tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html) to your user based on their attributes. IAM policy conditions can check tags Allow or Deny user access to AWS services. | A tagged session with temporary AWS credentials for an IAM role. |