Skip to content

Commit 4173f13

Browse files
josefaidtjosefaidt
authored
rework "use existing cognito resources" prose, highlight configuring client libs directly (#7806)
* rework "use existing cognito resources" prose, highlight configuring client libs directly * pivot use existing aws resources page to generalized 'connect _to_' * rm backend snippets in favor of referenceAuth rfc
1 parent 5bae7b0 commit 4173f13

File tree

4 files changed

+152
-142
lines changed

4 files changed

+152
-142
lines changed

‎src/directory/directory.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ export const directory = {
3939
path: 'src/pages/[platform]/start/manual-installation/index.mdx'
4040
},
4141
{
42-
path: 'src/pages/[platform]/start/connect-existing-aws-resources/index.mdx'
42+
path: 'src/pages/[platform]/start/connect-to-aws-resources/index.mdx'
4343
},
4444
{
4545
path: 'src/pages/[platform]/start/kotlin-coroutines/index.mdx'

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

Lines changed: 12 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -29,113 +29,20 @@ export function getStaticProps(context) {
2929
};
3030
}
3131

32-
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.
33-
34-
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).
35-
36-
If you do not use Amplify to build your backend, you can [configure the client library directly](#use-auth-resources-without-an-amplify-backend).
32+
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.
3733

3834
<Callout info>
3935

40-
**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/)
41-
42-
</Callout>
43-
44-
## Use auth resources with an Amplify backend
45-
46-
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:
47-
48-
```ts title="amplify/backend.ts"
49-
import { defineBackend } from "@aws-amplify/backend"
50-
51-
/**
52-
* @see https://docs.amplify.aws/react/build-a-backend/ to add storage, functions, and more
53-
*/
54-
const backend = defineBackend({})
55-
56-
backend.addOutput({
57-
auth: {
58-
aws_region: "<your-cognito-aws-region>",
59-
user_pool_id: "<your-cognito-user-pool-id>",
60-
user_pool_client_id: "<your-cognito-user-pool-client-id>",
61-
identity_pool_id: "<your-cognito-identity-pool-id>",
62-
username_attributes: ["email"],
63-
standard_required_attributes: ["email"],
64-
user_verification_types: ["email"],
65-
unauthenticated_identities_enabled: true,
66-
password_policy: {
67-
min_length: 8,
68-
require_lowercase: true,
69-
require_uppercase: true,
70-
require_numbers: true,
71-
require_symbols: true,
72-
}
73-
}
74-
})
75-
```
76-
77-
<Callout warning>
78-
79-
**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.
36+
**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.
8037

8138
</Callout>
8239

83-
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:
84-
85-
```ts title="amplify/backend.ts"
86-
import { defineBackend } from "@aws-amplify/backend"
87-
import { UserPool, UserPoolClient } from "aws-cdk-lib/aws-cognito"
88-
89-
/**
90-
* @see https://docs.amplify.aws/react/build-a-backend/ to add storage, functions, and more
91-
*/
92-
const backend = defineBackend({})
93-
94-
const authStack = backend.createStack("ExistingAuth")
95-
const userPool = UserPool.fromUserPoolId(
96-
authStack,
97-
"UserPool",
98-
"<your-cognito-user-pool-id>"
99-
)
100-
const userPoolClient = UserPoolClient.fromUserPoolClientId(
101-
authStack,
102-
"UserPoolClient",
103-
"<your-cognito-user-pool-client-id>"
104-
)
105-
// Cognito Identity Pools can be referenced directly
106-
const identityPoolId = "<your-cognito-identity-pool-id>"
107-
108-
backend.addOutput({
109-
auth: {
110-
aws_region: authStack.region,
111-
user_pool_id: userPool.userPoolId,
112-
user_pool_client_id: userPoolClient.userPoolClientId,
113-
identity_pool_id: identityPoolId,
114-
// this property configures the Authenticator's sign-up/sign-in views
115-
username_attributes: ["email"],
116-
// this property configures the Authenticator's sign-up/sign-in views
117-
standard_required_attributes: ["email"],
118-
// this property configures the Authenticator confirmation views
119-
user_verification_types: ["email"],
120-
unauthenticated_identities_enabled: true,
121-
// this property configures the validation for the Authenticator's password field
122-
password_policy: {
123-
min_length: 8,
124-
require_lowercase: true,
125-
require_uppercase: true,
126-
require_numbers: true,
127-
require_symbols: true,
128-
},
129-
},
130-
})
131-
```
132-
13340
## Use auth resources without an Amplify backend
13441

135-
Alternatively, you can use existing resources without an Amplify backend.
136-
13742
<InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
13843

44+
You can use existing resources without an Amplify backend by configuring the client library directly.
45+
13946
```ts title="src/main.ts"
14047
import { Amplify } from "aws-amplify"
14148

@@ -178,7 +85,6 @@ Configuring the mobile client libraries directly is not supported, however you c
17885

17986
</Callout>
18087

181-
{/* pending hosted outputs schema */}
18288
```json title="amplify_outputs.json"
18389
{
18490
"version": "1",
@@ -204,6 +110,14 @@ Configuring the mobile client libraries directly is not supported, however you c
204110

205111
</InlineFilter>
206112

113+
## Use auth resources with an Amplify backend
114+
115+
<Callout warning>
116+
117+
**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)
118+
119+
</Callout>
120+
207121
## Next steps
208122

209123
- [Learn how to connect your frontend](/[platform]/build-a-backend/auth/connect-your-frontend/)

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

Lines changed: 0 additions & 43 deletions
This file was deleted.

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

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
import { getCustomStaticPath } from '@/utils/getCustomStaticPath';
2+
import { Card } from '@aws-amplify/ui-react';
3+
4+
export const meta = {
5+
title: 'Connect to AWS resources',
6+
description: 'You can use Amplify client libraries to connect directly to your AWS resources',
7+
platforms: [
8+
'android',
9+
'angular',
10+
'flutter',
11+
'javascript',
12+
'nextjs',
13+
'react',
14+
'react-native',
15+
'swift',
16+
'vue'
17+
]
18+
};
19+
20+
export async function getStaticPaths() {
21+
return getCustomStaticPath(meta.platforms);
22+
}
23+
24+
export function getStaticProps(context) {
25+
return {
26+
props: {
27+
platform: context.params.platform,
28+
meta
29+
}
30+
};
31+
}
32+
33+
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.
34+
35+
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.
36+
37+
<InlineFilter filters={["angular", "javascript", "nextjs", "react", "react-native", "vue"]}>
38+
39+
For JavaScript-based applications, the client library can be configured by using the generated outputs file:
40+
41+
```ts title="src/main.ts"
42+
import { Amplify } from "aws-amplify"
43+
import outputs from "../amplify_outputs.json"
44+
45+
Amplify.configure(outputs)
46+
```
47+
48+
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:
49+
50+
```ts title="src/main.ts"
51+
import { Amplify } from "aws-amplify"
52+
53+
Amplify.configure({
54+
Auth: {
55+
Cognito: {
56+
userPoolId: "<your-cognito-user-pool-id>",
57+
userPoolClientId: "<your-cognito-user-pool-client-id>",
58+
identityPoolId: "<your-cognito-identity-pool-id>",
59+
loginWith: {
60+
email: true,
61+
},
62+
signUpVerificationMethod: "code",
63+
userAttributes: {
64+
email: {
65+
required: true,
66+
},
67+
},
68+
allowGuestAccess: true,
69+
passwordFormat: {
70+
minLength: 8,
71+
requireLowercase: true,
72+
requireUppercase: true,
73+
requireNumbers: true,
74+
requireSpecialCharacters: true,
75+
},
76+
},
77+
},
78+
})
79+
```
80+
81+
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.
82+
83+
```ts title="src/main.ts"
84+
import { signIn } from "aws-amplify/auth"
85+
86+
await signIn({
87+
username: "[email protected]",
88+
password: "hunter2",
89+
})
90+
```
91+
92+
</InlineFilter>
93+
<InlineFilter filters={["android", "flutter", "swift"]}>
94+
95+
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:
96+
97+
```json title="amplify_outputs.json"
98+
{
99+
"$schema": "https://raw.githubusercontent.com/aws-amplify/amplify-backend/main/packages/client-config/src/client-config-schema/schema_v1.json",
100+
"version": "1",
101+
"auth": {
102+
"user_pool_id": "<your-cognito-user-pool-id>",
103+
"aws_region": "<your-aws-region>",
104+
"user_pool_client_id": "<your-cognito-user-pool-client-id>",
105+
"identity_pool_id": "<your-cognito-identity-pool-id>",
106+
"mfa_methods": [],
107+
"standard_required_attributes": [
108+
"email"
109+
],
110+
"username_attributes": [
111+
"email"
112+
],
113+
"user_verification_types": [
114+
"email"
115+
],
116+
"mfa_configuration": "NONE",
117+
"password_policy": {
118+
"min_length": 8,
119+
"require_lowercase": true,
120+
"require_numbers": true,
121+
"require_symbols": true,
122+
"require_uppercase": true
123+
},
124+
"unauthenticated_identities_enabled": true
125+
}
126+
}
127+
```
128+
129+
</InlineFilter>
130+
131+
For more information about how to use the Amplify client libraries with existing AWS resources, visit the guides:
132+
133+
<Columns columns={2}>
134+
<Card variation="outlined">
135+
[Connect to Cognito](/[platform]/build-a-backend/auth/use-existing-cognito-resources/)
136+
137+
Connect to Cognito resources using Amplify Auth's client library
138+
</Card>
139+
</Columns>

0 commit comments

Comments
 (0)