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
To create an app client
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-idMyClientID
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
overHTTP
except forhttp://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 thephone_number
andphone_number_verified
claims. This scope can only be requested with theopenid
scope. -
The
email
scope grants access to theemail
andemail_verified
claims. This scope can only be requested with theopenid
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 theopenid
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 theopenid
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