add auth "use existing resources"

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'
                 },

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:
+
+<InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
+
+- [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)
+
+</InlineFilter>
+{/* merge content after hosting outputs schema */}
+<InlineFilter filters={["android", "flutter", "swift"]}>
+
+- [Add auth configuration as an output of the backend](#add-auth-as-a-backend-output)
+
+</InlineFilter>
+
+<Callout info>
+
+**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/)
+
+</Callout>
+
+## 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: "<your-cognito-aws-region>",
+    user_pool_id: "<your-cognito-user-pool-id>",
+    user_pool_client_id: "<your-cognito-user-pool-client-id>",
+    identity_pool_id: "<your-cognito-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,
+    }
+  }
+})
+```
+
+<Callout warning>
+
+**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.
+
+</Callout>
+
+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",
+  "<your-cognito-user-pool-id>"
+)
+const userPoolClient = UserPoolClient.fromUserPoolClientId(
+  authStack,
+  "UserPoolClient",
+  "<your-cognito-user-pool-client-id>"
+)
+// Cognito Identity Pools can be referenced directly
+const identityPoolId = "<your-cognito-identity-pool-id>"
+
+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 */}
+<InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
+
+## Configure the client library directly
+
+Alternatively, you can use existing resources without an Amplify backend.
+
+<InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
+
+```ts title="src/main.ts"
+import { Amplify } from "aws-amplify"
+
+Amplify.configure({
+  Auth: {
+    Cognito: {
+      userPoolId: "<your-cognito-user-pool-id>",
+      userPoolClientId: "<your-cognito-user-pool-client-id>",
+      identityPoolId: "<your-cognito-identity-pool-id>",
+      loginWith: {
+        email: true,
+      },
+      signUpVerificationMethod: "code",
+      userAttributes: {
+        email: {
+          required: true,
+        },
+      },
+      allowGuestAccess: true,
+      passwordFormat: {
+        minLength: 8,
+        requireLowercase: true,
+        requireUppercase: true,
+        requireNumbers: true,
+        requireSpecialCharacters: true,
+      },
+    },
+  },
+})
+```
+
+</InlineFilter>
+<InlineFilter filters={["android", "flutter", "swift"]}>
+
+Configuring the mobile client libraries directly is not supported, however you can manually create `amplify_outputs.json` with the following schema:
+
+<Callout info>
+
+**Note:** it is strongly recommended to use backend outputs to generate this file for each sandbox or branch deployment
+
+</Callout>
+
+{/* pending hosted outputs schema */}
+```json title="amplify_outputs.json"
+{
+  "$schema": "..."
+}
+```
+
+</InlineFilter>
+</InlineFilter>
+
+## Next steps
+
+- [Learn how to connect your frontend](/[platform]/build-a-backend/auth/connect-your-frontend/)