User groups

Amplify Auth provides a mechanism that allows you to group users. Assigning users to groups enable you to customize access for a collection of users, or leverage for auditing purposes. For example, only "ADMINS" users are permitted to delete posts from a bulletin, or only "EDITORS" are permitted to modify posts in a "draft" state. To get started with groups, configure the groups property:

import { defineAuth } from "@aws-amplify/backend"

export const auth = defineAuth({
  loginWith: {
    email: true,
  },
Copy highlighted code example
  groups: ["ADMINS", "EDITORS"],
})

Defining access

Amplify resources enable you to define access for groups using common language. For example, you can use allow.groups in data:

import { type ClientSchema, a, defineData } from "@aws-amplify/backend"

const schema = a.schema({
  Article: a.model({}).authorization(allow => [
    allow.groups(["EDITORS"]).to(["read", "update"])
  ])
})

// ...

Or in storage:

import { defineStorage } from "@aws-amplify/backend"

export const storage = defineStorage({
  name: "articles",
  access: (allow) => ({
    "drafts/*": [allow.groups(["EDITORS"]).to(["read", "write"])],
  }),
})

By defining access with groups, Amplify configures authorization rules to read from the current user's groups. User pool groups are available as a claim in the user's ID token and access token as cognito:groups. Requests can be made to secure resources using the access token and validated against this claim to permit action on the resource.

Group roles

Each Cognito user pool group is assigned an IAM role. IAM roles can be modified to extend access to other AWS resources. Roles can be accessed from your backend on the role property of your group:

import { defineBackend } from '@aws-amplify/backend';
import { auth } from './auth/resource';
import { data } from './data/resource';

/**
 * @see https://docs.amplify.aws/react/build-a-backend/ to add storage, functions, and more
 */
const backend = defineBackend({
  auth,
  data,
});

Copy highlighted code example
const { groups } = backend.auth.resources

// https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html
groups["ADMINS"].role

Next steps

• Learn how to automatically add a user to a group upon account confirmation
• Learn how to secure access to data models using groups
• Learn how to secure access to storage objects using groups