AWS cognito medium security documentation change
Summary
Expanded documentation for password and SRP authentication flows, added choice-based authentication configuration details, included screenshots and API examples for client/choice-based flows, clarified challenge response sequences, and updated placeholder values for security.
Security assessment
Added emphasis on SRP protocol usage which avoids transmitting plaintext passwords, introduced security-focused placeholder values ([User's password]) instead of example credentials, and expanded guidance on secure authentication flow configurations. These changes promote security best practices but do not reference a specific vulnerability.
Diff
diff --git a/cognito/latest/developerguide/amazon-cognito-user-pools-authentication-flow-methods.md b/cognito/latest/developerguide/amazon-cognito-user-pools-authentication-flow-methods.md index 8614f5641..dbbc27fa7 100644 --- a/cognito/latest/developerguide/amazon-cognito-user-pools-authentication-flow-methods.md +++ b/cognito/latest/developerguide/amazon-cognito-user-pools-authentication-flow-methods.md @@ -79 +79 @@ Activate password sign-in -To activate sign-in with username and password, configure your app client to permit it. In the Amazon Cognito console, navigate to the **App clients** menu under **Applications** in your user pool configuration. To permit username-password sign-in for a client-side mobile or native app, select or create an app client and choose **Sign in with username and password: ALLOW_USER_PASSWORD_AUTH**. To permit username-password sign-in for a server-side or web app, choose **Sign in with server-side administrative credentials: ALLOW_ADMIN_USER_PASSWORD_AUTH**. +To activate [client-based authentication](./authentication-flows-selection-sdk.html#authentication-flows-selection-client) with username and password, configure your app client to permit it. In the Amazon Cognito console, navigate to the **App clients** menu under **Applications** in your user pool configuration. To permit plain-password sign-in for a client-side mobile or native app, edit an app client and choose **Sign in with username and password: ALLOW_USER_PASSWORD_AUTH** under **Authentication flows**. To permit plain-password sign-in for a server-side app, edit an app client and choose **Sign in with server-side administrative credentials: ALLOW_ADMIN_USER_PASSWORD_AUTH**. @@ -81 +81,9 @@ To activate sign-in with username and password, configure your app client to per -In the user pools API, configure `ExplicitAuthFlows` with the required option in a [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) or [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html) request. +To activate [choice-based authentication](./authentication-flows-selection-sdk.html#authentication-flows-selection-choice) with username and password, configure your app client to permit it. Edit your app client and choose **Choice-based sign-in: ALLOW_USER_AUTH**. + + + +To verify that password authentication is available in choice-based authentication flows, navigate to the **Sign-in menu** and review the section under **Options for choice-based sign-in**. You can sign in with plain-password authentication if **Password** is visible under **Available choices**. The **Password** option includes the plain and SRP username-password authentication variants. + + + +Configure `ExplicitAuthFlows` with your preferred username-and-password authentication options in a [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) or [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html) request. @@ -86 +94,2 @@ In the user pools API, configure `ExplicitAuthFlows` with the required option in - "ALLOW_ADMIN_USER_PASSWORD_AUTH" + "ALLOW_ADMIN_USER_PASSWORD_AUTH", + "ALLOW_USER_AUTH" @@ -88,0 +98,13 @@ In the user pools API, configure `ExplicitAuthFlows` with the required option in +In a [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) or [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) request, configure `Policies` with the choice-based authentication flows that you want to support. The `PASSWORD` value in `AllowedFirstAuthFactors` includes both the plain-password and SRP authentication flow options. + + + "Policies": { + "SignInPolicy": { + "AllowedFirstAuthFactors": [ + "PASSWORD", + "EMAIL_OTP", + "WEB_AUTHN" + ] + } + } + @@ -92 +114 @@ Choice-based sign-in with a password -To sign a user in to a client-side app with username-password authentication, configure the body of your [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) request as follows. Amazon Cognito responds with a `ChallengeName` of `PASSWORD` if the current user is eligible for username-password authentication. Otherwise, it responds with a list of available challenges. This set of parameters is the minimum required for sign-in. Additional parameters are available. +To sign a user in to an application with username-password authentication, configure the body of your [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) or [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) request as follows. This sign-in request succeeds or continues to the next challenge if the current user is eligible for username-password authentication. Otherwise, it responds with a list of available primary-factor authentication challenges. This set of parameters is the minimum required for sign-in. Additional parameters are available. @@ -99 +121,2 @@ To sign a user in to a client-side app with username-password authentication, co - "PREFERRED_CHALLENGE" : "PASSWORD" + "PREFERRED_CHALLENGE" : "PASSWORD", + "PASSWORD" : "[User's password]" @@ -104 +127 @@ To sign a user in to a client-side app with username-password authentication, co -To sign a user in to a server-side app with username-password authentication, configure the body of your [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) request as follows. Your application must sign this request with AWS credentials. Amazon Cognito responds with a `ChallengeName` of `PASSWORD` if the current user is eligible for username-password authentication. Otherwise, it responds with a list of available challenges. This set of parameters is the minimum required for sign-in. Additional parameters are available. +You can also omit the `PREFERRED_CHALLENGE` value and receive a response that contains a list of eligible sign-in factors for the user. @@ -110,2 +133 @@ To sign a user in to a server-side app with username-password authentication, co - "USERNAME" : "testuser", - "PREFERRED_CHALLENGE" : "PASSWORD" + "USERNAME" : "testuser" @@ -115,0 +138,15 @@ To sign a user in to a server-side app with username-password authentication, co +If you didn't submit a preferred challenge or the submitted user isn't eligible for their preferred challenge, Amazon Cognito returns a list of options in `AvailableChallenges`. When `AvailableChallenges` includes a `ChallengeName` of `PASSWORD`, you can continue authentication with a [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) or [AdminRespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminRespondToAuthChallenge.html) challenge response in the format that follows. You must pass a `Session` parameter that associates the challenge response with the API response to your initial sign-in request. This set of parameters is the minimum required for sign-in. Additional parameters are available. + + + { + "ChallengeName": "PASSWORD", + "ChallengeResponses": { + "USERNAME" : "testuser", + "PASSWORD" : "[User's Password]" + }, + "ClientId": "1example23456789", + "Session": "[Session ID from the previous response" + } + +Amazon Cognito responds to eligible and successful preferred-challenge requests and `PASSWORD` challenge responses with tokens or an additional required challenge like multi-factor authentication (MFA). + @@ -126 +163 @@ To sign a user in to a client-side app with username-password authentication, co - "PASSWORD" : "Example1234!" + "PASSWORD" : "[User's password]" @@ -138 +175 @@ To sign a user in to a server-side app with username-password authentication, co - "PASSWORD" : "Example1234!" + "PASSWORD" : "[User's password]" @@ -142,0 +180,2 @@ To sign a user in to a server-side app with username-password authentication, co +Amazon Cognito responds to successful requests with tokens or an additional required challenge like multi-factor authentication (MFA). + @@ -145 +184,3 @@ To sign a user in to a server-side app with username-password authentication, co -Another form of the username-password sign-in methods in user pools is with the Secure Remote Password (SRP) protocol. This option sends proof of knowledge of a password—a password hash and a salt—that your user pool can verify. With no readable secret information in the request to Amazon Cognito, your application is the only entity that processes the passwords that users enter. SRP authentication involves mathematical calculations that are best done by an existing component that you can import in your SDK. SRP is typically implemented in client-side applications like mobile apps. For more information about the protocol, see [The Stanford SRP Homepage](http://srp.stanford.edu/). [Wikipedia](https://en.wikipedia.org/wiki/Secure_Remote_Password_protocol) also has resources and examples. +Another form of the username-password sign-in methods in user pools is with the Secure Remote Password (SRP) protocol. This option sends proof of knowledge of a password—a password hash and a salt—that your user pool can verify. With no readable secret information in the request to Amazon Cognito, your application is the only entity that processes the passwords that users enter. SRP authentication involves mathematical calculations that are best done by an existing component that you can import in your SDK. SRP is typically implemented in client-side applications like mobile apps. For more information about the protocol, see [The Stanford SRP Homepage](http://srp.stanford.edu/). [Wikipedia](https://en.wikipedia.org/wiki/Secure_Remote_Password_protocol) also has resources and examples. [A variety of public libraries](https://en.wikipedia.org/wiki/Secure_Remote_Password_protocol#Implementations) are available to perform the SRP calculations for your authentication flows. + +The initiate-challenge-respond sequence of Amazon Cognito authentication validates users and their passwords with SRP. You must configure your user pool and app client to support SRP authentication, then implement the logic of sign-in requests and challenge responses in your application. Your SRP libraries can generate the random numbers and calculated values that demonstrate to your user pool that you are in possession of a user's password. Your application fills in these calculated values to the JSON-formatted `AuthParameters` and `ChallengeParameters` fields in the Amazon Cognito user pools API operations and SDK methods for authentication. @@ -150 +191 @@ Activate SRP sign-in -To activate sign-in with username and password, configure your app client to permit it. In the Amazon Cognito console, navigate to the **App clients** menu under **Applications** in your user pool configuration. To permit username-password sign-in for a client-side mobile or native app, select or create an app client and choose **Sign in with username and password: ALLOW_USER_PASSWORD_AUTH**. To permit username-password sign-in for a server-side or web app, choose **Sign in with server-side administrative credentials: ALLOW_ADMIN_USER_PASSWORD_AUTH**. +To activate [client-based authentication](./authentication-flows-selection-sdk.html#authentication-flows-selection-client) with username and SRP, configure your app client to permit it. In the Amazon Cognito console, navigate to the **App clients** menu under **Applications** in your user pool configuration. To permit SRP sign-in for a client-side mobile or native app, edit an app client and choose **Sign in with secure remote password (SRP): ALLOW_USER_SRP_AUTH** under **Authentication flows**. @@ -152 +193,9 @@ To activate sign-in with username and password, configure your app client to per -In the user pools API, configure `ExplicitAuthFlows` with the required option in a [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) or [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html) request. +To activate [choice-based authentication](./authentication-flows-selection-sdk.html#authentication-flows-selection-choice) with username and SRP, edit your app client and choose **Choice-based sign-in: ALLOW_USER_AUTH**. + + + +To verify that SRP authentication is available in your choice-based authentication flows, navigate to the **Sign-in menu** and review the section under **Options for choice-based sign-in**. You can sign in with SRP authentication if **Password** is visible under **Available choices**. The **Password** option includes the plaintext and SRP username-password authentication variants. + + + +Configure `ExplicitAuthFlows` with your preferred username-and-password authentication options in a [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) or [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html) request. @@ -156 +205,2 @@ In the user pools API, configure `ExplicitAuthFlows` with the required option in - "ALLOW_USER_SRP_AUTH" + "ALLOW_USER_SRP_AUTH", + "ALLOW_USER_AUTH" @@ -158,0 +209,13 @@ In the user pools API, configure `ExplicitAuthFlows` with the required option in +In a [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) or [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) request, configure `Policies` with the choice-based authentication flows that you want to support. The `PASSWORD` value in `AllowedFirstAuthFactors` includes both the plaintext-password and SRP authentication flow options. + + + "Policies": { + "SignInPolicy": { + "AllowedFirstAuthFactors": [ + "PASSWORD", + "EMAIL_OTP", + "WEB_AUTHN" + ] + } + } + @@ -162 +225 @@ Choice-based sign-in with SRP -To sign a user in to a client-side app with username-password authentication, configure the body of your [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) request as follows. Amazon Cognito responds with a `ChallengeName` of `PASSWORD_SRP` if the current user is eligible for username-password authentication. Otherwise, it responds with a list of available challenges. This set of parameters is the minimum required for sign-in. Additional parameters are available. +To sign a user in to an application with username-password authentication with SRP, configure the body of your [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) or [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) request as follows. This sign-in request succeeds or continues to the next challenge if the current user is eligible for username-password authentication. Otherwise, it responds with a list of available primary-factor authentication challenges. This set of parameters is the minimum required for sign-in. Additional parameters are available. @@ -169 +232,2 @@ To sign a user in to a client-side app with username-password authentication, co - "PREFERRED_CHALLENGE" : "PASSWORD_SRP" + "PREFERRED_CHALLENGE" : "PASSWORD_SRP", + "SRP_A" : "[g^a % N]" @@ -174 +238 @@ To sign a user in to a client-side app with username-password authentication, co -To sign a user in to a server-side app with username-password authentication, configure the body of your [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) request as follows. Your application must sign this request with AWS credentials. Amazon Cognito responds with a `ChallengeName` of `PASSWORD_SRP` if the current user is eligible for username-password authentication. Otherwise, it responds with a list of available challenges. This set of parameters is the minimum required for sign-in. Additional parameters are available. +You can also omit the `PREFERRED_CHALLENGE` value and receive a response that contains a list of eligible sign-in factors for the user. @@ -180,2 +244 @@ To sign a user in to a server-side app with username-password authentication, co - "USERNAME" : "testuser", - "PREFERRED_CHALLENGE" : "PASSWORD_SRP" + "USERNAME" : "testuser" @@ -185,0 +249,29 @@ To sign a user in to a server-side app with username-password authentication, co +If you didn't submit a preferred challenge or the submitted user isn't eligible for their preferred challenge, Amazon Cognito returns a list of options in `AvailableChallenges`. When `AvailableChallenges` includes a `ChallengeName` of `PASSWORD_SRP`, you can continue authentication with a [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) or [AdminRespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminRespondToAuthChallenge.html) challenge response in the format that follows. You must pass a `Session` parameter that associates the challenge response with the API response to your initial sign-in request. This set of parameters is the minimum required for sign-in. Additional parameters are available. + + + { + "ChallengeName": "PASSWORD_SRP", + "ChallengeResponses": { + "USERNAME" : "testuser", + "SRP_A" : "[g^a % N]" + }, + "ClientId": "1example23456789", + "Session": "[Session ID from the previous response" + } + +Amazon Cognito responds to eligible preferred-challenge requests and `PASSWORD_SRP` challenge responses with a `PASSWORD_VERIFIER` challenge. Your client must complete SRP calculations and respond to the challenge in a [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) or [AdminRespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminRespondToAuthChallenge.html) request. + + + { + "ChallengeName": "PASSWORD_VERIFIER", + "ChallengeResponses": { + "PASSWORD_CLAIM_SIGNATURE" : "string", + "PASSWORD_CLAIM_SECRET_BLOCK" : "string", + "TIMESTAMP" : "string" + }, + "ClientId": "1example23456789", + "Session": "[Session ID from the previous response]" + } + +On a successful `PASSWORD_VERIFIER` challenge response, Amazon Cognito issues tokens or another required challenge like multi-factor authentication (MFA). + @@ -195 +287 @@ The client generates `SRP_A` from a generator modulo N _g_ raised to the power o - "AuthFlow": "USER_PASSWORD_AUTH", + "AuthFlow": "USER_SRP_AUTH", @@ -198 +290 @@ The client generates `SRP_A` from a generator modulo N _g_ raised to the power o - "SRP_A" : "g^a" + "SRP_A" : "[g^a % N]" @@ -217,5 +309 @@ Amazon Cognito responds with a `PASSWORD_VERIFIER` challenge. Your client must c -### Built-in authentication flow and challenges - -Amazon Cognito contains built-in `AuthFlow` and `ChallengeName` values so that a standard authentication flow can validate a username and password through the Secure Remote Password (SRP) protocol. The AWS SDKs have built-in support for these flows with Amazon Cognito. - -The flow starts by sending `USER_SRP_AUTH` as the `AuthFlow` to `InitiateAuth`. You also send `USERNAME` and `SRP_A` values in `AuthParameters`. If the `InitiateAuth` call is successful, the response has included `PASSWORD_VERIFIER` as the `ChallengeName` and `SRP_B` in the challenge parameters. The app then calls `RespondToAuthChallenge` with the `PASSWORD_VERIFIER` `ChallengeName` and the necessary parameters in `ChallengeResponses`. If the call to `RespondToAuthChallenge` is successful and the user signs in, Amazon Cognito issues tokens. If you activated multi-factor authentication (MFA) for the user, Amazon Cognito returns the `ChallengeName` of `SMS_MFA`. The app can provide the necessary code through another call to `RespondToAuthChallenge`. +On a successful `PASSWORD_VERIFIER` challenge response, Amazon Cognito issues tokens or another required challenge like multi-factor authentication (MFA). @@ -259 +347 @@ The sign-in operation returns the response that indicates successful authenticat - * The user is eligible for the requested `PREFERRED_CHALLENGE` authentication method. + * The user is eligible for the OTP authentication method. @@ -295 +383 @@ Sign in with passwordless -Passwordless sign-in doesn't have an `AuthFlow` that you can specify in [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) and [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html). Instead, you must declare an `AuthFlow` of `USER_AUTH` and request a sign-in option or choose your passwordless option from the response from your user pool. To sign a user in to an application, configure the body of your `InitiateAuth` or `AdminInitiateAuth` request as follows. This set of parameters is the minimum required for sign-in. Additional parameters are available. +Passwordless sign-in doesn't have a [client-based](./authentication-flows-selection-sdk.html#authentication-flows-selection-client) `AuthFlow` that you can specify in [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) and [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html). OTP authentication is only available in the [choice-based](./authentication-flows-selection-sdk.html#authentication-flows-selection-choice) `AuthFlow` of `USER_AUTH`, where you can request a preferred sign-in option or choose the passwordless option from a user's [AvailableChallenges](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html#CognitoUserPools-InitiateAuth-response-AvailableChallenges). To sign a user in to an application, configure the body of your `InitiateAuth` or `AdminInitiateAuth` request as follows. This set of parameters is the minimum required for sign-in. Additional parameters are available. @@ -308 +396,3 @@ In this example, we don't know which way the user wants to sign in. If we add a -Amazon Cognito responds includes an `AvailableChallenges` parameter. +You can instead add `"PREFERRED_CHALLENGE": "EMAIL_OTP"` or `"PREFERRED_CHALLENGE": "SMS_OTP"` to `AuthParameters` in this example. If the user is eligible for that preferred method, your user pool immediately sends a code to the user's email address or phone number and returns `"ChallengeName": "EMAIL_OTP"` or `"ChallengeName": "SMS_OTP"`. + +If you don't specify a preferred challenge, Amazon Cognito responds with an `AvailableChallenges` parameter. @@ -317 +407 @@ Amazon Cognito responds includes an `AvailableChallenges` parameter. - "Session": "[Session ID from the previous response]" + "Session": "[Session ID]" @@ -334,0 +425,2 @@ Amazon Cognito responds with an `EMAIL_OTP` challenge and sends a code to your u +This would also be the next challenge response if you requested `EMAIL_OTP` as a `PREFERRED_CHALLENGE`. +