AWS cognito: Restructure Cognito authentication guide into decision aid and subpages
Summary
The authentication overview page was reorganized: the large inline 'Implement authentication flows' and 'Things to know' sections (app client flow configuration, session duration, lockout behavior, passwordless/passkey notes) were removed and replaced with a short decision aid linking to dedicated subpages (authentication-implement.html, authentication-flow-things-to-know.html).
Security assessment
This is a documentation restructuring that moves existing authentication content (including lockout and session-duration guidance) to separate pages rather than introducing new security guidance or fixing a vulnerability. The removed lockout text is security-adjacent but is relocated, not newly added.
Evidence
-After five failed sign-in attempts with a user's password, regardless of whether those are requested with unauthenticated or IAM-authorized API operations, Amazon Cognito locks out your user for one second.
Diff
diff --git a/cognito/latest/developerguide/authentication.md b/cognito/latest/developerguide/authentication.md index 50eb38e..56db4c1 100644 --- a//cognito/latest/developerguide/authentication.md +++ b//cognito/latest/developerguide/authentication.md @@ -7 +7 @@ -Implement authentication flowsThings to knowAuthentication flow example +Authentication flow example @@ -17,79 +17 @@ To verify the identity of users, Amazon Cognito supports authentication flows th -###### Topics - - * [Application-specific settings with app clients](./user-pool-settings-client-apps.html) - - * Implement authentication flows - - * Things to know about authentication with user pools - - * An example authentication session - - * [Configure authentication methods for managed login](./authentication-flows-selection-managedlogin.html) - - * [Manage authentication methods in AWS SDKs](./authentication-flows-selection-sdk.html) - - * [Authentication flows](./amazon-cognito-user-pools-authentication-flow-methods.html) - - * [Authorization models for API and SDK authentication](./authentication-flows-public-server-side.html) - - * [User pool sign-in with third party identity providers](./cognito-user-pools-identity-federation.html) - - - - -## Implement authentication flows - -Whether you're implementing [managed login](./authentication-flows-selection-managedlogin.html) or a [custom-built application front end](./authentication-flows-selection-sdk.html) with an AWS SDK for authentication, you must configure your app client for the types of authentication that you want to implement. The following information describes setup for authentication flows in your [app clients](./user-pool-settings-client-apps.html) and your application. - -App client supported flows - - -You can configure supported flows for your app clients in the Amazon Cognito console or with the API in an AWS SDK. After you configure your app client to support these flows, you can deploy them in your application. - -The following procedure configures available authentication flows for an app client with the Amazon Cognito console. - -###### To configure an app client for authentication flows (console) - - 1. Sign in to AWS and navigate to the [Amazon Cognito user pools console](https://console.aws.amazon.com/cognito/v2/idp). Choose a user pool or create a new one. - - 2. In your user pool configuration, select the **App clients** menu. Choose an app client or create a new one. - - 3. Under **App client information** , select **Edit**. - - 4. Under **App client flows** , choose the authentication flows that you want to support. - - - - -###### To configure an app client for authentication flows (API/SDK) - -To configure available authentication flows for an app client with the Amazon Cognito API, set the value of `ExplicitAuthFlows` in a [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html#CognitoUserPools-CreateUserPoolClient-request-ExplicitAuthFlows) or [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html#CognitoUserPools-UpdateUserPoolClient-request-ExplicitAuthFlows) request. The following is an example that provisions secure remote password (SRP) and choice-based authentication to a client. - - - "ExplicitAuthFlows": [ - "ALLOW_USER_AUTH", - "ALLOW_USER_SRP_AUTH" - ] - -When you configure app client supported flows, you can specify the following options and API values. - -App client flow support Authentication flow | Compatibility | Console | API ----|---|---|--- -[Choice-based authentication](./authentication-flows-selection-sdk.html#authentication-flows-selection-choice) | Server-side, client-side | Select an authentication type at sign-in | `ALLOW_USER_AUTH` -[Sign-in with persistent passwords](./amazon-cognito-user-pools-authentication-flow-methods.html#amazon-cognito-user-pools-authentication-flow-methods-password) | Client-side | Sign in with username and password | `ALLOW_USER_PASSWORD_AUTH` -[Sign-in with persistent passwords and secure payload](./amazon-cognito-user-pools-authentication-flow-methods.html#amazon-cognito-user-pools-authentication-flow-methods-srp) | Server-side, client-side | Sign in with secure remote password (SRP) | `ALLOW_USER_SRP_AUTH` -[Refresh tokens](./amazon-cognito-user-pools-authentication-flow-methods.html#amazon-cognito-user-pools-authentication-flow-methods-refresh) | Server-side, client-side | Get new user tokens from existing authenticated sessions | `ALLOW_REFRESH_TOKEN_AUTH` -[Server-side authentication](./authentication-flows-public-server-side.html#amazon-cognito-user-pools-server-side-authentication-flow) | Server-side | Sign in with server-side administrative credentials | `ALLOW_ADMIN_USER_PASSWORD_AUTH` -[Custom authentication](./amazon-cognito-user-pools-authentication-flow-methods.html#amazon-cognito-user-pools-authentication-flow-methods-custom) | Server-side and client-side custom-built applications. Not compatible with managed login. | Sign in with custom authentication flows from Lambda triggers | `ALLOW_CUSTOM_AUTH` - -Implement flows in your application - - -Managed login automatically makes your configured authentication options available in your sign-pages. In custom-built applications, start authentication with a declaration of the initial flow. - - * To choose from a list of flow options for a user, declare [choice-based authentication](./authentication-flows-selection-sdk.html#authentication-flows-selection-choice) with the `USER_AUTH` flow. This flow has available authentication methods that aren't available in client-based authentication flows, for example [passkey](./amazon-cognito-user-pools-authentication-flow-methods.html#amazon-cognito-user-pools-authentication-flow-methods-passkey) and [passwordless](./amazon-cognito-user-pools-authentication-flow-methods.html#amazon-cognito-user-pools-authentication-flow-methods-passwordless) authentication. - - * To choose your authentication flow up front, declare [client-based authentication](./authentication-flows-selection-sdk.html#authentication-flows-selection-client) with any other flow that's available in your app client. - - - +Before you configure the details, choose the authentication approach that fits your application. The following decision aid summarizes the two entry points and, within a custom-built application, the two initial sign-in flows. Each option links to its detailed section. @@ -97 +19 @@ Managed login automatically makes your configured authentication options availab -When you sign users in, the body of your [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html#CognitoUserPools-InitiateAuth-request-AuthFlow) or [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html#CognitoUserPools-AdminInitiateAuth-request-AuthFlow) request must include an `AuthFlow` parameter. +**Do you want Amazon Cognito to host the sign-in pages, or build your own front end?** @@ -99 +20,0 @@ When you sign users in, the body of your [InitiateAuth](https://docs.aws.amazon. -Choice-based authentication: @@ -100,0 +22 @@ Choice-based authentication: +If you want the lowest-effort path, use [managed login](./authentication-flows-selection-managedlogin.html). Amazon Cognito hosts the sign-in, sign-out, and password-reset pages, and your application processes the result with an OpenID Connect (OIDC) relying-party library. Managed login automatically presents the authentication methods that your user pool and app client configuration allow. @@ -102 +24 @@ Choice-based authentication: - "AuthFlow": "USER_AUTH" +If you want to build your own UI and control the sign-in logic, use an [AWS SDK](./authentication-flows-selection-sdk.html). Your application calls the user pools API directly and you implement the challenge-response logic. @@ -104 +26 @@ Choice-based authentication: -Client-based authentication with SRP: +**In a custom-built application, do you collect the sign-in method from the user, or declare it up front?** @@ -107 +29 @@ Client-based authentication with SRP: - "AuthFlow": "USER_SRP_AUTH" +Choose [choice-based authentication](./authentication-flows-selection-sdk.html#authentication-flows-selection-choice) (the `USER_AUTH` flow) when you want to offer users a list of available sign-in methods and let them select one. This flow is the only way to offer [passwordless](./amazon-cognito-user-pools-authentication-flow-methods.html#amazon-cognito-user-pools-authentication-flow-methods-passwordless) and [passkey](./amazon-cognito-user-pools-authentication-flow-methods.html#amazon-cognito-user-pools-authentication-flow-methods-passkey) sign-in. @@ -109 +31 @@ Client-based authentication with SRP: -## Things to know about authentication with user pools +Choose [client-based authentication](./authentication-flows-selection-sdk.html#authentication-flows-selection-client) when your application already knows how the user will sign in and declares the flow up front, for example `USER_SRP_AUTH`. Client-based authentication is the only way to use the [custom authentication](./amazon-cognito-user-pools-authentication-flow-methods.html#amazon-cognito-user-pools-authentication-flow-methods-custom) and [refresh token](./amazon-cognito-user-pools-authentication-flow-methods.html#amazon-cognito-user-pools-authentication-flow-methods-refresh) flows. @@ -111 +33 @@ Client-based authentication with SRP: -Consider the following information in the design of your authentication model with Amazon Cognito user pools. +**Prerequisites for choice-based authentication** @@ -113 +34,0 @@ Consider the following information in the design of your authentication model wi -**Authentication flows in managed login and the hosted UI** @@ -115,35 +36 @@ Consider the following information in the design of your authentication model wi - -[Managed login](./cognito-user-pools-managed-login.html) has more options for authentication than the classic hosted UI. For example, users can do passwordless and passkey authentication only in managed login. - -**Custom authentication flows only available in AWS SDK authentication** - - -You can't do _custom authentication flows_ , or [custom authentication with Lambda triggers](./user-pool-lambda-challenge.html), with managed login or the classic hosted UI. Custom authentication is available in [authentication with AWS SDKs](./authentication-flows-selection-sdk.html). - -**Managed login for external identity provider (IdP) sign-in** - - -You can't sign users in through [third-party IdPs](./cognito-user-pools-identity-federation.html) in [authentication with AWS SDKs](./authentication-flows-selection-sdk.html). You must implement managed login or the classic hosted UI, redirect to IdPs, and then process the resulting authentication object with OIDC libraries in your application. For more information about managed login, see [User pool managed login](./cognito-user-pools-managed-login.html). - -**Passwordless authentication effect on other user features** - - -Activation of passwordless sign-in with [one-time passwords](./amazon-cognito-user-pools-authentication-flow-methods.html#amazon-cognito-user-pools-authentication-flow-methods-passwordless) or [passkeys](./amazon-cognito-user-pools-authentication-flow-methods.html#amazon-cognito-user-pools-authentication-flow-methods-passkey) in your user pool and app client has an effect on user creation and migration. When passwordless sign-in is active: - - 1. Administrators can create users without passwords. The default invitation message template changes to no longer include the `{###}` password placeholder. For more information, see [Creating user accounts as administrator](./how-to-create-user-accounts.html). - - 2. For SDK-based [SignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html) operations, users aren't required to supply a password when they sign up. Managed login and the hosted UI require a password in the sign-up page, even if passwordless authentication is permitted. For more information, see [Signing up and confirming user accounts](./signing-up-users-in-your-app.html). - - 3. Users imported from a CSV file can sign in immediatelywith passwordless options, without a password reset, if their attributes include an email address or phone number for an available passwordless sign-in option. For more information, see [Importing users into user pools from a CSV file](./cognito-user-pools-using-import-tool.html). - - 4. Passwordless authentication doesn't invoke the [user migration Lambda trigger](./user-pool-lambda-migrate-user.html). - - 5. Users who sign in with a one-time password (OTP) first factor can't add a [multi-factor authentication (MFA)](./user-pool-settings-mfa.html) factor to their session. Passkeys with user verification can satisfy MFA requirements when configured with `MULTI_FACTOR_WITH_USER_VERIFICATION`. - - - - -**Passkey relying party URLs can't be on the public suffix list** - - -You can use domain names that you own, like `www.example.com`, as the relying party (RP) ID in your passkey configuration. This configuration is intended to support custom-built applications that run on domains that you own. The [public suffix list](https://publicsuffix.org/), or PSL, contains protected high-level domains. Amazon Cognito returns an error when you attempt to set your RP URL to a domain on the PSL. +Choice-based authentication applies to both managed login and the AWS SDKs. To use it, add `ALLOW_USER_AUTH` to the allowed authentication flows of your app client. The passwordless and passkey methods additionally require a [managed login domain](./managed-login-branding.html) and a [feature plan](./cognito-sign-in-feature-plans.html) above the **Lite** tier (Essentials or Plus). @@ -153,32 +40 @@ You can use domain names that you own, like `www.example.com`, as the relying pa - * Authentication session flow duration - - * Lockout behavior for failed sign-in attempts - - - - -### Authentication session flow duration - -Depending on the features of your user pool, you can end up responding to several challenges to `InitiateAuth` and `RespondToAuthChallenge` before your app retrieves tokens from Amazon Cognito. Amazon Cognito includes a session string in the response to each request. To combine your API requests into an authentication flow, include the session string from the response to the previous request in each subsequent request. By default, your users have three minutes to complete each challenge before the session string expires. To adjust this period, change your app client **Authentication flow session duration**. The following procedure describes how to change this setting in your app client configuration. - -###### Note - -**Authentication flow session duration** settings apply to authentication with the Amazon Cognito user pools API. Managed login sets session duration to 3 minutes for multi-factor authentication and 8 minutes for forced password change during end-user's first sign-in with temporary password. - -Amazon Cognito console - - -###### To configure app client authentication flow session duration (AWS Management Console) - - 1. From the **App integration** tab in your user pool, select the name of your app client from the **App clients and analytics** container. - - 2. Choose **Edit** in the **App client information** container. - - 3. Change the value of **Authentication flow session duration** to the validity duration that you want, in minutes, for SMS and email MFA codes. This also changes the amount of time that any user has to complete any authentication challenge in your app client. - - 4. Choose **Save changes**. - - - - -User pools API + * [Application-specific settings with app clients](./user-pool-settings-client-apps.html) @@ -185,0 +42 @@ User pools API + * [Implement authentication flows](./authentication-implement.html) @@ -187 +44 @@ User pools API -###### To configure app client authentication flow session duration (Amazon Cognito API) + * [Things to know about authentication with user pools](./authentication-flow-things-to-know.html) @@ -189 +46 @@ User pools API - 1. Prepare an `UpdateUserPoolClient` request with your existing user pool settings from a `DescribeUserPoolClient` request. Your `UpdateUserPoolClient` request must include all existing app client properties. + * An example authentication session @@ -191 +48 @@ User pools API - 2. Change the value of `AuthSessionValidity` to the validity duration that you want, in minutes, for SMS MFA codes. This also changes the amount of time that any user has to complete any authentication challenge in your app client. + * [Configure authentication methods for managed login](./authentication-flows-selection-managedlogin.html) @@ -192,0 +50 @@ User pools API + * [Manage authentication methods in AWS SDKs](./authentication-flows-selection-sdk.html) @@ -193,0 +52 @@ User pools API + * [Authentication flows](./amazon-cognito-user-pools-authentication-flow-methods.html) @@ -194,0 +54 @@ User pools API + * [Authorization models for API and SDK authentication](./authentication-flows-public-server-side.html)