diff --git a/src/directory/directory.mjs b/src/directory/directory.mjs index bb42f929cb0..066cdd00b50 100644 --- a/src/directory/directory.mjs +++ b/src/directory/directory.mjs @@ -171,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' } 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 new file mode 100644 index 00000000000..100830f1c6a --- /dev/null +++ b/src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx @@ -0,0 +1,209 @@ +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; + +export const meta = { + title: 'Use existing Cognito 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(context) { + return { + props: { + platform: context.params.platform, + meta + } + }; +} + +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`](#use-auth-resources-with-an-amplify-backend). + +If you do not use Amplify to build your backend, you can [configure the client library directly](#use-auth-resources-without-an-amplify-backend). + + + +**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/) + + + +## 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: + +```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, + }, + }, +}) +``` + +## Use auth resources without an Amplify backend + +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, + }, + }, + }, +}) +``` + + + + +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" +{ + "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 + } + } +} +``` + + + +## Next steps + +- [Learn how to connect your frontend](/[platform]/build-a-backend/auth/connect-your-frontend/)