User pool app clients

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

App client types

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. For more information about client types, see IETF RFC 6749 #2.1.

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, or client password, 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. For more information, see IETF RFC 6749 #2.3.1.

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.

JSON web tokens

Amazon Cognito app clients can issue JSON web tokens (JWTs) of the following types.

Identity (ID) token

A verifiable statement that your user is authenticated from your user pool. OpenID Connect (OIDC) added the ID token specification to the access and refresh token standards defined by OAuth 2.0. The ID token contains identity information, like user attributes, that your app can use to create a user profile and provision resources. See Using the ID token for more information.

Access token

A verifiable statement of your user's access rights. The access token contains scopes, a feature of OIDC and OAuth 2.0. Your app can present scopes to back-end resources and prove that your user pool authorized a user or machine to access data from an API, or their own user data. An access token with custom scopes, often from an M2M client-credentials grant, authorizes access to a resource server. See Using the access token for more information.

Refresh token

An encrypted statement of initial authentication that your app can present to your user pool when your user's tokens expire. A refresh-token request returns new, unexpired access and ID tokens. See Using the refresh token for more information.

You can set the expiration of these tokens for each app client from the App integration tab of your user pool in the Amazon Cognito console.

App client terms

The following terms are available properties of app clients in the Amazon Cognito console.

Authentication flows

The methods that your app client allows for sign-in. Your app can support authentication with username and password, Secure Remote Password (SRP), custom authentication with Lambda triggers, and token refresh. As a best security practice, use SRP authentication as your primary sign-in method. The hosted UI automatically signs users in with SRP.

Attribute read and write permissions

Your user pool might have many customers, each with their own app client and IdPs. You can configure your app client to have read and write access to only those user attributes that are relevant to the app. In cases like machine-to-machine (M2M) authorization, you can grant access to none of your user attributes.

Identity providers

You can choose some or all of your user pool external identity providers (IdPs) to authenticate your users. Your app client can also authenticate only local users in your user pool. When you add an IdP to your app client, you can generate authorization links to the IdP and display it on your hosted UI sign-in page. You can assign multiple IdPs, but you must assign at least one. For more information on using external IdPs, see Adding user pool sign-in through a third party.

Allowed callback URLs

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.

Allowed sign out URLs

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

OAuth grant types

An OAuth grant is a method of authentication that retrieves user-pool tokens. Amazon Cognito supports the following types of grants. To integrate these OAuth grants in your app, you must add a domain to your user pool.

Authorization code grant

The authorization code grant generates a code that your app can exchange for user pool tokens with the Token endpoint. When you exchange an authorization code, your app receives ID, access, and refresh tokens. This OAuth flow, like the implicit grant, happens in your users' browsers. An authorization code grant is the most secure grant that Amazon Cognito offers, because tokens aren't visible in your users' sessions. Instead, your app generates the request that returns tokens and can cache them in protected storage. For more information, see Authorization code in IETF RFC 6749 #1.3.1

Note

As a best security practice in public-client apps, activate only the authorization-code grant OAuth flow, and implement Proof Key for Code Exchange (PKCE) to restrict token exchange. With PKCE, a client can only exchange an authorization code when they have provided the token endpoint with the same secret that was presented in the original authentication request. For more information on PKCE, see IETF RFC 7636.

Implicit grant

The implicit grant delivers an access and ID token, but not refresh token, to your user's browser session directly from the Authorize endpoint. An implicit grant removes the requirement for a separate request to the token endpoint, but isn't compatible with PKCE and doesn't return refresh tokens. This grant accommodates testing scenarios and app architecture that can't complete authorization-code grants. For more information, see Implicit grant in IETF RFC 6749 #1.3.2. You can activate both the authorization-code grant and the implicit grant in an app client, and then use each grant as needed.

Client credentials grant

The client credentials grant is for machine-to-machine (M2M) communications. Authorization-code and implicit grants issue tokens to authenticated human users. Client credentials grant scope-based authorization from a non-interactive system to an API. Your app can request client credentials directly from the token endpoint and receive an access token. For more information, see Client Credentials in IETF RFC 6749 #1.3.4. You can only activate client-credentials grants in app clients that have a client secret and that don't support authorization-code or implicit grants.

Note

Because you don't invoke the client credentials flow as a user, this grant can only add custom scopes to access tokens. A custom scope is one that you define for your own resource server. Default scopes like openid and profile don't apply to nonhuman users.

Because ID tokens are a validation of user attributes, they aren't relevant to M2M communication, and a client credentials grants doesn't issue them. See OAuth 2.0 scopes and API authorization with resource servers.

OpenID Connect scopes

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

• The openid scope declares that you want to retrieve an ID token and a user's unique ID. It also requests all or some user attributes, depending on additional scopes in the request. Amazon Cognito doesn't return an ID token unless you request the openid scope. The openid scope authorizes structural ID token claims like expiration and key ID, and determines the user attributes that you receive in a response from the UserInfo endpoint.

  • When openid is the only scope that you request, Amazon Cognito populates the ID token with all user attributes that the current app client can read. The userInfo response to an access token with this scope alone returns all user attributes.

  • When you request openid with other scopes like phone, email, or profile, the ID token and userInfo return the user's unique ID and the attributes defined by the additional scopes.

• 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 aws.cognito.signin.user.admin scope grants access to Amazon Cognito user pools 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.

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

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

Creating 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