Set up user group management

You can create logical groups in Cognito User Pools and assign permissions to access resources in Amplify categories with the CLI, as well as define the relative precedence of one group to another. This can be useful for defining which users should be part of "Admins" vs "Editors", and if the users in a Group should be able to just write or write & read to a resource (AppSync, API Gateway, S3 bucket, etc). You can also use these with @auth Static Groups in the GraphQL Transformer. Precedence helps remove any ambiguity on permissions if a user is in multiple Groups.

Create user groups

amplify add auth

❯ Manual configuration

Do you want to add User Pool Groups? (Use arrow keys)
❯ Yes

? Provide a name for your user pool group: Admins
? Do you want to add another User Pool Group Yes
? Provide a name for your user pool group: Editors
? Do you want to add another User Pool Group No
? Sort the user pool groups in order of preference …  (Use <shift>+<right/left> to change the order)
  Admins
  Editors

When asked as in the example above, you can press Shift on your keyboard along with the LEFT and RIGHT arrows to move a Group higher or lower in precedence. Once complete you can open amplify/backend/auth/userPoolGroups/user-pool-group-precedence.json to manually set the precedence.

Group access controls

For certain Amplify categories you can restrict access with CRUD (Create, Read, Update, and Delete) permissions, setting different access controls for authenticated users vs Guests (e.g. Authenticated users can read & write to S3 buckets while Guests can only read). You can further restrict this to apply different permissions conditionally depending on if a logged-in user is part of a specific User Pool Group.

amplify add storage  # Select content

? Restrict access by? (Use arrow keys)
  Auth/Guest Users
  Individual Groups
❯ Both
  Learn more

Who should have access?
❯ Auth and guest users

What kind of access do you want for Authenticated users?
❯ create/update, read

What kind of access do you want for Guest users?
❯ read

Select groups:
❯ Admins

What kind of access do you want for Admins users?
❯ create/update, read, delete

The above example uses a combination of permissions where users in the "Admins" Group have full access, "Guest" users can only read, and "Authenticated" users who are not a part of any group have create, update, and read access. Amplify will configure the corresponding IAM policy on your behalf. Advanced users can additionally set permissions by adding a customPolicies key to amplify/backend/auth/userPoolGroups/user-pool-group-precedence.json with custom IAM policy for a Group. This will attach an inline policy on the IAM role associated to this Group during deployment. Note this is an advanced feature and only suitable if you have an understanding of AWS resources. For instance perhaps you wanted users in the "Admins" group to have the ability to Create an S3 bucket:

[
  {
    "groupName": "Admins",
    "precedence": 1,
    "customPolicies": [
      {
        "PolicyName": "admin-group-policy",
        "PolicyDocument": {
          "Version": "2012-10-17",
          "Statement": [
            {
              "Sid": "statement1",
              "Effect": "Allow",
              "Action": ["s3:CreateBucket"],
              "Resource": ["arn:aws:s3:::*"]
            }
          ]
        }
      }
    ]
  },
  {
    "groupName": "Editors",
    "precedence": 2
  }
]