Authorization models for API and SDK authentication - Amazon Cognito
Server-side authentication optionsClient-side authentication optionsUsing the API and endpoints

Authorization models for API and SDK authentication

When you start out with user pools authentication, you must decide on your application authorization model. Amazon Cognito authentication typically requires that you implement two API operations in order. The API operations that you use for authentication depend on the characteristics of your application. Public clients, where the application is distributed to users, use public authentication, where requests for sign-in don't require authorization. Server-side clients, where the application logic is hosted on a remote system, can protect authentication operations with IAM authorization for sign-in requests. The following API operation pairs and their corresponding SDK methods map to each of the available authorization models.

To compare API authentication and see a full list of API operations and their authorization models, see Understanding API, OIDC, and managed login pages authentication.

Client-side (public) authentication

  1. InitiateAuth

  2. RespondToAuthChallenge

InitiateAuth and RespondToAuthChallenge are unauthenticated APIs for use with client-side public app clients. For more information, see Client-side authentication options and Understanding API, OIDC, and managed login pages authentication.

Server-side authentication

  1. AdminInitiateAuth

  2. AdminRespondToAuthChallenge

AdminInitiateAuth and AdminRespondToAuthChallenge require IAM credentials and are suited for server-side confidential app clients. For more information, see Server-side authentication options and Understanding API, OIDC, and managed login pages authentication.

A user authenticates by answering successive challenges until authentication either fails or Amazon Cognito issues tokens to the user. You can repeat these steps with Amazon Cognito, in a process that includes different challenges, to support any custom authentication flow.

Server-side authentication options

Web applications and other server-side applications implement authentication in a session on a remote server, usually in a browser that initiates a session to that server. Server-side applications typically have the following characteristics.

  • They're built in an application installed on a server in languages like Java, Ruby, or Node.js.

  • They connect to user pool app clients that might have a client secret, called confidential clients.

  • They have access to AWS credentials.

  • They invoke managed login for authentication, or use IAM-authorized operations in the user pools API with an AWS SDK.

  • They serve internal customers and might serve public customers.

Server-side operations with the user pools API can use passwords, one-time passwords, or passkeys as the primary sign-in factor. For server-side apps, user pool authentication is similar to authentication for client-side apps, except for the following:

  • The server-side app makes an AdminInitiateAuth API request. This operation requires AWS credentials with permissions that include cognito-idp:AdminInitiateAuth and cognito-idp:AdminRespondToAuthChallenge. The operation returns the required challenge or authentication outcome.

  • When the application receives a challenge, it makes an AdminRespondToAuthChallenge API request. The AdminRespondToAuthChallenge API operation also requires AWS credentials.

For more information about signing Amazon Cognito API requests with AWS credentials, see Signature Version 4 signing process in the AWS General Reference.

In the AdminInitiateAuth response ChallengeParameters, the USER_ID_FOR_SRP attribute, if present, contains the user's actual username, not an alias (such as email address or phone number). In your call to AdminRespondToAuthChallenge, in the ChallengeResponses, you must pass this username in the USERNAME parameter.

Note

Because backend admin implementations use the admin authentication flow, the flow doesn't support remembered devices. When you have turned on device tracking, admin authentication succeeds, but any call to refresh the access token fails.

Client-side authentication options

Mobile apps and other client-side application types installed on users' devices typically have the following characteristics.

  • They're built in languages like React native, Flutter, and Swift and deploy to user devices.

  • They connect to user pool app clients that don't have a client secret, called public clients.

  • They don't have access to AWS credentials that would authorize IAM-authorized API requests.

  • They invoke managed login for authentication, or use public and token-authorized operations in the user pools API with an AWS SDK.

  • They serve public customers and permit anyone to sign up and sign in.

Client-side operations with the user pools API can use passwords, one-time passwords, or passkeys as the primary sign-in factor. The following process works for user client-side apps that you create with AWS Amplify or the AWS SDKs.

  1. The user enters their username and password into the app.

  2. The app calls the InitiateAuth operation with the user's username and Secure Remote Password (SRP) details.

    This API operation returns the authentication parameters.

    Note

    The app generates SRP details with the Amazon Cognito SRP features that are built in to AWS SDKs.

  3. The app calls the RespondToAuthChallenge operation. If the call succeeds, Amazon Cognito returns the user's tokens, and the authentication flow is complete.

    If Amazon Cognito requires another challenge, the call to RespondToAuthChallenge returns no tokens. Instead, the call returns a session.

  4. If RespondToAuthChallenge returns a session, the app calls RespondToAuthChallenge again, this time with the session and the challenge response (for example, MFA code).

Understanding API, OIDC, and managed login pages authentication

Amazon Cognito user pools are a combination of several authentication technologies. They are relying parties to external identity providers (IdPs). They are IdPs to applications that implement authentication with OpenID Connect (OIDC) SDKs. They provide authentication as issuers of JSON web tokens (JWTs) similar to OIDC authentication, but in API methods that are part of AWS SDKs. They can also be secure points of entry to your applications.

When you want to sign up, sign in, and manage users in your user pool, you have two options.

  1. Your managed login pages and the classic hosted UI include the managed login user-interactive endpoints and the federation endpoints that handle IdP and relying-party roles. They make up a package of public webpages that Amazon Cognito activates when you choose a domain for your user pool. For a quick start with the authentication and authorization features of Amazon Cognito user pools, including pages for sign-up, sign-in, password management, and multi-factor authentication (MFA), use the built-in user interface of managed login.

    The other user pool endpoints facilitate authentication with third-party identity providers (IdPs). The services that they perform include the following.

    1. Service-provider callback endpoints for authenticated claims from your IdPs, like saml2/idpresponse and oauth2/idpresponse. When Amazon Cognito is an intermediate service provider (SP) between your app and your IdP, the callback endpoints represent the service.

    2. Endpoints that provide information about your environment, like oauth2/userInfo and /.well-known/jwks.json. Your app uses these endpoints when it verifies tokens or retrieves user profile data with OIDC or OAuth 2.0 developer libraries.

  2. The Amazon Cognito user pools API is a set of tools for your web or mobile app to authenticate users after it collects sign-in information in your own custom front end. User pools API authentication produces the following JSON web tokens.

    1. An identity token with verifiable attribute claims from your user.

    2. An access token that authorizes your user to create token-authorized API requests to an AWS service endpoint.

      Note

      By default, access tokens from user pools API authentication only contain the aws.cognito.signin.user.admin scope. To generate an access token with additional scopes, for example to authorize a request to a third-party API, request scopes during authentication through your user pool endpoints or add custom scopes in a Pre token generation Lambda trigger. Access token customization adds costs to your AWS bill.

    3. A refresh token that authorizes requests for new ID and access tokens, and refreshes user identity and access-control properties.

You can link a federated user, who would normally sign in through the user pools endpoints, with a user whose profile is local to your user pool. A local user exists exclusively in your user pool directory without federation through an external IdP. If you link their federated identity to a local user in an AdminLinkProviderForUser API request, they can sign in with the user pools API. For more information, see Linking federated users to an existing user profile.

The Amazon Cognito user pools API is dual-purpose.

  1. It creates and configures your Amazon Cognito user pools resources. For example, you can create user pools, add AWS Lambda triggers, and configure the user pool domain that hosts your managed login pages.

  2. It performs sign-up, sign-in and other user operations for local and linked users.

Example scenario with the Amazon Cognito user pools API

  1. Your user selects a "Create an account" button that you created in your app. They enter an email address and password.

  2. Your app sends a SignUp API request and creates a new user in your user pool.

  3. Your app prompts your user for an email confirmation code. Your users enters the code they received in an email message.

  4. Your app sends a ConfirmSignUp API request with the user's confirmation code.

  5. Your app prompts your user for their username and password, and they enter their information.

  6. Your app sends an InitiateAuth API request and stores an ID token, access token, and refresh token. Your app calls OIDC libraries to manage your user's tokens and maintain a persistent session for that user.

In the Amazon Cognito user pools API, you can't sign in users who federate through an IdP. You must authenticate these users through your user pool endpoints. For more information about the user pool endpoints that include managed login, see User pool endpoints and managed login reference.

Your federated users can start in managed login and select their IdP, or you can skip managed login and send your users directly to your IdP to sign in. When your API request to the Authorize endpoint includes an IdP parameter, Amazon Cognito silently redirects your user to the IdP sign-in page.

Example scenario with managed login pages

  1. Your user selects a "Create an account" button that you created in your app.

  2. Managed login presents your user with a list of the social identity providers where you have registered developer credentials. Your user chooses Apple.

  3. Your app initiates a request to the Authorize endpoint with provider name SignInWithApple.

  4. Your user's browser opens the Apple authentication page. Your user signs in and chooses to authorize Amazon Cognito to read their profile information.

  5. Amazon Cognito confirms the Apple access token and queries your user's Apple profile.

  6. Your user presents an Amazon Cognito authorization code to your app.

  7. The OIDC library in your application exchanges the authorization code with the Token endpoint and stores an ID token, access token, and refresh token issued by the user pool. Your app uses OIDC libraries to manage your user's tokens and maintain a persistent session for that user.

The user pools API and managed login pages support a variety of scenarios, described throughout this guide. The following sections examine how the user pools API further divides into classes that support your sign-up, sign-in, and resource-management requirements.

Amazon Cognito user pools authenticated and unauthenticated API operations

The Amazon Cognito user pools API, both a resource-management interface and a user-facing authentication and authorization interface, combines the authorization models that follow in its operations. Depending on the API operation, you might have to provide authorization with IAM credentials, an access token, a session token, a client secret, or a combination of these. For many user authentication and authorization operations, you have a choice of authenticated and unauthenticated versions of the request. Unauthenticated operations are best security practice for apps that you distribute to your users, like mobile apps; you don't need to include any secrets in your code.

You can only assign permissions in IAM policies for IAM-authenticated management operations and IAM-authenticated user operations.

IAM-authenticated management operations modify and view your user pool and app client configuration, like you would do in the AWS Management Console.

For example, to modify your user pool in an UpdateUserPool API request, you must present AWS credentials and IAM permissions to update the resource.

To authorize these requests in the AWS Command Line Interface (AWS CLI) or an AWS SDK, configure your environment with environment variables or client configuration that adds IAM credentials to your request. For more information, see Accessing AWS using your AWS credentials in the AWS General Reference. You can also send requests directly to the service endpoints for the Amazon Cognito user pools API. You must authorize, or sign, these requests with AWS credentials that you embed in the header of your request. For more information, see Signing AWS API requests.

IAM-authenticated management operations
AddCustomAttributes
CreateGroup
CreateIdentityProvider
CreateResourceServer
CreateUserImportJob
CreateUserPool
CreateUserPoolClient
CreateUserPoolDomain
DeleteGroup
DeleteIdentityProvider
DeleteResourceServer
DeleteUserPool
DeleteUserPoolClient
DeleteUserPoolDomain
DescribeIdentityProvider
DescribeResourceServer
DescribeRiskConfiguration
DescribeUserImportJob
DescribeUserPool
DescribeUserPoolClient
DescribeUserPoolDomain
GetCSVHeader
GetGroup
GetIdentityProviderByIdentifier
GetSigningCertificate
GetUICustomization
GetUserPoolMfaConfig
ListGroups
ListIdentityProviders
ListResourceServers
ListTagsForResource
ListUserImportJobs
ListUserPoolClients
ListUserPools
ListUsers
ListUsersInGroup
SetRiskConfiguration
SetUICustomization
SetUserPoolMfaConfig
StartUserImportJob
StopUserImportJob
TagResource
UntagResource
UpdateGroup
UpdateIdentityProvider
UpdateResourceServer
UpdateUserPool
UpdateUserPoolClient
UpdateUserPoolDomain

IAM-authenticated user operations sign up, sign in, manage credentials for, modify, and view your users.

For example, you can have a server-side application tier that backs a web front end. Your server-side app is an OAuth confidential client that you trust with privileged access to your Amazon Cognito resources. To register a user in the app, your server can include AWS credentials in an AdminCreateUser API request. For more information about OAuth client types, see Client Types in The OAuth 2.0 Authorization Framework.

To authorize these requests in the AWS CLI or an AWS SDK, configure your server-side app environment with environment variables or client configuration that adds IAM credentials to your request. For more information, see Accessing AWS using your AWS credentials in the AWS General Reference. You can also send requests directly to the service endpoints for the Amazon Cognito user pools API. You must authorize, or sign, these requests with AWS credentials that you embed in the header of your request. For more information, see Signing AWS API requests.

If your app client has a client secret, you must provide both your IAM credentials and, depending on the operation, either the SecretHash parameter or the SECRET_HASH value in AuthParameters. For more information, see Computing secret hash values.

IAM-authenticated user operations
AdminAddUserToGroup
AdminConfirmSignUp
AdminCreateUser
AdminDeleteUser
AdminDeleteUserAttributes
AdminDisableProviderForUser
AdminDisableUser
AdminEnableUser
AdminForgetDevice
AdminGetDevice
AdminGetUser
AdminInitiateAuth
AdminLinkProviderForUser
AdminListDevices
AdminListGroupsForUser
AdminListUserAuthEvents
AdminRemoveUserFromGroup
AdminResetUserPassword
AdminRespondToAuthChallenge
AdminSetUserMFAPreference
AdminSetUserPassword
AdminSetUserSettings
AdminUpdateAuthEventFeedback
AdminUpdateDeviceStatus
AdminUpdateUserAttributes
AdminUserGlobalSignOut

Unauthenticated user operations sign up, sign in, and initiate password resets for your users. Use unauthenticated, or public, API operations when you want anyone on the internet to sign up and sign in to your app.

For example, to register a user in your app, you can distribute an OAuth public client that doesn't provide any privileged access to secrets. You can register this user with the unauthenticated API operation SignUp.

To send these requests in a public client that you developed with an AWS SDK, you don't need to configure any credentials. You can also send requests directly to the service endpoints for the Amazon Cognito user pools API with no additional authorization.

If your app client has a client secret, you must provide, depending on the operation, either the SecretHash parameter or the SECRET_HASH value in AuthParameters. For more information, see Computing secret hash values.

Unauthenticated user operations
SignUp
ConfirmSignUp
ResendConfirmationCode
ForgotPassword
ConfirmForgotPassword
InitiateAuth

Token-authorized user operations sign out, manage credentials for, modify, and view your users after they have signed in or begun the sign-in process. Use token-authorized API operations when you don't want to distribute secrets in your app, and you want to authorize requests with your user's own credentials. If your user has completed sign-in, you must authorize their token-authorized API request with an access token. If your user is in the middle of a sign-in process, you must authorize their token-authorized API request with a session token that Amazon Cognito returned in the response to the previous request.

For example, in a public client, you might want to update a user's profile in a way that restricts the write access to the user's own profile only. To make this update, your client can include the user's access token in a UpdateUserAttributes API request.

To send these requests in a public client that you developed with an AWS SDK, you don't need to configure any credentials. Include an AccessToken or Session parameter in your request. You can also send requests directly to the service endpoints for the Amazon Cognito user pools API. To authorize a request to a service endpoint, include the access or session token in the POST body of your request.

To sign an API request for a token-authorized operation, include the access token as an Authorization header in your request, in the format Bearer <Base64-encoded access token>.

Token-authorized user operations AccessToken Session
RespondToAuthChallenge ✓
ChangePassword ✓
GetUser ✓
UpdateUserAttributes ✓
DeleteUserAttributes ✓
DeleteUser ✓
ConfirmDevice ✓
ForgetDevice ✓
GetDevice ✓
ListDevices ✓
UpdateDeviceStatus ✓
GetUserAttributeVerificationCode ✓
VerifyUserAttribute ✓
SetUserSettings ✓
SetUserMFAPreference ✓
GlobalSignOut ✓
AssociateSoftwareToken ✓ ✓
UpdateAuthEventFeedback ✓
VerifySoftwareToken ✓ ✓
RevokeToken¹

¹ RevokeToken takes a refresh token as a parameter. The refresh token serves as the authorizing token, and as the target resource.