diff --git a/src/directory/directory.mjs b/src/directory/directory.mjs index d0b275b9e50..c2a2d6ddf26 100644 --- a/src/directory/directory.mjs +++ b/src/directory/directory.mjs @@ -162,6 +162,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..0f8ece57304 --- /dev/null +++ b/src/pages/[platform]/build-a-backend/auth/use-existing-resources/index.mdx @@ -0,0 +1,206 @@ +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(context) { + return { + props: { + platform: context.params.platform, + 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) + + +{/* merge content after hosting outputs schema */} + + +- [Add auth configuration as an output of the backend](#add-auth-as-a-backend-output) + + + + + +**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, + }, + }, + }, +}) +``` + + + + +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": "..." +} +``` + + + + +## Next steps + +- [Learn how to connect your frontend](/[platform]/build-a-backend/auth/connect-your-frontend/)