Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(js): restore missing gen1 documents #7769

Merged
merged 6 commits into from
Jul 5, 2024
Merged
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -659,6 +659,20 @@ signInWithRedirect({ provider: {
}})
```

### Auto sign-in

The `autoSignIn` API will automatically sign-in a user when it was previously enabled by the `signUp` API and after any of the following cases has completed:

- User confirmed their account with a verification code sent to their phone or email (default option).
- User confirmed their account with a verification link sent to their phone or email. In order to enable this option you need to go to the [Amazon Cognito console](https://aws.amazon.com/pm/cognito), look for your userpool, then go to the `Messaging` tab and enable `link` mode inside the `Verification message` option. Finally you need to define the `signUpVerificationMethod` to `link` inside the `Cognito` option of your `Auth` config.

```ts title="amplify/auth/resource.ts"
import { autoSignIn } from 'aws-amplify/auth';

await autoSignIn();

```
joon-won marked this conversation as resolved.
Show resolved Hide resolved

</InlineFilter>
<InlineFilter filters={['react-native']}>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,13 @@ export const meta = {
title: 'Switching authentication flows',
description: 'Learn how to switch between different auth flows',
platforms: [
'angular',
'javascript',
'nextjs',
'react',
'react-native',
'swift',
'vue'
]
};

Expand All @@ -20,6 +26,8 @@ export function getStaticProps() {
};
}

<InlineFilter filters={["swift"]}>

`AWSCognitoAuthPlugin` allows you to switch between different auth flows while initiating signIn. You can configure the flow in the `amplifyconfiguration.json` file or pass the `authFlowType` as a runtime parameter to the `signIn` api call.

For client side authentication there are four different flows that can be configured during runtime:
Expand Down Expand Up @@ -105,6 +113,89 @@ The flow is initiated by calling `signIn` with `AuthSignInOptions` configured wi

Follow the instructions in [Custom Auth Sign In](/gen1/[platform]/build-a-backend/auth/sign-in-custom-flow/) to learn about how to integrate custom authentication flow in your application with the Auth APIs.

</InlineFilter>

<InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>

For client side authentication there are three different flows:

1. `USER_SRP_AUTH`: The `USER_SRP_AUTH` flow uses the [SRP protocol (Secure Remote Password)](https://en.wikipedia.org/wiki/Secure_Remote_Password_protocol) where the password never leaves the client and is unknown to the server. This is the recommended flow and is used by default.

2. `USER_PASSWORD_AUTH`: The `USER_PASSWORD_AUTH` flow will send user credentials to the backend without applying SRP encryption. If you want to migrate users to Cognito using the "Migration" trigger and avoid forcing users to reset their passwords, you will need to use this authentication type because the Lambda function invoked by the trigger needs to verify the supplied credentials.

3. `CUSTOM_WITH_SRP` & `CUSTOM_WITHOUT_SRP`: Allows for a series of challenge and response cycles that can be customized to meet different requirements.

The Auth flow can be customized when calling `signIn`, for example:

```ts title="src/main.ts"
await signIn({
username: "hello@mycompany.com",
password: "hunter2",
options: {
authFlowType: 'USER_PASSWORD_AUTH'
}
})
```

> For more information about authentication flows, please visit [AWS Cognito developer documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-authentication-flow.html#amazon-cognito-user-pools-custom-authentication-flow)

## USER_PASSWORD_AUTH flow

A use case for the `USER_PASSWORD_AUTH` authentication flow is migrating users into Amazon Cognito

### Set up auth backend

In order to use the authentication flow `USER_PASSWORD_AUTH`, your Cognito app client has to be configured to allow it. In the AWS Console, this is done by ticking the checkbox at General settings > App clients > Show Details (for the affected client) > Enable username-password (non-SRP) flow. If you're using the AWS CLI or CloudFormation, update your app client by adding `USER_PASSWORD_AUTH` to the list of "Explicit Auth Flows".

### Migrate users with Amazon Cognito

Amazon Cognito provides a trigger to migrate users from your existing user directory seamlessly into Cognito. You achieve this by configuring your User Pool's "Migration" trigger which invokes a Lambda function whenever a user that does not already exist in the user pool authenticates, or resets their password.

In short, the Lambda function will validate the user credentials against your existing user directory and return a response object containing the user attributes and status on success. An error message will be returned if an error occurs. Visit [Amazon Cognito user pools import guide](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-import-using-lambda.html) for migration flow and more detailed instruction, and [Amazon Cognito Lambda trigger guide](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-migrate-user.html#cognito-user-pools-lambda-trigger-syntax-user-migration) on how to set up lambda to handle request and response objects.

## `CUSTOM_WITH_SRP` & `CUSTOM_WITHOUT_SRP` flows

Amazon Cognito user pools supports customizing the authentication flow to enable custom challenge types,
in addition to a password in order to verify the identity of users. These challenge types may include CAPTCHAs
or dynamic challenge questions. The `CUSTOM_WITH_SRP` flow requires a password when calling `signIn`. Both of
these flows map to the `CUSTOM_AUTH` flow in Cognito.

To define your challenges for custom authentication flow, you need to implement three Lambda triggers for Amazon Cognito.

<Callout>

For more information about working with Lambda Triggers for custom authentication challenges, please visit [Amazon Cognito Developer Documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-challenge.html).

</Callout>

### Custom authentication flow

To initiate a custom authentication flow in your app, call `signIn` without a password. A custom challenge needs to be answered using the `confirmSignIn` API:

```ts title="src/main.ts"
import { signIn, confirmSignIn } from 'aws-amplify/auth';

const challengeResponse = 'the answer for the challenge';

const { nextStep } = await signIn({
username,
options: {
authFlowType: 'CUSTOM_WITHOUT_SRP',
},
});

if (nextStep.signInStep === 'CONFIRM_SIGN_IN_WITH_CUSTOM_CHALLENGE') {
// to send the answer of the custom challenge
await confirmSignIn({ challengeResponse });
}
```

### CAPTCHA authentication

To create a CAPTCHA challenge with a Lambda Trigger, please visit [AWS Amplify Google reCAPTCHA challenge example](/[platform]/build-a-backend/functions/examples/google-recaptcha-challenge/) for detailed examples.

</InlineFilter>

<Callout>

For more information about working with Lambda Triggers for custom authentication challenges, please visit [Amazon Cognito Developer Documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-challenge.html).
Expand Down