From 8e0e8efcbdeef083908249bc8ae4a60b6fc33110 Mon Sep 17 00:00:00 2001 From: josefaidt Date: Fri, 17 May 2024 11:19:13 -0700 Subject: [PATCH 1/9] add auth "use existing resources" --- src/directory/directory.mjs | 3 + .../auth/use-existing-resources/index.mdx | 194 ++++++++++++++++++ 2 files changed, 197 insertions(+) create mode 100644 src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx diff --git a/src/directory/directory.mjs b/src/directory/directory.mjs index ef3a5e7fbc5..5b288c2596b 100644 --- a/src/directory/directory.mjs +++ b/src/directory/directory.mjs @@ -159,6 +159,9 @@ export const directory = { { path: 'src/pages/[platform]/build-a-backend/auth/grant-access-to-auth-resources/index.mdx' }, + { + path: 'src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx' + }, { path: 'src/pages/[platform]/build-a-backend/auth/modify-resources-with-cdk/index.mdx' }, diff --git a/src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx b/src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx new file mode 100644 index 00000000000..ae8c978c355 --- /dev/null +++ b/src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx @@ -0,0 +1,194 @@ +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; + +export const meta = { + title: 'Use existing resources', + description: 'Learn how to use existing auth resources', + platforms: [ + 'android', + 'angular', + 'flutter', + 'javascript', + 'nextjs', + 'react', + 'react-native', + 'swift', + 'vue' + ] +}; + +export function getStaticPaths() { + return getCustomStaticPath(meta.platforms); +} + +export function getStaticProps() { + return { + props: { + meta + } + }; +} + +Amplify Auth can be configured to use a existing resources. If you are in a team setting or part of a company that has previously created auth resources, you have a few different options to configure your application to use existing auth resources: + +- [Add auth configuration as an output of the backend](#add-auth-as-a-backend-output) + +- [Configure the client library directly (without an Amplify backend)](#configure-the-client-library-directly) + + + + +**Note:** when using existing auth resources, it may be necessary to add policies or permissions for your authenticated and unauthenticated IAM roles. These changes must be performed manually using the [AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/cdk/) + + + +## Add auth as a backend output + +The easiest way to get started with your existing resource is to use `backend.addOutput` to surface auth configuration to `amplify_outputs.json` automatically. In it's simplest form: + +```ts title="amplify/backend.ts" +import { defineBackend } from "@aws-amplify/backend" + +/** + * @see https://docs.amplify.aws/react/build-a-backend/ to add storage, functions, and more + */ +const backend = defineBackend({}) + +backend.addOutput({ + auth: { + aws_region: "", + user_pool_id: "", + user_pool_client_id: "", + identity_pool_id: "", + username_attributes: ["email"], + standard_required_attributes: ["email"], + user_verification_types: ["email"], + unauthenticated_identities_enabled: true, + password_policy: { + min_length: 8, + require_lowercase: true, + require_uppercase: true, + require_numbers: true, + require_symbols: true, + } + } +}) +``` + + + +**Warning:** if you are creating an auth resource with `defineAuth`, you cannot override the default auth configuration automatically surfaced to `amplify_outputs.json` by Amplify. + + + +You can also use the CDK to dynamically reference existing resources, and use metadata from that resource to set up IAM policies for other resources, or reference as an authorizer for a custom REST API: + +```ts title="amplify/backend.ts" +import { defineBackend } from "@aws-amplify/backend" +import { UserPool, UserPoolClient } from "aws-cdk-lib/aws-cognito" + +/** + * @see https://docs.amplify.aws/react/build-a-backend/ to add storage, functions, and more + */ +const backend = defineBackend({}) + +const authStack = backend.createStack("ExistingAuth") +const userPool = UserPool.fromUserPoolId( + authStack, + "UserPool", + "" +) +const userPoolClient = UserPoolClient.fromUserPoolClientId( + authStack, + "UserPoolClient", + "" +) +// Cognito Identity Pools can be referenced directly +const identityPoolId = "" + +backend.addOutput({ + auth: { + aws_region: authStack.region, + user_pool_id: userPool.userPoolId, + user_pool_client_id: userPoolClient.userPoolClientId, + identity_pool_id: identityPoolId, + // this property configures the Authenticator's sign-up/sign-in views + username_attributes: ["email"], + // this property configures the Authenticator's sign-up/sign-in views + standard_required_attributes: ["email"], + // this property configures the Authenticator confirmation views + user_verification_types: ["email"], + unauthenticated_identities_enabled: true, + // this property configures the validation for the Authenticator's password field + password_policy: { + min_length: 8, + require_lowercase: true, + require_uppercase: true, + require_numbers: true, + require_symbols: true, + }, + }, +}) +``` + +{/* double-filter as a placeholder pending examples for other platforms */} +{/* when others are added, remove the outer filter to keep the same prose */} + + +## Configure the client library directly + +Alternatively, you can use existing resources without an Amplify backend. + + + +```ts title="src/main.ts" +import { Amplify } from "aws-amplify" + +Amplify.configure({ + Auth: { + Cognito: { + userPoolId: "", + userPoolClientId: "", + identityPoolId: "", + loginWith: { + email: true, + }, + signUpVerificationMethod: "code", + userAttributes: { + email: { + required: true, + }, + }, + allowGuestAccess: true, + passwordFormat: { + minLength: 8, + requireLowercase: true, + requireUppercase: true, + requireNumbers: true, + requireSpecialCharacters: true, + }, + }, + }, +}) +``` + + + + + + + + + + + + + + + + + + + +## Next steps + +- [Learn how to connect your frontend](/[platform]/build-a-backend/auth/connect-your-frontend/) From d264ea785b8c2e2e6cc7bd9eb3bbdc151c63110c Mon Sep 17 00:00:00 2001 From: josefaidt Date: Fri, 17 May 2024 11:42:59 -0700 Subject: [PATCH 2/9] update filters --- .../auth/use-existing-resources/index.mdx | 32 +++++++++++++------ 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx b/src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx index ae8c978c355..0f8ece57304 100644 --- a/src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx +++ b/src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx @@ -20,9 +20,10 @@ export function getStaticPaths() { return getCustomStaticPath(meta.platforms); } -export function getStaticProps() { +export function getStaticProps(context) { return { props: { + platform: context.params.platform, meta } }; @@ -30,9 +31,17 @@ export function getStaticProps() { Amplify Auth can be configured to use a existing resources. If you are in a team setting or part of a company that has previously created auth resources, you have a few different options to configure your application to use existing auth resources: -- [Add auth configuration as an output of the backend](#add-auth-as-a-backend-output) + +- [Add auth configuration as an output of the backend](#add-auth-as-a-backend-output) - [Configure the client library directly (without an Amplify backend)](#configure-the-client-library-directly) + + +{/* merge content after hosting outputs schema */} + + +- [Add auth configuration as an output of the backend](#add-auth-as-a-backend-output) + @@ -172,19 +181,22 @@ Amplify.configure({ ``` - - - - - - + +Configuring the mobile client libraries directly is not supported, however you can manually create `amplify_outputs.json` with the following schema: + - - +**Note:** it is strongly recommended to use backend outputs to generate this file for each sandbox or branch deployment + +{/* pending hosted outputs schema */} +```json title="amplify_outputs.json" +{ + "$schema": "..." +} +``` From b35320f9177030554708d5d3b01654374e553242 Mon Sep 17 00:00:00 2001 From: josefaidt Date: Mon, 20 May 2024 09:16:09 -0700 Subject: [PATCH 3/9] rerun pr check From ecedc3585b35607f1b10773ab8e58c6ac9ae00f4 Mon Sep 17 00:00:00 2001 From: josefaidt Date: Tue, 21 May 2024 14:52:53 -0700 Subject: [PATCH 4/9] use-existing-resources -> use-existing-cognito-resources --- src/directory/directory.mjs | 2 +- .../index.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename src/pages/[platform]/build-a-backend/auth/{use-existing-resources => use-existing-cognito-resources}/index.mdx (99%) diff --git a/src/directory/directory.mjs b/src/directory/directory.mjs index c2a2d6ddf26..80d813f4aae 100644 --- a/src/directory/directory.mjs +++ b/src/directory/directory.mjs @@ -163,7 +163,7 @@ export const directory = { path: 'src/pages/[platform]/build-a-backend/auth/grant-access-to-auth-resources/index.mdx' }, { - path: 'src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx' + path: 'src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx' }, { path: 'src/pages/[platform]/build-a-backend/auth/modify-resources-with-cdk/index.mdx' diff --git a/src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx b/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx similarity index 99% rename from src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx rename to src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx index 0f8ece57304..561999adb65 100644 --- a/src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx +++ b/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx @@ -1,7 +1,7 @@ import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; export const meta = { - title: 'Use existing resources', + title: 'Use existing Cognito resources', description: 'Learn how to use existing auth resources', platforms: [ 'android', From cbf06e9f38bf4e1f5fd7187e67aed510ab86116c Mon Sep 17 00:00:00 2001 From: josefaidt Date: Wed, 22 May 2024 21:16:09 -0700 Subject: [PATCH 5/9] add comment for double filter --- .../auth/use-existing-cognito-resources/index.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx b/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx index 561999adb65..ab8cbc31668 100644 --- a/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx +++ b/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx @@ -199,6 +199,7 @@ Configuring the mobile client libraries directly is not supported, however you c ``` +{/* end double filter -- remove after hosting schema */} ## Next steps From dffacce2c7b3ca28f828916928b1ab6f79cfcbe6 Mon Sep 17 00:00:00 2001 From: josefaidt Date: Wed, 22 May 2024 21:16:25 -0700 Subject: [PATCH 6/9] move page to bottom of auth nav --- src/directory/directory.mjs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/directory/directory.mjs b/src/directory/directory.mjs index c2ef3f17bac..066cdd00b50 100644 --- a/src/directory/directory.mjs +++ b/src/directory/directory.mjs @@ -162,9 +162,6 @@ export const directory = { { path: 'src/pages/[platform]/build-a-backend/auth/grant-access-to-auth-resources/index.mdx' }, - { - path: 'src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx' - }, { path: 'src/pages/[platform]/build-a-backend/auth/modify-resources-with-cdk/index.mdx' }, @@ -174,6 +171,9 @@ export const directory = { { path: 'src/pages/[platform]/build-a-backend/auth/advanced-workflows/index.mdx' }, + { + path: 'src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx' + }, { path: 'src/pages/[platform]/build-a-backend/auth/use-aws-sdk/index.mdx' } From 6f8fbe5ef4702f258ea3e985ef09f20407f3e12e Mon Sep 17 00:00:00 2001 From: josefaidt Date: Fri, 31 May 2024 11:53:29 -0700 Subject: [PATCH 7/9] add apparent recommendation, manual setup --- .../use-existing-cognito-resources/index.mdx | 40 ++++++++++--------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx b/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx index ab8cbc31668..c3bfca5b7d5 100644 --- a/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx +++ b/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx @@ -29,20 +29,11 @@ export function getStaticProps(context) { }; } -Amplify Auth can be configured to use a existing resources. If you are in a team setting or part of a company that has previously created auth resources, you have a few different options to configure your application to use existing auth resources: +Amplify Auth can be configured to use a existing resources. If you are in a team setting or part of a company that has previously created auth resources, you have a few different options to configure your application to use existing auth resources. - - -- [Add auth configuration as an output of the backend](#add-auth-as-a-backend-output) -- [Configure the client library directly (without an Amplify backend)](#configure-the-client-library-directly) - - -{/* merge content after hosting outputs schema */} - - -- [Add auth configuration as an output of the backend](#add-auth-as-a-backend-output) +If you are using Amplify to build your backend, it is recommended to [add a reference to your auth resource using `backend.addOutput`](#add-auth-as-a-backend-output). - +If you do not use Amplify to build your backend, you can [configure the client library directly](#configure-the-client-library-directly). @@ -139,10 +130,6 @@ backend.addOutput({ }) ``` -{/* double-filter as a placeholder pending examples for other platforms */} -{/* when others are added, remove the outer filter to keep the same prose */} - - ## Configure the client library directly Alternatively, you can use existing resources without an Amplify backend. @@ -194,12 +181,27 @@ Configuring the mobile client libraries directly is not supported, however you c {/* pending hosted outputs schema */} ```json title="amplify_outputs.json" { - "$schema": "..." + "version": "1", + "auth": { + "aws_region": "", + "user_pool_id": "", + "user_pool_client_id": "", + "identity_pool_id": "", + "username_attributes": ["email"], + "standard_required_attributes": ["email"], + "user_verification_types": ["email"], + "unauthenticated_identities_enabled": true, + "password_policy": { + "min_length": 8, + "require_lowercase": true, + "require_uppercase": true, + "require_numbers": true, + "require_symbols": true + } + } } ``` - -{/* end double filter -- remove after hosting schema */} ## Next steps From d0469b83cc1ff0cb60ef37ae1640d834d8b22ea7 Mon Sep 17 00:00:00 2001 From: josef Date: Fri, 31 May 2024 16:49:54 -0700 Subject: [PATCH 8/9] Update src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx Co-authored-by: Rene Brandel <4989523+renebrandel@users.noreply.github.com> --- .../auth/use-existing-cognito-resources/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx b/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx index c3bfca5b7d5..035fb0c875a 100644 --- a/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx +++ b/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx @@ -29,7 +29,7 @@ export function getStaticProps(context) { }; } -Amplify Auth can be configured to use a existing resources. If you are in a team setting or part of a company that has previously created auth resources, you have a few different options to configure your application to use existing auth resources. +Amplify Auth can be configured to use an existing Amazon Cognito user pool and identity pool. If you are in a team setting or part of a company that has previously created auth resources, you have a few different options to configure your application to use existing auth resources. If you are using Amplify to build your backend, it is recommended to [add a reference to your auth resource using `backend.addOutput`](#add-auth-as-a-backend-output). From f20791e32801468d4fb548b2788256ac52011167 Mon Sep 17 00:00:00 2001 From: josefaidt Date: Mon, 3 Jun 2024 11:09:17 -0700 Subject: [PATCH 9/9] update headings --- .../auth/use-existing-cognito-resources/index.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx b/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx index 035fb0c875a..100830f1c6a 100644 --- a/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx +++ b/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx @@ -31,9 +31,9 @@ export function getStaticProps(context) { Amplify Auth can be configured to use an existing Amazon Cognito user pool and identity pool. If you are in a team setting or part of a company that has previously created auth resources, you have a few different options to configure your application to use existing auth resources. -If you are using Amplify to build your backend, it is recommended to [add a reference to your auth resource using `backend.addOutput`](#add-auth-as-a-backend-output). +If you are using Amplify to build your backend, it is recommended to [add a reference to your auth resource using `backend.addOutput`](#use-auth-resources-with-an-amplify-backend). -If you do not use Amplify to build your backend, you can [configure the client library directly](#configure-the-client-library-directly). +If you do not use Amplify to build your backend, you can [configure the client library directly](#use-auth-resources-without-an-amplify-backend). @@ -41,7 +41,7 @@ If you do not use Amplify to build your backend, you can [configure the client l -## Add auth as a backend output +## Use auth resources with an Amplify backend The easiest way to get started with your existing resource is to use `backend.addOutput` to surface auth configuration to `amplify_outputs.json` automatically. In it's simplest form: @@ -130,7 +130,7 @@ backend.addOutput({ }) ``` -## Configure the client library directly +## Use auth resources without an Amplify backend Alternatively, you can use existing resources without an Amplify backend.