Amazon Cognito
Developer Guide

Configuring a User Pool App Client

After you create a user pool, you can create an app client to use the built-in webpages for signing up and signing in your users. To add an app client and an Amazon Cognito hosted domain with the AWS Management Console, see Adding an App to Enable the Hosted Web UI.

App Client Settings Overview

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 is to be redirected after a successful sign-in. Choose at least one callback URL, and it should:

  • 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, ID token, based on scopes) directly from the AUTHORIZATION Endpoint. Choose this flow if your app cannot initiate the Authorization code grant flow. For more information, see the OAuth 2.0 specification.

You can enable 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. With it you can request an access token to access your own resources. Use this flow when your app is requesting the token on its own behalf, not on behalf of a user.

Note

Since the client credentials flow is not used on behalf of a user, only custom scopes can be used 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 returns all user attributes in the ID token that are readable by the client. The ID token is not returned if the openid scope is not requested by the client.

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

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.

To Configure an App Client (AWS Management Console)
  1. Go to the Amazon Cognito console. You might be prompted for your AWS credentials.

  2. Choose Manage User Pools.

  3. Choose the user pool you want to edit.

  4. Choose App client settings from the navigation bar on the left-side of the console page.

  5. Select Cognito User Pool as one of the Enabled Identity Providers to include it as one of your IdPs. Enable at least one IdP.

    Note

    To sign in with external identity providers (IdPs), such as Facebook, Amazon, or Google, as well as through OpenID Connect (OIDC) or SAML IdPs, configure them first and then return to the App client settings page to enable them. For more information see Adding User Pool Sign-in Through a Third Party.

  6. In the Sign in and sign out URLs section, type your Callback URLs, separated by commas.

    For a web app, the URL should start with https://, such as https://www.example.com.

    For an iOS or Android app, you can use a callback URL such as myapp://.

    Note

    You must register the callback and sign out URLs, either in the console or by using the CLI or API, before you can use them with your user pool app client.

  7. Type your optional Sign out URLs, separated by commas.

  8. Select your OAuth 2.0 options:

    • Authorized code grant

    • Implicit grant

    • Client credentials

      Choosing client credentials will clear the other options, and the standard scopes will not be available.

    1. For the code grant and implicit grant options, select your scopes from Allowed OAuth Scopes. Each scope is a set of one or more standard attributes. For more information, see App Client Settings Overview.

    2. For the client credentials flow, the standard scopes are not available. Since the client credentials flow is not used on behalf of a user, only custom scopes can be used. A custom scope is one that you define for your own resource server. See Defining Resource Servers for Your User Pool.

  9. Choose Save changes.

To Configure an App Client (AWS CLI and AWS API)

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)

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