diff --git a/src/directory/directory.mjs b/src/directory/directory.mjs index a7478482b12..9f2aaaf099b 100644 --- a/src/directory/directory.mjs +++ b/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' 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 100830f1c6a..b31966b1d01 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,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. -**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. +**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. -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. - +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 -{/* 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 +## Use auth resources with an Amplify backend + + + +**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) + + + ## Next steps - [Learn how to connect your frontend](/[platform]/build-a-backend/auth/connect-your-frontend/) diff --git a/src/pages/[platform]/start/connect-existing-aws-resources/index.mdx b/src/pages/[platform]/start/connect-existing-aws-resources/index.mdx deleted file mode 100644 index a4ee29b1ba5..00000000000 --- a/src/pages/[platform]/start/connect-existing-aws-resources/index.mdx +++ /dev/null @@ -1,43 +0,0 @@ -import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; -import { Card } from '@aws-amplify/ui-react'; - -export const meta = { - title: 'Connect to existing AWS resources', - description: 'You can use Amplify client libraries to connect directly to your AWS resources without having to set up an Amplify backend.', - platforms: [ - 'android', - 'angular', - 'flutter', - 'javascript', - 'nextjs', - 'react', - 'react-native', - 'swift', - 'vue' - ] -}; - -export const getStaticPaths = async () => { - 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, regardless of whether you choose to set up an Amplify backend environment or manually configure individual AWS services, such as AWS AppSync, Amazon Cognito, Amazon S3, and more. - -If you configured AWS resources outside of an Amplify backend, you can still use the Amplify libraries to connect to them by following the instructions provided: - - - -[Connect to Cognito](/[platform]/build-a-backend/auth/use-existing-cognito-resources/) - -Connect to Cognito resources using Amplify Auth's client library - - diff --git a/src/pages/[platform]/start/connect-to-aws-resources/index.mdx b/src/pages/[platform]/start/connect-to-aws-resources/index.mdx new file mode 100644 index 00000000000..2123f94ef6b --- /dev/null +++ b/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. + + + +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: "", + userPoolClientId: "", + identityPoolId: "", + 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", +}) +``` + + + + +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": "", + "aws_region": "", + "user_pool_client_id": "", + "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 + } +} +``` + + + +For more information about how to use the Amplify client libraries with existing AWS resources, visit the guides: + + + +[Connect to Cognito](/[platform]/build-a-backend/auth/use-existing-cognito-resources/) + +Connect to Cognito resources using Amplify Auth's client library + +