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.
You can apply settings for the following user pool features at the app client level:
-
Hosted UI IdPs, grant types, callback URLs, and customization
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
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.
- 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
overHTTP
except forhttp://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.
- 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.
Considerations for attribute read and write permissions configuration
-
When you create an app client and don't customize attribute read and write permissions, Amazon Cognito grants read and write permissions to all user pool attributes.
-
You can grant write access to immutable custom attributes. Your app client can write values to immutable attributes when you create or sign up a user. After this, you can't write values to any immutable custom attributes for the user.
-
App clients must have write access to required attributes in your user pool. The Amazon Cognito console automatically sets required attributes as writeable.
-
You can't permit an app client to have write access to
email_verified
orphone_number_verified
. A user pool administrator can modify these values. A user can only change the value of these attributes through attribute verification.
-
- 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.
- 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 Scopes, M2M, and API authorization with resource servers. - Default redirect URI
-
Replaces the
redirect_uri
parameter in authentication requests for users with third-party IdPs. Configure this app client setting with theDefaultRedirectURI
parameter of a CreateUserPoolClient or UpdateUserPoolClient API request. This URL must also be a member of theCallbackURLs
for your app client. Amazon Cognito redirects authenticated sessions to this URL when:-
Your app client has one identity provider assigned and multiple callback URLs defined. Your user pool redirects authentication requests to the authorization server to the default redirect URI when they don't include a
redirect_uri
parameter. -
Your app client has one identity provider assigned and one callback URLs defined. In this scenario it's not necessary to define a default callback URL. Requests that don't include a
redirect_uri
parameter redirect to the one available callback URL.
-
- 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.
- 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 theopenid
scope. Theopenid
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. TheuserInfo
response to an access token with this scope alone returns all user attributes. -
When you request
openid
with other scopes likephone
,email
, orprofile
, the ID token anduserInfo
return the user's unique ID and the attributes defined by the additional scopes.
-
-
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
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 theopenid
scope.
For more information about scopes, see the list of standard OIDC scopes
. -
- 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
andprofile
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 Scopes, M2M, and API authorization with resource servers.
Client credentials grants add costs to your AWS bill. For more information, see Amazon Cognito Pricing
.
Creating 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