Creating and Managing User Groups

Access to cloud resources is granted to groups, not directly to users. A user account is not automatically a member of any group. To enable a user to do any work with cloud resources, you must add the user to a group and then create an access policy for that group. A group is therefore a set of users who have the same type of access to the same set of cloud resources. Organize users into groups according to which compartments and resources they need to access and how they need to work with those resources. A user can be a member of more than one group.

For conceptual information about user accounts and groups, see the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.

Creating a Group

When you create a group, the group is automatically created in the tenancy. You cannot specify a different compartment for the group.

Using the Compute Web UI

In the navigation menu, click Identity, and then click Groups.
Click the Create Group button.
In the Create Group dialog, enter the following information:
- Name: A name for this group. Group names have the following characteristics:
  - Must be unique within the tenancy. You can create a group with the same name as a group that has been deleted.
  - Are case insensitive.
  - Cannot be changed later.
  - Can be no more than 100 characters.
  - Can contain only alphanumeric characters, period (.), hyphen (-), and underscore (_).
- Description: A description for this group. The description has the following characteristics:
  - Must be 1-400 characters.
  - Does not need to be unique.
  - Can be changed later.
- Tagging: (Optional) Add defined or free-form tags for this group as described in Adding Tags at Resource Creation. Tags can also be applied later.
Click the Create Group button on the Create Group dialog.

The details page of the new group is displayed.

Next steps:
- Create an access policy for this group or add this group to an existing policy. A group has no permissions unless it is the subject of at least one policy. See Managing Policies.
- Add users to this group. See Adding a User to a Group by Updating the Group.

Using the OCI CLI

Get the following information:
- A name and description for the group. See the Compute Web UI procedure for limitations. In the OCI CLI, a description must be provided but its value can be an empty string.
- (Optional) The OCID of the tenancy for the group. By default, the root compartment OCID from the config file is used.
Run the group create command.

Syntax:
```
oci iam group create --name text --description "text"
```
See the Compute Web UI procedure for characteristics of the name and description values. See Adding Tags at Resource Creation to add defined and free-form tags.

Example:
```
$ oci iam group create --name Product-A --description "Resource management for Product A."
```
The output of this command is the same as the output of the group get command.

Next steps:
- Create an access policy for this group or add this group to an existing policy. A group has no permissions unless it is the subject of at least one policy. See Managing Policies.
- Add users to this group. See Adding a User to a Group by Updating the Group.

Viewing Group Information and Group Membership

Using the Compute Web UI

In the navigation menu, click Identity, and then click Groups.

The Groups page shows all groups in the tenancy because group definitions cannot be in different compartments. All groups are in the tenancy.
Click the name of the group about which you want more information.
On the details page for that group, scroll down to the Resources section.
Click the Group Members resource.

The list of users that belong to this group is shown.
To see the full list of groups where a user is a member, click the name of the user in the Group Members list.

Scroll down to the Resources section for that user and click Groups.

Using the OCI CLI

Get the OCID of the group for which you want the list of users (oci iam group list).
Run the list users command.

Syntax:
```
oci iam group list-users --group-id group_OCID
```
The output of the list-users command is the same as the output of the user get command for each user that is a member of this group.

The group get command does not show member users.

Adding a User to a Group by Updating the Group

Users must be members of groups in order to have access to resources.

Using the Compute Web UI

In the navigation menu, click Identity, and then click Groups.
Click the name of the group where you want to add users.
On the details page, scroll down to the Resources section and click Group Members.
At the top of the Group Members list, click the Add User to Group button.
In the Add User to Group dialog, select a user from the drop-down list, and then click the OK button.

The selected user is added to the Group Members list.

Using the OCI CLI

Get the following information:
- The OCID of the group where you want to add a user (oci iam group list).
- The OCID of the user that you want to add to this group (oci iam user list).

Run the group add user command.

Syntax:

oci iam group add-user --group-id group_OCID --user-id user_OCID

Example:

$ oci iam group add-user --group-id ocid1.group.unique_ID --user-id ocid1.user.unique_ID
{
  "data": {
    "compartment-id": "ocid1.tenancy.unique_ID",
    "group-id": "ocid1.group.unique_ID",
    "id": "ocid1.user_group_membership.unique_ID",
    "inactive-status": null,
    "lifecycle-state": "ACTIVE",
    "time-created": null,
    "user-id": "ocid1.user.unique_ID"
  }
}

Removing a User from a Group by Updating the Group

Using the Compute Web UI

In the navigation menu, click Identity, and then click Groups.
Click the name of the group where you want to remove a user.
On the details page, scroll down to the Resources section and click Group Members.
In the Group Members list, click the Actions menu for the user that you want to remove from the group, and click the Remove from Group option.
At the confirmation prompt, click OK.

The user is removed from the group.

Using the OCI CLI

Get the following information:
- The OCID of the group where you want to remove a user (oci iam group list).
- The OCID of the user that you want to remove from the group (oci iam user list).

Run the group remove user command.

Syntax:

oci iam group remove-user --group-id group_OCID --user-id user_OCID

Modifying a Group

You can change the description for a group. You can add, change, or remove tags as described in Applying Tags to an Existing Resource.

Using the Compute Web UI

In the navigation menu, click Identity, and then click Groups.
For the group that you want to modify, click the Actions menu, and click the Edit option.
In the Edit groupname dialog, modify the group's description or tags.
Click Save Changes.

Using the OCI CLI

Get the OCID of the group that you want to modify (oci iam group list).
Run the group update command.

Syntax:
```
oci iam group update --group-id group_OCID [ --description desc ] \
[ --defined-tags tags ] [ --freeform-tags tags ]
```
The output of this command is the same as the output of the group get command.

Deleting a Group

You cannot delete a group if the group has any members.

Using the Compute Web UI

In the navigation menu, click Identity, and then click Groups.
Click the name of the group that you want to delete.
Ensure that the group does not have any members.

On the group details page, scroll down to the Resources section and click Group Members. To remove a user from the group, click the Actions menu for the user in the Group Members list, and click the Remove from Group option.
At the top of the group details page, click the Delete button.
On the Delete Group confirmation dialog, click the Confirm button.

Using the OCI CLI

Get the OCID of the group that you want to delete (oci iam group list).
Use the group list-users command to ensure that the group has no members.

Run the group delete command.

Syntax:

oci iam group delete --group-id group_OCID

Example:

$ oci iam group delete --group-id ocid1.group.unique_ID
Are you sure you want to delete this resource? [y/N]: y

To delete a group without confirmation, use the --force option.