rework "use existing cognito resources" prose, highlight configuring client libs directly

src/directory/directory.mjs

@@ -39,7 +39,7 @@ export const directory = {
               path: 'src/pages/[platform]/start/manual-installation/index.mdx'
             },
             {
-              path: 'src/pages/[platform]/start/connect-existing-aws-resources/index.mdx'
+              path: 'src/pages/[platform]/start/connect-to-aws-resources/index.mdx'
             },
             {
               path: 'src/pages/[platform]/start/kotlin-coroutines/index.mdx'

src/pages/[platform]/build-a-backend/auth/use-existing-cognito-resources/index.mdx

@@ -29,113 +29,20 @@ 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`](#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).
+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 can [configure the client library directly](#use-auth-resources-without-an-amplify-backend), or maintain references with [AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/cdk/) in your Amplify backend.
 
 <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>
-
-## 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: "<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.
+**Note:** when using existing auth resources, it may be necessary to add additional policies or permissions for your authenticated and unauthenticated IAM roles. These changes must be performed manually.
 
 </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,
-    },
-  },
-})
-```
-
 ## Use auth resources without an Amplify backend
 
-Alternatively, you can use existing resources without an Amplify backend.
-
 <InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
 
+You can use existing resources without an Amplify backend by configuring the client library directly.
+
 ```ts title="src/main.ts"
 import { Amplify } from "aws-amplify"
 
@@ -178,7 +85,6 @@ Configuring the mobile client libraries directly is not supported, however you c
 
 </Callout>
 
-{/* pending hosted outputs schema */}
 ```json title="amplify_outputs.json"
 {
   "version": "1",
@@ -204,6 +110,14 @@ Configuring the mobile client libraries directly is not supported, however you c
 
 </InlineFilter>
 
+## Use auth resources with an Amplify backend
+
+<Callout warning>
+
+**Warning:** Amplify resources do not support including auth configurations by referencing with CDK. We are currently working to improve this experience by providing first-class support for referencing existing auth resources. [View the RFC for `referenceAuth` for more details](https://github.com/aws-amplify/amplify-backend/issues/1548)
+
+</Callout>
+
 ## Next steps
 
 - [Learn how to connect your frontend](/[platform]/build-a-backend/auth/connect-your-frontend/)

src/pages/[platform]/start/connect-to-aws-resources/index.mdx

@@ -0,0 +1,139 @@
+import { getCustomStaticPath } from '@/utils/getCustomStaticPath';
+import { Card } from '@aws-amplify/ui-react';
+
+export const meta = {
+  title: 'Connect to AWS resources',
+  description: 'You can use Amplify client libraries to connect directly to your AWS resources',
+  platforms: [
+    'android',
+    'angular',
+    'flutter',
+    'javascript',
+    'nextjs',
+    'react',
+    'react-native',
+    'swift',
+    'vue'
+  ]
+};
+
+export async function getStaticPaths() {
+  return getCustomStaticPath(meta.platforms);
+}
+
+export function getStaticProps(context) {
+  return {
+    props: {
+      platform: context.params.platform,
+      meta
+    }
+  };
+}
+
+Amplify client libraries provide you with the flexibility to directly connect your application to AWS resources such as AWS AppSync, Amazon Cognito, Amazon S3, and more.
+
+To get started, client libraries must be _configured_. This is typically done by using the [`amplify_outputs.json` file](/[platform]/reference/amplify_outputs) generated by the Amplify backend tooling, however using the client libraries does not require backend resources to be created by Amplify.
+
+<InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
+
+For JavaScript-based applications, the client library can be configured by using the generated outputs file:
+
+```ts title="src/main.ts"
+import { Amplify } from "aws-amplify"
+import outputs from "../amplify_outputs.json"
+
+Amplify.configure(outputs)
+```
+
+Or by configuring the library directly by passing a [`ResourcesConfig`](https://aws-amplify.github.io/amplify-js/api/interfaces/aws_amplify.index.ResourcesConfig.html) object. For example, to configure the client library for use with Amazon Cognito, specify the `Auth` configuration:
+
+```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,
+      },
+    },
+  },
+})
+```
+
+By configuring the client library, Amplify automates the communication with the underlying AWS resources, and provides a friendly API to author your business logic. In the snippet below, the `signIn` function does not require passing information from your Cognito resource to initiate the sign-in flow.
+
+```ts title="src/main.ts"
+import { signIn } from "aws-amplify/auth"
+
+await signIn({
+  username: "john.doe@example.com",
+  password: "hunter2",
+})
+```
+
+</InlineFilter>
+<InlineFilter filters={["android", "flutter", "swift"]}>
+
+For mobile platforms, the client library can be configured by creating an `amplify_outputs.json` file in your project's directory. To get started, create the file and specify your resource configuration:
+
+```json title="amplify_outputs.json"
+{
+  "$schema": "https://raw.githubusercontent.com/aws-amplify/amplify-backend/main/packages/client-config/src/client-config-schema/schema_v1.json",
+  "version": "1",
+  "auth": {
+    "user_pool_id": "<your-cognito-user-pool-id>",
+    "aws_region": "<your-aws-region>",
+    "user_pool_client_id": "<your-cognito-user-pool-client-id>",
+    "identity_pool_id": "<your-cognito-identity-pool-id>",
+    "mfa_methods": [],
+    "standard_required_attributes": [
+      "email"
+    ],
+    "username_attributes": [
+      "email"
+    ],
+    "user_verification_types": [
+      "email"
+    ],
+    "mfa_configuration": "NONE",
+    "password_policy": {
+      "min_length": 8,
+      "require_lowercase": true,
+      "require_numbers": true,
+      "require_symbols": true,
+      "require_uppercase": true
+    },
+    "unauthenticated_identities_enabled": true
+  }
+}
+```
+
+</InlineFilter>
+
+For more information about how to use the Amplify client libraries with existing AWS resources, visit the guides:
+
+<Columns columns={2}>
+<Card variation="outlined">
+[Connect to Cognito](/[platform]/build-a-backend/auth/use-existing-cognito-resources/)
+
+Connect to Cognito resources using Amplify Auth's client library
+</Card>
+</Columns>