diff --git a/public/images/studio/import-auth-selection.png b/public/images/studio/import-auth-selection.png new file mode 100644 index 00000000000..7b444d17dd8 Binary files /dev/null and b/public/images/studio/import-auth-selection.png differ diff --git a/public/images/studio/import-auth.png b/public/images/studio/import-auth.png new file mode 100644 index 00000000000..0c4ae4297f3 Binary files /dev/null and b/public/images/studio/import-auth.png differ diff --git a/public/images/studio/import-identity-pool.png b/public/images/studio/import-identity-pool.png new file mode 100644 index 00000000000..387b5e127de Binary files /dev/null and b/public/images/studio/import-identity-pool.png differ diff --git a/src/pages/console/auth/import.mdx b/src/pages/console/auth/import.mdx index dbf53965782..f60820318ae 100644 --- a/src/pages/console/auth/import.mdx +++ b/src/pages/console/auth/import.mdx @@ -1,31 +1,43 @@ export const meta = { title: `Import Amazon Cognito resources`, - description: `Configure Amplify Studio to use existing Amazon Cognito user pool and identity pool resources as an authentication and authorization mechanism for other Amplify categories ( For example, API, Storage, and more).`, + description: `Configure Amplify Studio to use existing Amazon Cognito user pool and identity pool resources as an authentication and authorization mechanism for other Amplify categories ( For example, API, Storage, and more).` }; -You can import existing Amazon Cognito resources into your Amplify project using Amplify Studio. To get started, choose **Authentication** from the **Set up** menu in your app's Studio. On the **Authentication** page, choose **Reuse existing Amazon Cognito resources**. - -This feature is particularly useful if you’re trying to do the following: +Importing an Amazon Cognito resource is particularly useful if you’re trying to do the following: - Authorize user access to fields/tables in Amplify Studio's data model - Manage users and groups from Amplify Studio (instead of having to login to the AWS console) - Reuse the imported auth resource across Amplify environments ## Import an existing Cognito user pool -To successfully import your user pool, your user pools require at least two app clients with the following conditions: + +You can import existing Amazon Cognito resources into your Amplify project using Amplify Studio. + +To get started, Choose **Authentication** from the **Set up** menu in your app's Studio. On the **Authentication** page, choose **Reuse existing Amazon Cognito resources**. + +![import Amazon Cognito resource](/images/studio/import-auth.png) + +Select a Cognito user pool and App clients required for your application. + +![Select user pool and app clients](/images/studio/import-auth-selection.png) + +then click `Import` to deploy your changes. + +It is best practice to create at least two app clients with the following conditions: - At least one “Web app client”: an app client without a client secret - At least one “Native app client“: an app client with a client secret -The client secret is used by applications that have a server-side component that secure the client secret, which is why the native app client needs one. +The client secret is used by applications that have a server-side component that secure the client secret, which is why the native app client needs one. If the Cognito user pool contains only one App Client, this will be used for both your web and mobile clients. -To complete the import procedure, run the `amplify push` command. +[Learn more about getting started with Cognito User Pools](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-with-cognito-user-pools.html) or [configuring a User Pool App Client](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html) -[Learn more about getting started with User Pools](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-with-cognito-user-pools.html) -or -[configuring a User Pool App Client](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html) +We can also use Amplify CLI to [import a Cognito user pool resource](/cli/auth/import/). ## Import an existing identity pool + +![import Amazon Cognito resource](/images/studio/import-identity-pool.png) + In order to successfully import your identity pool, it must have both of the user pool app clients must meet the following requirements: - An Authenticated Role with a trust relationship to your identity pool @@ -35,26 +47,41 @@ These roles are usually automatically configured when you create a new identity [Learn more about getting started with Identity Pools.](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-with-identity-pools.html) -## Import and update your source code +We can also use Amplify CLI to [import a Cognito identity pool resource](/cli/auth/import/). + + + +In order to import a Cognito identity pool resource a Cognito user pool resource is required. +Note: Amplify does not manage the lifecycle of an imported resource. + + + +## Update your source code + +Update your source code in your local application by running the following command: -Choose **Import** on the bottom of the page to complete the import procedure. Update your source code by running the following command: ```bash amplify pull ``` + Next, generate the necessary GraphQL files by running the following command: + ```bash amplify codegen add ``` After running this command, the following occurs: + - Your Amplify Library configuration files (aws-exports.js, amplifyconfiguration.json) are automatically populated with your chosen Amazon Cognito resource information - Your designated existing Amazon Cognito resource is provided as the authentication and authorization mechanism for all auth-dependent categories (API, Storage and more) - Lambda functions are enabled to access the chosen Amazon Cognito resource if you permit it. ## Multi-environment support + When you clone an environment or create a new one, you’ll be required to import your Amazon Cognito resources. If you want to have Amplify manage your authorization resources in a new environment, unlink the imported Cognito resource and add authorization to your new environment. This will create new Amplify-managed authorization resources in the new environment. - + ## Unlink an existing Amazon Cognito user pool or identity pool + In order to unlink your existing Amazon Cognito resource, click **Unlink Cognito User Pool and Identity Pool** on the bottom of the **Authentication** page and follow the prompt to confirm this action. This only unlinks the Amazon Cognito resource referenced from the Amplify project. It does not delete the Amazon Cognito resource itself.