From d1e197399a334f818ff95154291cbef87478b7d5 Mon Sep 17 00:00:00 2001 From: josefaidt Date: Mon, 8 Jul 2024 09:02:15 -0700 Subject: [PATCH 1/3] rework "use existing cognito resources" prose, highlight configuring client libs directly --- .../use-existing-cognito-resources/index.mdx | 159 +++++++++--------- 1 file changed, 80 insertions(+), 79 deletions(-) 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..e721964c319 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,21 +29,96 @@ 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. +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. -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). + + +**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. + + + +## Use auth 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" + +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, + }, + }, + }, +}) +``` + + + -If you do not use Amplify to build your backend, you can [configure the client library directly](#use-auth-resources-without-an-amplify-backend). +Configuring the mobile client libraries directly is not supported, however you can manually create `amplify_outputs.json` with the following schema: -**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/) +**Note:** it is strongly recommended to use backend outputs to generate this file for each sandbox or branch deployment +```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 + } + } +} +``` + + + ## 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: + + +**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) + + + +To get started with your existing resource in your frontend application, 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" @@ -130,80 +205,6 @@ backend.addOutput({ }) ``` -## 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/) From fc9f4eb3197753249e34065a5d7a727dc2c65c41 Mon Sep 17 00:00:00 2001 From: josefaidt Date: Fri, 26 Jul 2024 14:40:18 -0700 Subject: [PATCH 2/3] pivot use existing aws resources page to generalized 'connect _to_' --- src/directory/directory.mjs | 2 +- .../connect-existing-aws-resources/index.mdx | 43 ------ .../start/connect-to-aws-resources/index.mdx | 139 ++++++++++++++++++ 3 files changed, 140 insertions(+), 44 deletions(-) delete mode 100644 src/pages/[platform]/start/connect-existing-aws-resources/index.mdx create mode 100644 src/pages/[platform]/start/connect-to-aws-resources/index.mdx 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]/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 + + From d2bc95f926582320d26e4c093ec84f511aea9b91 Mon Sep 17 00:00:00 2001 From: josefaidt Date: Fri, 26 Jul 2024 14:40:41 -0700 Subject: [PATCH 3/3] rm backend snippets in favor of referenceAuth rfc --- .../use-existing-cognito-resources/index.mdx | 87 ------------------- 1 file changed, 87 deletions(-) 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 e721964c319..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 @@ -118,93 +118,6 @@ Configuring the mobile client libraries directly is not supported, however you c -To get started with your existing resource in your frontend application, 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, - }, - }, -}) -``` - ## Next steps - [Learn how to connect your frontend](/[platform]/build-a-backend/auth/connect-your-frontend/)