Configuring a user pool app client

After you create a user pool, you can configure an app client to use the built-in webpages for signing up and signing in your users. For terminology, see App Client Settings Terminology.

Go to the Amazon Cognito console. If prompted, enter your AWS credentials.
Choose User Pools.
Choose an existing user pool from the list, or create a user pool.
Choose the App integration tab.
Under App clients, select Create an app client.
Select an App type: Public client, Confidential client, or Other. A Public client typically operates from your users' devices and uses unauthenticated and token-authenticated APIs. A Confidential client typically operates from an app on a central server that you trust with client secrets and API credentials, and uses authorization headers and AWS Identity and Access Management credentials to sign requests. If your use case is different from the preconfigured app client settings for a Public client or a Confidential client, select Other.
Enter an App client name.
Select the Authentication flows you want to allow in your app client. For more information, see User Pool Authentication Flow.
Configure the Authentication flow session duration. This is the amount of time your users have to complete each authentication challenge before their session token expires.
(Optional) configure token expiration.
1. Specify the Refresh token expiration for the app client. The default value is 30 days. You can change it to any value between 1 hour and 10 years.
2. Specify the Access token expiration for the app client. The default value is 1 hour. You can change it to any value between 5 minutes and 24 hours.
3. Specify the ID token expiration for the app client. The default value is 1 hour. You can change it to any value between 5 minutes and 24 hours.
  
  Important
  If you use the hosted UI and configure a token lifetime of less than an hour, your user will be able to use tokens based on their session cookie duration, which is currently fixed at one hour.
Choose Generate client secret to have Amazon Cognito generate a client secret for you. Client secrets are typically associated with confidential clients.
Choose whether you will Enable token revocation for this app client. This will increase the size of tokens that Amazon Cognito issues. For more information, see Revoking Tokens.
Choose whether you will Prevent error messages that reveal user existence for this app client. Amazon Cognito will respond to sign-in requests for nonexistent users with a generic message stating that either the user name or password was incorrect.
(Optional) Configure Attribute read and write permissions for this app client. Your app client can have permission to read and write only a limited subset of your user pool's attribute schema. For more information, see Attribute Permissions and Scopes.
Choose Create.
Note the Client id. This will identify the app client in sign-up and sign-in requests.

You can use the AWS CLI to update, create, describe, and delete your user pool app client.

Replace "MyUserPoolID" and "MyAppClientID" with your user pool and app client ID values in these examples. Likewise, your parameter values might be different than those used in these examples.

Note

Use JSON format for callback and logout URLs to prevent the CLI from treating them as remote parameter files:

--callback-urls "["https://example.com"]"

--logout-urls "["https://example.com"]"

Updating a user pool app client (AWS CLI and AWS API)

At the AWS CLI, enter the following command:


aws cognito-idp update-user-pool-client --user-pool-id  "MyUserPoolID" --client-id "MyAppClientID" --allowed-o-auth-flows-user-pool-client --allowed-o-auth-flows "code" "implicit" --allowed-o-auth-scopes "openid" --callback-urls "["https://example.com"]" --supported-identity-providers "["MySAMLIdP", "LoginWithAmazon"]"

If the command is successful, the AWS CLI returns a confirmation:


{
    "UserPoolClient": {
        "ClientId": "MyClientID",
        "SupportedIdentityProviders": [
            "LoginWithAmazon",
            "MySAMLIdP"
        ],
        "CallbackURLs": [
            "https://example.com"
        ],
        "AllowedOAuthScopes": [
            "openid"
        ],
        "ClientName": "Example",
        "AllowedOAuthFlows": [
            "implicit",
            "code"
        ],
        "RefreshTokenValidity": 30,
        "AuthSessionValidity": 3,
        "CreationDate": 1524628110.29,
        "AllowedOAuthFlowsUserPoolClient": true,
        "UserPoolId": "MyUserPoolID",
        "LastModifiedDate": 1530055177.553
    }
}

See the AWS CLI command reference for more information: update-user-pool-client.

AWS API: UpdateUserPoolClient

Creating a user pool app client (AWS CLI and AWS API)


aws cognito-idp create-user-pool-client --user-pool-id MyUserPoolID --client-name myApp

See the AWS CLI command reference for more information: create-user-pool-client

AWS API: CreateUserPoolClient

Getting information about a user pool app client (AWS CLI and AWS API)


aws cognito-idp describe-user-pool-client --user-pool-id MyUserPoolID --client-id MyClientID

See the AWS CLI command reference for more information: describe-user-pool-client.

AWS API: DescribeUserPoolClient

Listing all app client information in a user pool (AWS CLI and AWS API)


aws cognito-idp list-user-pool-clients --user-pool-id "MyUserPoolID" --max-results 3

See the AWS CLI command reference for more information: list-user-pool-clients.

AWS API: ListUserPoolClients

Deleting a user pool app client (AWS CLI and AWS API)


aws cognito-idp delete-user-pool-client --user-pool-id "MyUserPoolID" --client-id "MyAppClientID"

See the AWS CLI command reference for more information: delete-user-pool-client

AWS API: DeleteUserPoolClient

App client settings terminology

The following terms and definitions can help you with configuring your app client.

Enabled Identity Providers

You can choose your identity provider (IdP) to authenticate your users. This service can be performed by your user pool, or by a third party such as Facebook. Before you can use an IdP, you need to enable it. You can enable multiple IdPs, but you must enable at least one. For more information on using external IdPs see Adding user pool sign-in through a third party.

Callback URL(s)

A callback URL indicates where the user will be redirected after a successful sign-in. Choose at least one callback URL. The callback URL must:

Be an absolute URI.
Be pre-registered with a client.
Not include a fragment component.

See OAuth 2.0 - redirection endpoint.

Amazon Cognito requires HTTPS over HTTP except for http://localhost for testing purposes only.

App callback URLs such as myapp://example are also supported.

Sign out URL(s)

A sign-out URL indicates where your user is to be redirected after signing out.

Allowed OAuth Flows

The Authorization code grant flow initiates a code grant flow, which provides an authorization code as the response. This code can be exchanged for access tokens with the Token endpoint. Because the tokens are never exposed directly to an end user, they are less likely to become compromised. However, a custom application is required on the backend to exchange the authorization code for user pool tokens.

Note

For security reasons, we highly recommend that you use only the Authorization code grant flow, together with PKCE, for mobile apps.

The Implicit grant flow allows the client to get the access token (and optionally the ID token, based on scopes) directly from the Authorize endpoint. Choose this flow if your app can't initiate the Authorization code grant flow. For more information, see the OAuth 2.0 specification.

You can activate both the Authorization code grant and the Implicit code grant, and then use each grant as needed.

The Client credentials flow is used in machine-to-machine communications. You can use this flow to request an access token to access your own resources. Choose this flow when your app is requesting the token on its own behalf and not on behalf of a user.

Note

Because you don't invoke the client credentials flow as a user, you can only populate custom scopes to the access token with this flow. A custom scope is one that you define for your own resource server. See Defining resource servers for your user pool.

Allowed OAuth Scopes

Choose one or more of the following OAuth scopes to specify the access privileges that can be requested for access tokens.

The phone scope grants access to the phone_number and phone_number_verified claims. This scope can only be requested with the openid scope.
The email scope grants access to the email and email_verified claims. This scope can only be requested with the openid scope.
The openid scope declares that you want to retrieve scopes that align with the OpenID Connect specification. Amazon Cognito doesn't return an ID token unless you request the openid scope.
The aws.cognito.signin.user.admin scope grants access to Amazon Cognito user pool API operations that require access tokens, such as UpdateUserAttributes and VerifyUserAttribute.
The profile scope grants access to all user attributes that are readable by the client. This scope can only be requested with the openid scope.

Allowed Custom Scopes: A custom scope is one that you define for your own resource server in the Resource Servers. The format is resource-server-identifier/scope. See Defining resource servers for your user pool.

For more information about OAuth scopes, see the list of standard OIDC scopes.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Using the hosted UI

Configuring a domain