use existing auth resources

Author: josefaidt

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

@@ -112,12 +112,60 @@ Configuring the mobile client libraries directly is not supported, however you c
 
 ## Use auth resources with an Amplify backend
 
-<Callout warning>
+If you have created Amazon Cognito resources outside of the context of your Amplify app such as creating resources through the AWS Console or consuming resources created by a separate team, you can use `referenceAuth` to reference the existing resources.
+
+```ts title="amplify/auth/resource.ts"
+import { referenceAuth } from '@aws-amplify/backend';
+
+export const auth = referenceAuth({
+  userPoolId: 'us-east-1_xxxx',
+  identityPoolId: 'us-east-1:b57b7c3b-9c95-43e4-9266-xxxx',
+  authRoleArn: 'arn:aws:iam::xxxx:role/amplify-xxxx-mai-amplifyAuthauthenticatedU-xxxx',
+  unauthRoleArn: 'arn:aws:iam::xxxx:role/amplify-xxxx-mai-amplifyAuthunauthenticate-xxxx',
+  userPoolClientId: 'xxxx',
+});
+```
+
+<Callout info>
 
-**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)
+Referenced resources cannot be modified. IAM policies specific to your Amplify application will be appended to your authenticated and unauthenticated roles.
 
 </Callout>
 
+You can also use the [`access` property](/[platform]/build-a-backend/auth/grant-access-to-auth-resources/) to grant permissions to your auth resource from other Amplify backend resources. For example, if you have a function that needs to retrieve details about a user:
+
+```ts title="amplify/auth/resource.ts"
+import { referenceAuth } from '@aws-amplify/backend';
+import { getUser } from "../functions/get-user/resource";
+
+export const auth = referenceAuth({
+  userPoolId: 'us-east-1_xxxx',
+  identityPoolId: 'us-east-1:b57b7c3b-9c95-43e4-9266-xxxx',
+  authRoleArn: 'arn:aws:iam::xxxx:role/amplify-xxxx-mai-amplifyAuthauthenticatedU-xxxx',
+  unauthRoleArn: 'arn:aws:iam::xxxx:role/amplify-xxxx-mai-amplifyAuthunauthenticate-xxxx',
+  userPoolClientId: 'xxxx',
+  access: (allow) => [
+    allow.resource(getUser).to(["getUser"]),
+  ],
+});
+```
+
+In a team setting you may want to reference a different set of auth resources depending on the deployment context. For instance if you have a `staging` branch that should reuse resources from a separate "staging" environment compared to a `production` branch that should reuse resources from the separate "production" environment. In this case we recommend using environment variables.
+
+```ts title="amplify/auth/resource.ts"
+import { referenceAuth } from '@aws-amplify/backend';
+
+export const auth = referenceAuth({
+  userPoolId: process.env.MY_USER_POOL_ID,
+  identityPoolId: process.env.MY_IDENTITY_POOL_ID,
+  authRoleArn: process.env.MY_AUTH_ROLE_ARN,
+  unauthRoleArn: process.env.MY_UNAUTH_ROLE_ARN,
+  userPoolClientId: process.env.MY_USER_POOL_CLIENT_ID,
+});
+```
+
+Environment variables must be configured separately on your machine for sandbox deployments and Amplify console for branch deployments.
+
 ## Next steps
 
 - [Learn how to connect your frontend](/[platform]/build-a-backend/auth/connect-your-frontend/)