Using the Amazon Cognito user pools API and user pool endpoints - Amazon Cognito
User pool API authentication

Using the Amazon Cognito user pools API and user pool endpoints

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

  1. Your user pool endpoints include the hosted UI and federation endpoints. 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 the hosted UI. 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 jwks.json. Your app uses these endpoints when it verifies tokens or retrieves user profile data with AWS SDKs and OAuth 2.0 libraries.

  2. The Amazon Cognito user pools API is a set of tools for your web or mobile app, after it collects sign-in information in your own custom front end, to authenticate users. 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.

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. It creates and configures your Amazon Cognito user pools resources. For example, you can create user pools, add AWS Lambda triggers, and configure your hosted UI domain. The user pools API also 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 the hosted UI, see User pool federation endpoints and hosted UI reference. Your federated users can start in the hosted UI and select their IdP, or you can skip the hosted UI 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 user pool endpoints

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

  2. You present 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 OAuth authorization page. Your user chooses to allow 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. Your app exchanges the authorization code with the Token endpoint 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.

The user pools API and the user pool endpoints 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.