Configuring a user pool app client

A user pool app client is a configuration within a user pool that interacts with one mobile or web application that authenticates with Amazon Cognito. App clients can call authenticated and authenticated API operations, and read or modify some or all of your users' attributes. Your app must identify itself to the app client in operations to register, sign in, and handle forgotten passwords. These API requests must include self-identification with an app client ID, and authorization with an optional client secret. You must secure any app client IDs or secrets so that only authorized client apps can call these unauthenticated operations. Additionally, if you configure your app to sign authenticated API requests with AWS credentials, you must secure your credentials against user inspection.

You can create multiple apps for a user pool. An app client might be linked to the code platform of an app, or a separate tenant in your user pool. For example, you might create an app for a server-side application and a different Android app. Each app has its own app client ID.

When you create an app client in Amazon Cognito, you can pre-populate options based on the standard OAuth client types public client and confidential client. Configure a confidential client with a client secret.

Public client

A public client runs in a browser or on a mobile device. Because it does not have trusted server-side resources, it does not have a client secret.

Confidential client

A confidential client has server-side resources that can be trusted with a client secret for unauthenticated API operations. The app might run as a daemon or shell script on your backend server.

Client secret

A client secret is a fixed string that your app must use in all API requests to the app client. Your app client must have a client secret to perform client_credentials grants.

You can't change secrets after you create an app. You can create a new app with a new secret if you want to rotate the secret. You can also delete an app to block access from apps that use that app client ID.

You can use a confidential client, and a client secret, with a public app. Use an Amazon CloudFront proxy to add a SECRET_HASH in transit. For more information, see Protect public clients for Amazon Cognito by using an Amazon CloudFront proxy on the AWS blog.

To create an app client

AWS Management Console

To create an app client (console)

1. Go to the Amazon Cognito console. If prompted, enter your AWS credentials.

2. Choose User Pools.

3. Choose an existing user pool from the list, or create a user pool.

4. Select the App integration tab.

5. Under App clients, select Create an app client.

6. Select an App type: Public client, Confidential client, or Other.

7. Enter an App client name.

8. Choose Generate a client secret to have Amazon Cognito generate a client secret for you. Client secrets are typically associated with confidential clients.

9. Select the Authentication flows you want to allow in your app client.

10. 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.

11. (Optional) If you want to configure token expiration, complete the following steps:

    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.

12. Choose whether you will Enable token revocation for this app client. This will increase the size of tokens that Amazon Cognito issues.

13. Choose whether you will Prevent user existence errors 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.

14. If you want to use the hosted UI with this app client, configure Hosted UI settings.

    1. Enter one or more Allowed callback URLs. These are the web or app URLs where you want Amazon Cognito to redirect your users after they complete authentication.

    2. Enter one or more Allowed sign-out URLs. These are URLs that you want your app to accept in requests to the Logout endpoint.

    3. Choose one or more Identity providers that you want to be able to sign in users for your app. You can choose any combination of existing IdPs. You can authenticate users with your user pool alone, or with one or more third-party IdPs that you configured in your user pool.

    4. Choose the OAuth 2.0 grant types that you want your app client to accept.

       • Select Authorization code grant to pass codes to your app that it can redeem for tokens with the Token endpoint.

       • Select Implicit grant to pass ID and access tokens directly to your app. The implicit grant flow exposes tokens directly to your users.

       • Select Client credentials to pass access tokens to your app based on its knowledge not of user credentials, but of the client secret. The client credentials grant flow is mututally exclusive with authorization code and implicit grant flows.

    5. Choose the OpenID Connect scopes that you want to authorize for use with your app client. You can generate access tokens with only the aws.cognito.signin.user.admin scope through the user pools API. For additional scopes, you must request your access tokens from the Token endpoint.

    6. Choose the Custom scopes that you want to authorize with your app client. Custom scopes are most often used to authorize access to third-party APIs.

15. Configure Attribute read and write permissions for this app client. Your app client can have permission to read and write all, or a limited subset of, your user pool's attribute schema.

16. Choose Create app client.

17. Note the Client id. This will identify the app client in sign-up and sign-in requests.

AWS CLI

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

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"]"

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

Amazon Cognito user pools API

Generate a CreateUserPoolClient API request. You must specify a value for all parameters that you don't want set to a default value.

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

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 API authorization with resource servers and OAuth 2.0 scopes.

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 API authorization with resource servers and OAuth 2.0 scopes.

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