---
title: "User groups"
section: "build-a-backend/auth/concepts"
platforms: ["angular", "javascript", "nextjs", "react", "vue"]
gen: 2
last-updated: "2024-05-03T17:21:51.000Z"
url: "https://docs.amplify.aws/react/build-a-backend/auth/concepts/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:

```ts title="amplify/auth/resource.ts"
import { defineAuth } from "@aws-amplify/backend"

export const auth = defineAuth({
  loginWith: {
    email: true,
  },
  // highlight-start
  groups: ["ADMINS", "EDITORS"],
  // highlight-end
})
```

<Callout>

**Note:** There are a few [limitations with groups](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-user-groups.html#user-pool-user-groups-limitations), including a limit of 10,000 groups per user pool.

</Callout>

## Defining access

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

```ts title="amplify/data/resource.ts"
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:

```ts title="amplify/storage/articles/resource.ts"
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](https://aws.amazon.com/iam/features/manage-roles/). 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:

```ts title="amplify/backend.ts"
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,
});

// highlight-start
const { groups } = backend.auth.resources

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

## Next steps

- [Learn how to automatically add a user to a group upon account confirmation](/[platform]/build-a-backend/functions/examples/add-user-to-group/)
- [Learn how to secure access to data models using groups](/[platform]/build-a-backend/data/customize-authz/user-group-based-data-access)
- [Learn how to secure access to storage objects using groups](/[platform]/build-a-backend/storage/set-up-storage/)