# IAM user groups
<a name="id_groups"></a>

An IAM [*user group*](#id_groups) is a collection of IAM users. User groups let you specify permissions for multiple users, which can make it easier to manage the permissions for those users. For example, you could have a user group called *Admins* and give that user group typical administrator permissions. Any user in that user group automatically has *Admins* group permissions. If a new user joins your organization and needs administrator privileges you can assign the appropriate permissions by adding the user to the *Admins* user group. If a person changes jobs in your organization, instead of editing that user's permissions you can remove them from the old IAM groups and add them to the appropriate new IAM groups. 

You can attach an identity-based policy to a user group so that all of the users in the user group receive the policy's permissions. You cannot identify a user group as a `Principal` in a policy (such as a resource-based policy) because groups relate to permissions, not authentication, and principals are authenticated IAM entities. For more information about policy types, see [Identity-based policies and resource-based policies](access_policies_identity-vs-resource.md).

Here are some important characteristics of IAM groups:
+ A user group can contain many users, and a user can belong to multiple user groups.
+ User groups can't be nested; they can contain only users, not other IAM groups.
+ There is no default user group that automatically includes all users in the AWS account. If you want to have a user group like that, you must create it and assign each new user to it.
+ The number and size of IAM resources in an AWS account, such as the number of groups, and the number of groups that a user can be a member of, are limited. For more information, see [IAM and AWS STS quotas](reference_iam-quotas.md).

The following diagram shows a simple example of a small company. The company owner creates an `Admins` user group for users to create and manage other users as the company grows. The `Admins` user group creates a `Developers` user group and a `Test` user group. Each of these IAM groups consists of users (humans and applications) that interact with AWS (Jim, Brad, DevApp1, and so on). Each user has an individual set of security credentials. In this example, each user belongs to a single user group. However, users can belong to multiple IAM groups.

![\[Example of relationship between AWS accounts, users, and IAM groups\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/Relationship_Between_Entities_Example.diagram.png)


# Create IAM groups
<a name="id_groups_create"></a>

**Note**  
As a [best practice](best-practices.md), we recommend that you require human users to use federation with an identity provider to access AWS using temporary credentials. If you follow the best practices, you are not managing IAM users and groups. Instead, your users and groups are managed outside of AWS and are able to access AWS resources as a *federated identity*. A federated identity is a user from your enterprise user directory, a web identity provider, the AWS Directory Service, the Identity Center directory, or any user that accesses AWS services by using credentials provided through an identity source. Federated identities use the groups defined by their identity provider. If you are using AWS IAM Identity Center, see [Manage identities in IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-sso.html) in the *AWS IAM Identity Center User Guide* for information about creating users and groups in IAM Identity Center.

You create IAM groups to manage access permissions for multiple users with similar roles or responsibilities. By attaching policies to these groups, you can grant or revoke permissions for entire sets of users. This simplifies your maintenance of security policies, as changes you make to a group's permissions are automatically applied to all members of that group, ensuring consistent access control. After you create the group, give the group permissions based on the type of work that you expect the IAM users in the group to do, then add the IAM users to the group.

For information about the permissions required to create an IAM group, see [Permissions required to access IAM resources](access_permissions-required.md). 

## To create an IAM group and attach policies
<a name="id_groups_create-section-1"></a>

------
#### [ Console ]

1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane, choose **User groups** and then choose **Create group**.

1. For **User group name**, type the name of the group.
**Note**  
The number and size of IAM resources in an AWS account are limited. For more information, see [IAM and AWS STS quotas](reference_iam-quotas.md). Group names can be a combination of up to 128 letters, digits, and these characters: plus (\$1), equal (=), comma (,), period (.), at sign (@), underscore (\$1), and hyphen (-). Names must be unique within an account. They aren't distinguished by case. For example, you cannot create groups named both **ADMINS** and **admins**.

1. In the list of users, select the check box for each user that you want to add to the group.

1. In the list of policies, select the check box for each policy that you want to apply to all members of the group.

1. Choose **Create group**.

------
#### [ AWS CLI ]

Run the following command:
+ [aws iam create-group](https://docs.aws.amazon.com/cli/latest/reference/iam/create-group.html)

------
#### [ API ]

Call the following operation:
+ [CreateGroup](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateGroup.html)

------

# View IAM groups
<a name="id_groups_manage_list"></a>

You can list all the IAM groups in your account, list the users in a user group, and list the IAM groups a user belongs to. If you use the CLI or API, you can list all the IAM groups with a particular path prefix.

------
#### [ Console ]

To list all IAM groups in your account:
+ In the navigation pane , choose **User groups**.

To list the IAM users in a specific IAM group:
+ In the navigation pane, choose **User groups**. Then choose the name of the group to open the group details page. Review the **Users** tab to see the group membership.

To list all the IAM groups that a user is in:
+ In the navigation pane, choose **Users**. Then choose the user name to open the user details page. Choose the **Groups** tab to see a list of the groups to which the user belongs.

------
#### [ AWS CLI ]

To list all IAM groups in your account:
+ [aws iam list-groups](https://docs.aws.amazon.com/cli/latest/reference/iam/list-groups.html)

To list the users in a specific IAM group:
+ [aws iam get-group](https://docs.aws.amazon.com/cli/latest/reference/iam/get-group.html)

To list all the IAM groups that a user is in:
+ [aws iam list-groups-for-user](https://docs.aws.amazon.com/cli/latest/reference/iam/list-groups-for-user.html)

------
#### [ API ]

To list all IAM groups in your account:
+ [ListGroups](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListGroups.html)

To list the users in a specific IAM group:
+ [GetGroup](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetGroup.html)

To list all the IAM groups that a user is in:
+ [ListGroupsForUser](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListGroupsForUser.html)

------

# Edit users in IAM groups
<a name="id_groups_manage_add-remove-users"></a>

Use IAM groups to apply the same permissions policies across multiple users at once. You can then add users to or remove users from an IAM group. This is useful as people enter and leave your organization.

## Review policy access
<a name="groups-remove_prerequisites"></a>

Before you remove a group, use the group details page to review the members (IAM users) of the group, the policies attached to the group on the **Permissions** tab and review recent service-level activity using the **Last Accessed** tab. This helps prevent unintentionally removing access from a principal (person or application) who is using it. For more information about viewing last accessed information, see [Refine permissions in AWS using last accessed information](access_policies_last-accessed.md).

## Add an IAM user to an IAM group
<a name="groups-add-remove-console"></a>

------
#### [ Console ]

1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane, choose **User groups** and then choose the name of the group.

1. Choose the **Users** tab and then choose **Add users**. Select the check box next to the users you want to add.

1. Choose **Add users**.

------
#### [ AWS CLI ]

Run the following command:
+ `[aws iam add-user-to-group](https://docs.aws.amazon.com/cli/latest/reference/iam/add-user-to-group.html)`

------
#### [ API ]

Call the following operation:
+ `[AddUserToGroup](https://docs.aws.amazon.com/IAM/latest/APIReference/API_AddUserToGroup.html)`

------

## Remove an IAM user from an IAM group
<a name="id_groups_manage_add-remove-users-section-1"></a>

------
#### [ Console ]

1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane, choose **User groups** and then choose the name of the group.

1. Choose the **Users** tab. Select the check box next to the users you want to remove and then choose **Remove users**.

------
#### [ AWS CLI ]

Run the following command:
+ `[aws iam remove-user-from-group](https://docs.aws.amazon.com/cli/latest/reference/iam/remove-user-from-group.html)`

------
#### [ API ]

Call the following operation:
+ `[RemoveUserFromGroup](https://docs.aws.amazon.com/IAM/latest/APIReference/API_RemoveUserFromGroup.html)`

------

# Attach a policy to an IAM user group
<a name="id_groups_manage_attach-policy"></a>

You can attach an [AWS managed policy](access_policies_managed-vs-inline.md#aws-managed-policies)—that is, a prewritten policy provided by AWS—to a user group, as explained in the following steps. To attach a customer managed policy—that is, a policy with custom permissions that you create—you must first create the policy. For information about creating customer managed policies, see [Define custom IAM permissions with customer managed policies](access_policies_create.md). 

For more information about permissions and policies, see [Access management for AWS resources](access.md). 

## To attach a policy to an IAM group
<a name="id_groups_manage_attach-policy-section-1"></a>

------
#### [ Console ]

1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane, choose **User groups** and then choose the name of the group.

1. Choose the **Permissions** tab.

1. Choose **Add permissions** and then choose **Attach policies**.

1. The current policies attached to the user group are displayed in the **Current permissions policies** list. In the list of **Other permissions policies**, select the check box next to the names of the policies to attach. You can use the search box to filter the list of policies by type and policy name.

1. Select the policy you want to attach to your IAM group and choose **Attach policies**.

------
#### [ AWS CLI ]

Run the following command:
+ `[aws iam attach-group-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-group-policy.html)`

------
#### [ API ]

Call the following operation:
+ `[AttachGroupPolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_AttachGroupPolicy.html)`

------

# Rename an IAM user group
<a name="id_groups_manage_rename"></a>

When you change a user group's name or path, the following happens: 
+ Any policies attached to the user group stay with the group under the new name.
+ The user group retains all its users under the new name.
+ The unique ID for the user group remains the same. For more information about unique IDs, see [Unique identifiers](reference_identifiers.md#identifiers-unique-ids). 

IAM does not automatically update policies that refer to the user group as a resource to use the new name. Therefore, you must be careful when you rename a user group. Before you rename your user group, you must manually check all of your policies to find any policies where that user group is mentioned by name. For example, let's say Bob is the manager of the testing part of the organization. Bob has a policy attached to his IAM user entity that lets him add and remove users from the Test user group. If an administrator changes the name of the user group (or changes the group path), the administrator must also update the policy attached to Bob to use the new name or path. Otherwise Bob won't be able to add and remove users from the user group. 

**To find policies that refer to an IAM group as a resource:**

1. From the navigation pane of the IAM console, choose **Policies**.

1. Sort by the **Type** column to find your **Customer managed** custom policies.

1. Choose the policy name of the policy to edit.

1. Choose the **Permissions** tab, and then choose **Summary**.

1. Choose **IAM** from the list of services, if it exists.

1. Look for the name of your user group in the **Resource** column.

1. Choose **Edit** to change the name of your user group in the policy.

## To change the name of an IAM user group
<a name="id_groups_manage_rename-section-1"></a>

------
#### [ Console ]

1. In the navigation pane, select **User groups** and then select the group name.

1. Choose **Edit**. Type the new user group name and then choose **Save changes**.

------
#### [ AWS CLI ]

Run the following command:
+ [aws iam update-group](https://docs.aws.amazon.com/cli/latest/reference/iam/update-group.html)

------
#### [ API ]

Call the following operation:
+ [UpdateGroup](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateGroup.html)

------

# Delete an IAM group
<a name="id_groups_manage_delete"></a>

When you delete an IAM group in the console, the console automatically removes all group members, detaches all attached managed policies, and deletes all inline policies. However, because IAM doesn't automatically delete policies that refer to the IAM group as a resource, you must be careful when you delete an IAM group. Before you delete your IAM group, manually review your policies to find any policies that mention the group by name. For example, John, the Test Team manager, has a policy attached to his IAM user entity that lets him add and remove users from the Test user group. If an administrator deletes the group, the administrator must also delete the policy attached to John. Otherwise, if the administrator recreates the deleted group and gives it the same name, John's permissions remain in place, even if he left the Test Team.

In contrast, when you use the CLI, SDK, or API to delete a user group, you remove the users in the group first. Then you delete any inline policies embedded in the IAM group. Next, you detach any managed policies that are attached to the group. Then you delete the IAM group itself.

------
#### [ Console ]

1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane, choose **User groups**.

1. In the list of IAM groups, select the check box next to the names of the IAM groups to delete. You can use the search box to filter the list of IAM groups by type, permissions, and group name.

1. Choose **Delete**.

1. In the confirmation box, if you want to delete a single group, type the group name and choose **Delete**. If you want to delete multiple groups, type the number of IAM group to delete followed by **user groups** and choose **Delete**. For example, if you want to delete three groups, type **3 **user groups****.

------
#### [ AWS CLI ]

1. Remove all users from the IAM group.
   + [aws iam get-group](https://docs.aws.amazon.com/cli/latest/reference/iam/get-group.html) (to get the list of users in the IAM group), and [aws iam remove-user-from-group](https://docs.aws.amazon.com/cli/latest/reference/iam/remove-user-from-group.html) (to remove a user from the IAM group)

1. Delete all inline policies embedded in the IAM group.
   + [aws iam list-group-policies](https://docs.aws.amazon.com/cli/latest/reference/iam/list-group-policies.html) (to get a list of the IAM group's inline policies), and [aws iam delete-group-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/delete-group-policy.html) (to delete the IAM group's inline policies)

1. Detach all managed policies attached to the IAM group.
   + [aws iam list-attached-group-policies](https://docs.aws.amazon.com/cli/latest/reference/iam/list-attached-group-policies.html) (to get a list of the managed policies attached to the IAM group), and [aws iam detach-group-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/detach-group-policy.html) (to detach a managed policy from the IAM group)

1. Delete the IAM group.
   + [aws iam delete-group](https://docs.aws.amazon.com/cli/latest/reference/iam/delete-group.html)

------
#### [ API ]

1. Remove all users from the IAM group.
   + [GetGroup](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetGroup.html) (to get the list of users in the IAM group) and [RemoveUserFromGroup](https://docs.aws.amazon.com/IAM/latest/APIReference/API_RemoveUserFromGroup.html) (to remove a user from the IAM group)

1. Delete all inline policies embedded in the IAM group.
   + [ListGroupPolicies](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListGroupPolicies.html) (to get a list of the IAM group's inline policies) and [DeleteGroupPolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteGroupPolicy.html) (to delete the IAM group's inline policies)

1. Detach all managed policies attached to the IAM group.
   + [ListAttachedGroupPolicies](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListAttachedGroupPolicies.html) (to get a list of the managed policies attached to the IAM group) and [DetachGroupPolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DetachGroupPolicy.html) (to detach a managed policy from the IAM group)

1. Delete the IAM group.
   + [DeleteGroup](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteGroup.html)

------