Identity and Access Management

2 Identity and Access Management

Oracle Private Cloud Appliance Identity and Access Management (IAM) enables you to control which users have what access to which cloud resources in your tenancy.

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

Creating and Managing User Accounts

By default, the tenancy has an administrative user in an administrators group, and a policy enables the administrators group to manage the tenancy. To limit a user to managing only a subset of resources in the tenancy or another compartment, or to have less than full management access to some resources, create a user account, add the user account to one or more groups, and create one or more policies for those groups.

A user account is not automatically a member of any group. A user that is not a member of any group is visible in the tenancy but does not have access to any resources.

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 User

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

Using the Compute Web UI

In the navigation menu, click Identity, and then click Users.
Click the Create User button.
In the Create User dialog, enter the following information:
- Name: A name for this user account. User names have the following characteristics:
  - Must be unique within the tenancy. You can create a user with the same name as a user that has been deleted.
  - Are case insensitive.
  - Cannot be changed later.
  - Must be at least two and no more than 100 characters.
  - Can contain only alphanumeric characters, period (.), hyphen (-), underscore (_), plus sign (+), and at sign (@).
- Description: A description for this user, such as the full name of the person or a brief description of the account. The description has the following characteristics:
  - Must be 1-400 characters.
  - Does not need to be unique.
  - Can be changed later.
- Email Address: (Optional) The email address for the user. Can be updated later.
- Password: (Optional) To enable this user to log in to the Compute Web UI, check the box labeled "Generate a temporary password for this user."
  
  You can provide a password later. See Providing a Temporary Compute Web UI Password.
  
  Note:
  
  Passwords for federated users are not managed through this service. See information from your federated identity provider.
- Tagging: (Optional) Add defined or free-form tags for this user account as described in Adding Tags at Resource Creation. Tags can also be applied later.
Click the Create User button on the Create User dialog.

If you checked the box labeled "Generate a temporary password for this user," a Temporary Password for New User dialog pops up, showing the temporary password. You cannot retrieve this password again after you close this dialog. Copy the temporary password, save the password to a safe place for delivery to the user, and click the "I have made a note of the password" button.

The details page of the new user is displayed.

Next steps:
- Provide the user with a temporary password so that the user can set their own permanent Compute Web UI password.
  - If you checked the box labeled "Generate a temporary password for this user," provide the temporary password that you copied from the Temporary Password for New User dialog.
  - If you did not check the box labeled "Generate a temporary password for this user," or did not save that password, follow the instructions in Providing a Temporary Compute Web UI Password to generate a temporary password for the user.
- Add this user to at least one group. See Adding a User to a Group by Updating the User.
- If the user wants to use the OCI CLI, see Installing the OCI CLI.

Using the OCI CLI

Get the following information:
- A name and description for the user. See the Compute Web UI procedure for parameters. 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 user. By default, the root compartment OCID from the config file is used.
Run the user create command.

Syntax:
```
oci iam user 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 user create --name flast --description "First Last" --email first.last@example.com
```
The output of this command is the same as the output of the user get command.

Next steps:
- Provide the user with a temporary password so that the user can set their own permanent Compute Web UI password. See Providing a Temporary Compute Web UI Password.
- Add this user to at least one group. See Adding a User to a Group by Updating the User.
- If the user wants to use the OCI CLI, see Installing the OCI CLI.

Providing a Temporary Compute Web UI Password

Perform this procedure for new users and for users who forget their password. This procedure generates a temporary one-time password. When the user signs in using this password, the user is required to change the password before proceeding. The generated temporary password expires after seven (7) days.

A tenancy administrator can provide a temporary password for any user. Users must set their own permanent passwords by following the instructions in Setting Your Own Compute Web UI Password.

Note:

Passwords for federated users are not managed through the IAM service. See information from your federated identity provider.

Using the Compute Web UI

In the navigation menu, click Identity, and then click Users.
For the user that needs a new password, click the Actions menu, and click the Change Password option.
In the Change Password dialog, click the Create Temporary Password button.

A Password Changed dialog pops up. The New Password field contains the temporary password.
Copy and save this temporary password.

You cannot retrieve this password again after you close this dialog. Copy the temporary password, and save the password to a safe place for delivery to the user.
Click the Close button on the dialog.
Deliver this temporary one-time password to the user. The user must follow the rules stated in Setting Your Own Compute Web UI Password when setting their new password.

Using the OCI CLI

Get the OCID of the user that needs a password (oci iam user list).

Run the user Compute Web UI password create or reset command.

Example:

$ oci iam user ui-password create-or-reset --user-id ocid1.user.unique_ID
{
  "data": {
    "inactive-status": null,
    "lifecycle-state": "ACTIVE",
    "password": "N59%fP9uTq6\\",
    "time-created": "2021-10-13T22:10:49.290000+00:00",
    "user-id": "ocid1.user.unique_ID"
  }
}

Copy the password value from the command output and deliver this temporary one-time password to the user. The user must follow the rules stated in Setting Your Own Compute Web UI Password when setting their new password.

Setting Your Own Compute Web UI Password

Users do not require an access policy to set or change their own Compute Web UI password.

Setting Your Password

Use this procedure to set your Compute Web UI password initially, or to reset your password if you forgot your password.

Using the Compute Web UI

Get the temporary password that was generated for you.
On the login screen for the Compute Web UI, enter your user name.
Enter the temporary password.

A dialog pops up that says your password has expired and you need to create a new password.
Click the Change my password button.
On the Change My Password screen, enter the temporary password in the Current Password field.
Enter a new password in the New Password field and again in the Confirm New Password field.

Passwords must be at least 12 characters in length and contain at least one of each of the following: uppercase character, lowercase character, number, and symbol.
Click the Save Changes button.

A dialog pops up that says your password has been successfully updated.
Click the Continue button.
Log in using your new password.

Changing Your Password

Use this procedure to change your Compute Web UI password while your current password still works.

Using the Compute Web UI

In the top right corner of the Compute Web UI, click your user menu.
Click Change My Password.
On the Change My Password screen, enter your current password in the Current Password field.
Enter a new password in the New Password field and again in the Confirm New Password field.

Passwords must be at least 12 characters in length and contain at least one of each of the following: uppercase character, lowercase character, number, and symbol.
Click the Save Changes button.

A dialog pops up that says your password has been successfully updated.
Click the Continue button.

Viewing User Information and Group Membership

Using the Compute Web UI

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

The Users page shows all users of the tenancy because user accounts cannot be in different compartments. All users are in the tenancy.
Click the name of the user for which you want more information.
On the details page for that user account, scroll down to the Resources section.
Click the Groups resource.

The list of groups where this user is a member is shown.
To see the full list of members of a group, click the name of the group in the Groups list.

Scroll down to the Resources section for that group and click Group Members.

Using the OCI CLI

Get the OCID of the user account for which you want the list of groups (oci iam user list).
Run the list groups command.

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

The user get command does not show group membership.

Adding a User to a Group by Updating the User

A user must be a member of at least one group in order to have access to any resources.

Using the Compute Web UI

As an alternative to using the Users Compute Web UI page, you can use the Groups page as described in Adding a User to a Group by Updating the Group.

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

The selected group is added to the user's Groups list.

Using the OCI CLI

For the OCI CLI procedure, see Adding a User to a Group by Updating the Group.
Use the user list-groups command to show the groups where this user is a member. The output of the user list-groups command is the same as the output of the group get command for each group where this user is a member.

Removing a User from a Group by Updating the User

If you remove a user from all groups, the user will not have access to any resources.

Using the Compute Web UI

As an alternative to using the Users Compute Web UI page, you can use the Groups page as described in Removing a User from a Group by Updating the Group.

In the navigation menu, click Identity, and then click Users.
Click the name of the user that you want to remove from a group.
Scroll to the Resources section and click Groups.
For the group from which you want to remove the user, click the Actions menu, and click the Remove from Group option.

The selected group is removed from the user's Groups list.

Using the OCI CLI

For the OCI CLI procedure, see Removing a User from a Group by Updating the Group.
Use the user list-groups command to show the groups where this user is a member. The output of the user list-groups command is the same as the output of the group get command for each group where this user is a member.

Modifying a User

You can change a user account's description and email address. 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 Users.
For the user account that you want to modify, click the Actions menu, and click the Edit option.
In the Edit username dialog, modify the account's description, email address, or tags.
Click Save Changes.

Using the OCI CLI

Get the OCID of the user account that you want to modify (oci iam user list).

Run the user update command.

Syntax:

oci iam user update --user-id user_OCID [ --description desc ] \
[ --email email ] [ --defined-tags tags ] [ --freeform-tags tags ]

The output of this command is the same as the output of the user get command.

Deleting a User

You cannot delete a user if the user is a member of any group. You cannot delete your own user.

When you delete a user, all API keys associated with that user account are also deleted.

Using the Compute Web UI

In the navigation menu, click Identity, and then click Users.
Click the name of the user that you want to delete.
Ensure that the user is not a member of any group.

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

Using the OCI CLI

Get the OCID of the user account that you want to delete (oci iam user list).
Use the user list-groups command to ensure that the user is not a member of any group.

Run the user delete command.

Syntax:

oci iam user delete --user-id user_OCID

Example:

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

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

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.

Creating and Managing Compartments

Compartments contain resources such as cloud instances, virtual cloud networks, and block volumes. Your tenancy is the root compartment where you can create cloud resources and other compartments. You can create hierarchies of compartments that are up to six levels deep. You can limit access to compartment resources to specified user groups. Most resources can be moved between compartments later if your business needs change.

The compartments that you create in your tenancy are your primary building blocks for organizing and controlling access to your cloud resources. Before you create compartments and resources, see "Organizing Resources in Compartments" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.

Understanding the Tenancy

A tenancy is a special compartment. The tenancy is the root compartment where you create and administer all of your cloud resources, including other compartments.

Users, groups, and identity providers are always attached directly to the tenancy, not to any compartment of the tenancy. You cannot specify a different compartment when you create a user, group, or identity provider. When you use the OCI CLI to operate on a user, group, or identity provider, the OCID of the tenancy from the config file is used by default.

Other resources can reside in the tenancy or in any other compartment. Operating on these resources often requires you to select the correct compartment in the Compute Web UI or specify the compartment OCID in the OCI CLI.

Use the following procedures to get the OCID of the tenancy.

Using the Compute Web UI

Click your user profile menu in the top right of the page.
Click the Tenancy option.
On the tenancy details page, use the Show or Copy button under OCID.

Using the OCI CLI

Use the compartment list command.
```
$ oci iam compartment list
```
Look for the ocid1.tenancy.unique_ID OCID.
- With no options, the compartment list command lists all compartments that are direct child compartments of the tenancy. The tenancy is the value of the first property listed (compartment-id) for every compartment in the list.
- If you specify the --include-root option, the tenancy is listed first, and the tenancy OCID is the value of the id property (the value of the compartment-id property is null).
As is true for other resources, in a compartment list or get, the compartment-id compartment is the parent compartment of the id compartment.

Listing Compartments

Using the Compute Web UI

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

The list shows all compartments that are direct child compartments of the tenancy.
To view a compartment that is a subcompartment of a listed compartment, click the name of the listed compartment. On the details page for that compartment, scroll to the Resources section, and click Child Compartments.

You might need to click the name of a compartment in the Child Compartments list, and repeat this step.

To find the compartment where a particular resource is located, navigate to a list of those resources. Above the resource list, use the Compartment drop-down menu to select the compartment.

Using the OCI CLI

Use the --help option to learn about the --access-level option and about options that are common to list commands such as --lifecycle-state and --sort-by.

To list all compartments and subcompartments in the tenancy, specify the --compartment-id-in-subtree option with a value of true.
```
$ oci iam compartment list --compartment-id-in-subtree true
```
Specifying the --compartment-id option, described in the next step, does not change this output: You cannot list just the compartment tree of a particular compartment other than the tenancy.
To list all compartments that are direct child compartments of another compartment, specify the OCID of that parent compartment:
```
$ oci iam compartment list --compartment-id ocid1.compartment.unique_ID
```
This output does not list the specified parent compartment and does not list compartments that are deeper in the hierarchy of this parent compartment. This output only lists the direct child compartments of the specified parent compartment.

If you do not specify a parent compartment, all compartments that are direct child compartments of the tenancy are listed. To list the tenancy in addition to the direct child compartments of the tenancy, specify the --include-root option.
To list just one particular compartment, you can specify the compartment name.
```
$ oci iam compartment list --name Acompartment
```
The output is the same as a get of that compartment.
```
$ oci iam compartment get --compartment-id OCID_of_Acompartment
```

Creating a Compartment

You can create a compartment in your tenancy or in another compartment. You can create hierarchies of compartments that are up to six levels deep.

Using the Compute Web UI

In the navigation menu, click Identity and then click Compartments.
Click the Create Compartment button above the list of compartments.
In the Create Compartment dialog box, enter the following information:
- Name: A name for this compartment. Compartment names have the following characteristics:
  - Must be unique within the tenancy.
  - Are case insensitive.
  - Can be changed later.
  - Can be no more than 100 characters.
  - Can contain only alphanumeric characters, period (.), hyphen (-), and underscore (_).
- Description: A description for this compartment. This description can be no more than 400 characters and can be changed later.
- Create in Compartment: The compartment in which you want to create the new compartment. The new compartment will be a sub-compartment of the selected compartment.
- Tagging: (Optional) Add defined or free-form tags for this compartment as described in Adding Tags at Resource Creation. Tags can also be applied later.
Click the Create Compartment button on the dialog box.

Click the name of the new compartment to view the compartment details, including tags.

Using the OCI CLI

Get the OCID of the compartment in which you want to create the new compartment. The new compartment will be a sub-compartment of the specified compartment.
```
$ oci iam compartment list --compartment-id-in-subtree true
```

Run the compartment create command.

Syntax:

oci iam compartment create --compartment-id compartment_OCID \
--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 compartment create -c ocid1.compartment.parent_compartment_unique_ID \
--name ProductX --description "A child compartment of compartment Products"
{
  "data": {
    "compartment-id": "ocid1.compartment.parent_compartment_unique_ID",
    "defined-tags": {},
    "description": "A child compartment of compartment Products",
    "freeform-tags": {},
    "id": "ocid1.compartment.new_compartment_unique_ID",
    "inactive-status": null,
    "is-accessible": null,
    "lifecycle-state": "ACTIVE",
    "name": "ProductX",
    "time-created": "2021-10-05T22:58:23.216657+00:00"
  },
  "etag": "b212700d-45fa-46a9-90da-bcc016c587bc"
}

To view this output later, use the compartment get command.

Applying Tag Defaults

Compartments can have resources called tag defaults. Tag defaults are defined tags that are inherited by all resources and child compartments that are created after the tag default is added to the parent compartment. To add a tag default to a compartment, see Configuring Tag Defaults.

Adding Policies for Access Control

Child compartments inherit access permissions from their parent compartments. If you want the access to a new compartment to be different from the access to the parent compartment, create an access policy for the new compartment. For example, grant group DevX permission to read all resources in compartment Products and permission to manage all resources in subcompartment ProductX. Grant group DevY permission to read all resources in compartment Products and permission to manage all resources in subcompartment ProductY. Because of inheritance, group DevX will be able to read all resources in compartment ProductY, and group DevY will be able to read all resources in compartment ProductX.

For information about creating and attaching policies, see Managing Policies.

Adding Resources to a Compartment

Use either of the following methods to add resources to a compartment:

Specify the compartment when you create the resource.
Move the resource from a different compartment.

See the documentation for the particular resource for information such as whether attached resources move with the moved resource.

Check whether the moved resources have the correct tags and policies applied. You might need to manually delete and add tags and policies.

The Resources box on a compartment details page in the Compute Web UI, and the compartment list and get commands in the OCI CLI, do not show all of the resources that belong to a compartment. For resources that are not listed, go to the Compute Web UI page for that resource, such as instances, and select the compartment from the Compartment drop-down menu above the resource list. In the OCI CLI, specify the compartment OCID when you list the resources. See also Using the Compute Web UI and Using the OCI CLI.

Updating a Compartment

You can change the name and description of a compartment. You can add, change, or remove tags as described in Applying Tags to an Existing Resource. You cannot change the parent compartment. To change the parent compartment, see Moving a Compartment to a Different Compartment.

Using the Compute Web UI

In the navigation menu, click Identity and then click Compartments.
If the compartment that you want to update is not listed, navigate to the compartment that you want to update, as described in Listing Compartments.
For the compartment that you want to update, click the Actions menu, and click the Edit option.
In the Editing compartment_name Compartment dialog, make the changes.
Click the Save Changes button.

Click the compartment name to view the compartment details, including tags.

Using the OCI CLI

Get the OCID of the compartment that you want to update.

$ oci iam compartment list --compartment-id-in-subtree true

Run the compartment update command.

Syntax:
```
oci iam oci iam compartment update --compartment-id compartment_OCID \
options_with_values_to_update
```
Example:

If you specify the --defined-tags or --freeform-tags options, then you must fully specify all defined and free-form tags that you want on this compartment, including tags that already exist on the compartment that you want to keep. Values that you provide for these tag options replace any existing values. See Working with Resource Tags. You will be prompted to confirm unless you specify the --force option.
```
$ oci iam compartment update --compartment-id ocid1.compartment.unique_ID \
--defined-tags '{"Product":{"LMN":"Development"}}' --freeform-tags '{"MyTag":"val-u"}'
WARNING: Updates to freeform-tags and defined-tags will replace any existing values.
Are you sure you want to continue? [y/N]: y
```
The output of this command is the same as the output of the compartment get command.

Moving a Compartment to a Different Compartment

You can move a compartment to a different parent compartment in the same tenancy. When you move a compartment, all subcompartments of the compartment are moved. Some resources of the moved compartment are moved. You can separately move other resources as needed. See the documentation for the particular resource type for more information.

After you move a compartment to a new parent compartment, the access policies of the new parent take effect and the policies of the previous parent no longer apply. Groups who had access to the compartment and its resources in the previous parent compartment lose their access when the compartment is moved. Groups who have access in the new parent compartment gain access to the moved compartment and its resources.

Tag defaults that are automatically applied to all resources created in the new parent are not automatically applied to the newly moved compartment and its resources. You might need to separately delete and add tag defaults to the moved compartment and delete and add tags to moved resources.

See also "Moving a Compartment to a Different Parent Compartment" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.

You must belong to a group that has manage all-resources permissions on the lowest shared parent compartment of the current compartment and the destination compartment.

To move a compartment, you must use the OCI CLI.

Using the OCI CLI

Get the OCID of the compartment that you want to move, and the OCID of the destination compartment.
```
$ oci iam compartment list --compartment-id-in-subtree true
```
Run the compartment move command.

Syntax:
```
oci iam compartment move --compartment-id compartment_to_move_OCID \
--target-compartment-id destination_compartment_OCID
```
Use the iam work-request get command to check the status of the compartment move, or view the work request details in the Compute Web UI. Some resources might take longer to move than the compartment.

Deleting a Compartment

To delete a compartment, you must first move, delete, or terminate all of the resources in the compartment, including any policies that are attached to the compartment. Before you begin, check the move and delete capabilities for all resources in the compartment.

Using the Compute Web UI

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

The compartments in the tenancy are listed.
If the compartment that you want to delete is not listed, navigate to the compartment that you want to update, as described in Listing Compartments.
For the compartment that you want to delete, click the Actions menu, and click the Delete Compartment option.

If the Delete Compartment option is not selectable, then you might not have permission to delete this compartment.
In the Delete Compartment confirmation dialog, click Delete.

The compartment status changes to Deleting.

In the Resources box on the compartment details page, click Work Requests and view the details of the compartment delete. When the work request is completed, the compartment is removed from the compartments list. If the work request fails, the compartment status returns to Active.

Using the OCI CLI

Get the OCID of the compartment that you want to delete.

$ oci iam compartment list --compartment-id-in-subtree true

Run the compartment delete command.

Syntax:
```
oci iam compartment delete --compartment-id compartment_OCID
```
Use the iam work-request get command to check the status of the compartment delete.

Managing Policies

A policy is a named set of one or more policy statements. Policy statements grant permissions to users to access resources.

When designing access policies, remember the following policy characteristics:

The policy will apply to the compartment where you attach the policy and to all subcompartments of that compartment. Permissions granted in a particular compartment, including the tenancy, are inherited by all subcompartments of that compartment.
A user can be a member of more than one group. A group can be the subject of more than one policy. A policy can have up to 50 policy statements.
If some users need full access to the named resources and other users only need to use the resources, you need to create multiple groups and multiple policies. A tenancy can have up to 100 policies.
Users who have full access to resources in a subcompartment probably also need view or use access to related resources in that compartment and in parent compartments. For example, users who have access to create instances in a compartment might also need access to use tag namespaces to apply defined tags to the instances, or access to read images in a different compartment.

For conceptual information, see "How Policies Work" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.

Writing Policy Statements

A policy can have up to 50 policy statements. A tenancy can have up to 100 policies. Decide what you want your policy to permit, and use the information in this section to write the necessary statements.

Ensure that the groups and compartments that you plan to name in the policy statements exist. Note the name or OCID of each group and compartment that you want to use.

Note:

If you use names in your policy statements instead of OCIDs, the policy will still be valid if the name of the group or compartment is subsequently changed. Internally, the OCID, not the name, is used. However, the policy could be more difficult for administrators to understand if the name of the group or compartment changes.

If you plan to use a tag to apply the policy to more than one group or more than one compartment, ensure that the tag exists. Note the name of the tag namespace, the name of the key, and the value that you want to use in the policy statement.

For conceptual and reference information and examples of common statements, see "How Policies Work" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.

Policy Statement Syntax

Policy statements grant permissions to users to access resources. The users are also called the subject of the policy, and the permissions are also called the verb. The resource type and compartment define the set of possible resources to which the users are granted access. This set of resources is also called the target. Conditions can be used to narrow the set of users, the set of resources, and the operations that can be performed on the resources.

The following is the policy statement syntax:

allow users to permissions [resource_type] in compartment [ where conditions ]

Keywords allow, to, and in are required and are case insensitive.

users

One or more user groups or any-user. To specify more than one group, use a comma between each two group names or OCIDs in a list. You cannot specify both group names and group OCIDs. You can specify the keyword any-user to grant permission to all users.

group group_name[,group_name …]
group id group_ocid[,group_ocid …]
any-user

permissions

One of inspect, read, use, or manage. For descriptions of the access that these permission aggregators grant, see "Verb" in "Policy Syntax" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.
One or more specific permissions, such as INSTANCE_UPDATE, in the following form:
```
{ PERMISSION_1[, PERMISSION_2]... }
```
If you use this option, do not specify a resource_type. The resource type is included in the permission.

To grant both a permission aggregator and one or more specific permissions for the same resource, use two policy statements.

resource_type

A single keyword that represents one of the following:

A single resource type, such as instances or volumes.
A family of resource types. For example, the instance-family resource type family includes the following resource types:
- app-catalog-listing
- console-histories
- instances
- instance-console-connection
- instance-images
all-resources

If you list specific permissions instead of one of the four permissions aggregator keywords, do not specify a resource_type. The resource type is included in the permission.

For a list of resource types, see the table in "Resource Types" in "Policy Syntax" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.

compartment

A single compartment name or OCID or tenancy.

compartment compartment_name
compartment id compartment_OCID
tenancy

To grant access in multiple compartments, use multiple statements.

condition

A predefined variable followed by an operator and a value. See Using Conditions.

Using Conditions

Conditions can be specified in a policy statement to narrow the set of users who are granted access, the set of resources to which the users are granted access, and the operations that can be performed on the resources. A condition is a predefined variable with a value that you specify. You can specify a list of conditions with AND and OR relationships. The entire condition clause must evaluate to true in order for access to be granted. For information about conditions that might unexpectedly evaluate to false, see Conditions That Are Not Applicable.

The following is the syntax of the condition clause:

where condition
where all|any {condition[, condition]...}

The syntax of condition is:

variable op 'value'

variable

See Table 2-1.

op

= (equal) or != (not equal) – Applies to all variables.
in or not in – See Using Defined Tags in Conditions.

value

The value can be a fully specified string or can use the * wildcard. If the value is a fully specified string, enclose the value in single quotation marks. If you use *, enclose the value in forward slashes (/):

'BU1-ProdX'
/*Prod*/
/*ProdX/
/BU1-Prod*/

Condition values are case insensitive. For example, a condition with a value of BucketA also applies to bucket bucketA in the same compartment if such a bucket exists.

In the following table, variables that begin with request refer to the request that is being made: A user has clicked a Compute Web UI option or entered a OCI CLI command. Variables that begin with target refer to the resource that the user clicked or named in the command.

Table 2-1 Supported Predefined Variables for Conditions

Variable	Description
`request.groups.id`	The list of groups that the requesting user belongs to.
`request.operation`	The name of the operation that is being attempted.
`request.permission`	The names of the permissions that are required to perform the operation.
`target.compartment.id`	The OCID of the compartment that contains the target resource. The compartment that contains the target resource could be a child compartment of the compartment specified in the `in` clause in the policy statement.
`target.compartment.name`	The name of the compartment that contains the target resource. The compartment that contains the target resource could be a child compartment of the compartment specified in the `in` clause in the policy statement.
`target.user.id`	The OCID of the target user. This OCID is not available when the requested permission is to create the user.
`target.user.name`	The name of the target user.
`target.group.id`	The OCID of the target group. This OCID is not available when the requested permission is to create the group.
`target.group.name`	The name of the target group.
`target.group.member`	True if the requesting user belongs to the target group.
`target.policy.id`	The OCID of the target policy. This OCID is not available when the requested permission is to create the policy.
`target.policy.name`	The name of the target policy.
`target.tag-namespace.id`	The OCID of the tag namespace that the user is requesting to list, update, or delete.
`target.tag-namespace.name`	The name of the tag namespace that the user is requesting to create or update. Use commas to separate multiple names.
`request.principal.group.tag`	See Using Defined Tags in Conditions.
`target.resource.tag`	See Using Defined Tags in Conditions.
`target.resource.compartment.tag`	See Using Defined Tags in Conditions.

Example: Specify Permissions Using request.permission

To grant users the ability to create objects but not the ability to delete objects, you can grant manage access and then specify a condition that says only create and inspect access are granted:

allow group ObjectWriters to manage objects in compartment ABC 
where any {request.permission='OBJECT_CREATE', request.permission='OBJECT_INSPECT'}

Example: Specify Compartments Using target.compartment.name and Wildcards

The following example grants users the ability to manage all resources in virtual-network-family in any compartment that has a name that begins with X except for compartment XYZ:

allow group NetworkAdmins to manage virtual-network-family in tenancy 
where all {target.compartment.name=/X*/,target.compartment.name!='XYZ'}

Example: Nested Conditions

The following policy enables users in group BucketAdmins to either read, update, or manage retention rules for BucketA in compartment ABC:

allow group BucketAdmins to manage buckets in compartment ABC 
where all {target.bucket.name='BucketA', 
any {request.permission='BUCKET_UPDATE', request.permission='BUCKET_READ',
RETENTION_RULE_MANAGE}}

Because the policy is for a specific named bucket, this policy does not permit users to retrieve a list of buckets. To permit users to retrieve a list of buckets, add the following separate statement:

allow group BucketAdmins to inspect buckets in compartment ABC

See Conditions That Are Not Applicable.

Example: Apply Defined Tags

The following example enables users in groups BucketAdmins and ObjectWriters to apply tags in the StorageTags tag namespace:

allow group BucketAdmins,ObjectWriters to use tag-namespaces in tenancy 
where target.tag-namespace.name='StorageTags'

Example: Edit Any Group Where You Are a Member

The following example enables all users to edit any group where they are members:

allow any-user to use groups in tenancy where target.group.member='true'

Conditions That Are Not Applicable

If a condition is not applicable to the rest of the policy statement, then that condition evaluates to false and access is not granted.

A condition is not applicable if it is testing information that is not available in the request. For example, the following policy statement grants use access to the resource users, but does not allow the requesting users to list or update users, even though those permissions are included in the use permission:

allow group GroupAdmins to use users in tenancy where target.group.name != 'Administrators'

The request to list users or update a user does not include information about groups. The list users and update user requests have no value for target.group.name. The test fails, and the request to list or update a user is denied.

To fix this example, you could remove the where clause and allow only inspect or read access.

Using Defined Tags in Conditions

Certain conditions evaluate the value of a defined tag that has been applied to a user, compartment, or resource. In these conditions, the predefined variable can be called a tag variable.

Using conditions with tag variables enables you to do the following:

Write a single policy statement that applies to multiple user groups, compartments, or resources.
Change the permissions that are granted without changing the policy statement. Instead, to allow or revoke access, apply tags to different resources or remove tags from resources.

See Resource Tag Management for information about how to create and apply defined tags.

The general syntax of a condition that uses tag variables is the same as the syntax of a condition that uses other condition variables:

variable op 'value'

The value of each of these three parts is specialized for tags.

variable

Tag condition variables include the name of the tag namespace and the name of the key in the variable name:

base_variable_name.tag_namespace_name.tag_key_name

op

One of =, !=, in, or not in.

The in and not in operations refer to members of the set of possible values for the tag.

value

The value is a value of the defined tag. The value can be a single value or a list of values.

The following tag variables are supported:

request.principal.group.tag

This variable potentially grants access to multiple groups in one statement. The following statement allows any user that is a member of a group that has been tagged with tag Operations>Project>ABC to manage instance resources in compartment ProdX:

allow any-user to manage instance-family in compartment ProdX 
where request.principal.group.tag.Operations.Project='ABC'

If you replace 'ABC' in the preceding statement with '*' or /*/, a user that is a member of a group that has been tagged with any value of Operations>Project could manage instance resources in compartment ProdX.

target.resource.compartment.tag

This variable potentially grants access to multiple compartments in one statement. The following statement allows users in group NetAdmins to use network resources in any compartment that has been tagged with either tag Operations>Project>ABC or tag Operations>Personnel>Test:

allow group NetAdmins to use virtual-network-family in tenancy where
any { target.resource.compartment.tag.Operations.Project='ABC', 
target.resource.compartment.tag.Operations.Personnel='Test' }

If you replace any with all in the preceding statement, the statement allows users in group NetAdmins to use network resources in any compartment that has been tagged with both tag Operations>Project>ABC and tag Operations>Personnel>Test.

The following statement allows users in group NetAdmins to use network resources in any compartment that has been tagged with either tag Operations>Personnel>Development or tag Operations>Personnel>Test:

allow group NetAdmins to use virtual-network-family in tenancy where
target.resource.compartment.tag.Operations.Personnel in ('Development', 'Test')

target.resource.tag

This variable grants access to one or more resources of the specified type. The following statement allows group Xadmins to use any instance in compartment ProdX that is tagged with tag Operations>Project>XYZ.

allow group Xadmins to use instances in compartment ProdX 
where target.resource.tag.Operations.Project = 'XYZ'

Writing Policies to Access Resources Across Tenancies

Before You Begin

You can write policies to allow tenancy access from other tenancies so you can share resources across tenancies. The administrators of both tenancies need to create special policy statements that explicitly state which resources can be accessed and shared. These special statements use the following special verbs:

Endorse: This policy statement describes what work a group in a source tenancy can perform in other tenancies. You write the endorse statement for the tenancy that contains the group of users who need to work with another tenancy's resources.
Admit: This policy statement describes what work a group from other tenancies can perform in a destination tenancy. You write the admit statement for the tenancy that is granting permission to access its resources. The admit statement identifies the group of users from the source tenancy that requires resource access in the destination tenancy.
Define: This policy statement is used to assign an alias for a source tenancy OCID, a source group OCID, and a destination tenancy OCID. You define a source tenancy alias and a source group alias for use in admit policy statements. You define a destination tenancy alias for use in endorse policy statements.

You must include a define statement in the same policy entity as the endorse or admit statement.

The endorse and admit statements work together. An endorse statement resides in the source tenancy while an admit statement resides in the destination tenancy. Without a corresponding statement that specifies access, a particular endorse or admit statement grants no access. Both tenancies must agree on access and have policies that allow for access.

In the source tenancy, you write define and endorse policy statements using the following syntax:

define tenancy destination-tenancy-alias as tenancy_ocid

endorse group group-name to verb resource in tenancy destination-tenancy-alias

In the destination tenancy, you write two define policy statemens and an admit policy statement using the following syntax:

define tenancy source-tenancy-alias as tenancy_ocid

define group source-group-alias as group_ocid

admit group source-group-alias of tenancy source-tenancy-alias to verb resource in compartment/tenancy

Source Tenancy Policy Statements

An administrator for the source tenancy creates policy statements that endorses a group in their tenancy to manage resources in a destination tenancy.

You can write broad policy statements for the source tenancy as in the following examples.

To endorse a specific group, such as StorageAdmins, to do anything with all object storage resources in any tenancy:
```
endorse group StorageAdmins to manage object-family in any-tenancy 
```
To endorse a specific group, such as DNSAdmins, to do anything with all DNS resources in any tenancy:
```
endorse group DNSAdmins to manage dns in any-tenancy 
```

You can write a policies that reduce the scope of access for a source tenancy group. For this type of policy, the administrator for the source tenancy must define an alias for the destination tenancy OCID and reference that alias in the policy's statements, for example:

To endorse a specific group, such as StorageAdmins, to manage object storage resources in a specific tenanacy, such as DestinationTenancy, you would use the following policy statements:
```
define tenancy DestinationTenancy as ocid1.tenancy.oc1..<unique_ID>
endorse group StorageAdmins to manage object-family in tenancy DestinationTenancy
```
To endorse a specific group, such as DNSAdmins, to manage DNS resources in a specific tenanacy, such as DestinationTenancy, you would use the following policy statements:
```
define tenancy DestinationTenancy as ocid1.tenancy.oc1..<unique_ID>
endorse group DNSAdmins to manage dns in tenancy DestinationTenancy
```

The destination tenancy must also have a policy that allows the source tenancy group access to the destination tenancy and its resources. Without this corresponding policy in the destination tenancy, the source tenancy group would not be able to access the destination tenancy or its resources.

For more information on writing policy statements, see "How Policies Work" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.

Destination Tenancy Policy Statements

An administrator for the destination tenancy creates policy statements that allows a group in a source tenancy access to the destination tenanacy and its resources.

You can write broad policy statements for the destination tenancy as in the following examples.

To allow a specific group in a source tenancy, such as StorageAdmins, to do anything with all object storage resources in the destination tenancy:

define tenancy SourceTenancy as ocid1.tenancy.oc1..<unique_ID>
define group StorageAdmins as ocid1.group.oc1..<unique_ID>
admit group StorageAdmins of tenancy SourceTenancy to manage object-family in tenancy

To allow a specific group in a source tenancy, such as DNSAdmins, to do anything with all DNS resources in the destination tenancy:

define tenancy SourceTenancy as ocid1.tenancy.oc1..<unique_ID>
define group DNSAdmins as ocid1.group.oc1..<unique_ID>
admit group DNSAdmins of tenancy SourceTenancy to manage dns in tenancy

You can write policies that reduces the scope of access for a source tenancy group to destination tenancy resources. For these types of policies, an administrator for the destination tenancy must define aliases for the source tenancy OCID and source group OCID, and then reference those aliases in the policy's statements, for example:

To allow a specific group in the source tenancy, such as StorageAdmins, to manage object storage resources in a specific compartment, such as SharedBuckets, you would use the following policy statements:

define tenancy SourceTenancy as ocid1.tenancy.oc1..<unique_ID>
define group StorageAdmins as ocid1.group.oc1..<unique_ID>
admit group StorageAdmins of tenancy SourceTenancy to manage object-family in compartment SharedBuckets

To allow a specific group in the source tenancy, such as DNSAdmins, to manage DNS resources in a specific compartment, such as SharedZomes, you would use the following policy statements:
```
define tenancy SourceTenancy as ocid1.tenancy.oc1..<unique_ID>
define group DNSAdmins as ocid1.group.oc1..<unique_ID>
admit group DNSAdmins of tenancy SourceTenancy to manage dns in compartment SharedZones 
```

The source tenancy must also have a policy that endorses the source tenancy group's access to the destination tenancy and its resources. Without this corresponding policy in the source tenancy, the source tenancy group would not be able to access the destination tenancy or its resources.

For more information on writing policy statements, see "How Policies Work" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.

Creating a Policy

Before You Begin

A policy must have at least one policy statement. You cannot create an empty policy and add statements later. Decide what you want your policy to allow, and see Writing Policy Statements to design the necessary statements.

Using the Compute Web UI

In the navigation menu, click Identity, and then click Policies.
Click Create Policy.
In the Create Policy dialog, enter the following information:
- Name: The policy name. Policy names have the following characteristics:
  - Must be unique within the tenancy.
  - Are case insensitive.
  - Cannot be changed later.
  - Can be no more than 100 characters.
- Description: A description for the policy. This description can be no more than 400 characters.
- Create in Compartment: Select the compartment where you want to attach this policy. The policy will apply to this compartment and all child compartments of this compartment.
- Statements: Enter a policy statement. For information about how to write policy statements, see Writing Policy Statements.
  
  To add a second policy statement, click the Another Statement button. You can enter up to 50 statements. If you create more than one policy statement, you can click the X button next to a statement to delete that statement.
- Tagging: (Optional) Add defined or free-form tags for this policy as described in Adding Tags at Resource Creation. Tags can also be applied later.
Click the Submit button.

The details page for the new policy is displayed. The Resources section of the page shows the policy statements.

Using the OCI CLI

Get the OCID of the compartment where you want to attach the policy. The policy will apply to this compartment and all child compartments of this compartment.
```
$ oci iam compartment list --compartment-id-in-subtree true
```
Construct an argument for the --statements option.

The value of the --statements option argument is an array of policy statements in JSON format. This argument can be provided as a string on the command line or in a file. For information about how to write policy statements, see Writing Policy Statements.
(Optional) Construct arguments for defined or free-form tags for this policy as described in Adding Tags at Resource Creation. Tags can also be applied later.
Run the policy create command.

Syntax:
```
oci iam policy create -c compartment_OCID --name text --description "text" \
{ --statements '["statement","statement"]' | --statements file://policy.json }
```
The compartment_OCID is the compartment where you want to attach this policy. 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.

This command returns the same output as the policy get command.

Updating a Policy

Using the Compute Web UI To Modify the Policy Description or Tags

In the navigation menu, click Identity, and then click Policies.
If the policy that you want to modify is not listed, select the correct compartment from the Compartment drop-down menu above the policies list.
For the policy that you want to modify, click the Actions menu for the policy, and click the Edit option.
Update the description or tags.

To modify tags, see Applying Tags to an Existing Resource.
Click the Save Changes button.

Using the Compute Web UI To Modify the Policy Statements

In the navigation menu, click Identity, and then click Policies.
If the policy that you want to modify is not listed, select the correct compartment from the Compartment drop-down menu above the policies list.
Click the name of the policy that you want to modify.
On the policy details page, scroll to the Resources section.
In the Statements list, click the Configure Policy Statements button.
In the Edit Statements in the policy_name Policy dialog, change or add policy statements.

To modify policy statements, see Writing Policy Statements.

To add a policy statement, click the Another Statement button. You can enter up to 50 statements.

If more than one policy statement exists, you can click the X button next to a statement to delete that statement.
Click the Submit button.

Using the OCI CLI

Get the policy OCID.

$ oci iam policy list --compartment-id compartment_OCID

(Optional) To change or add policy statements, construct an argument for the --statements option.

The value of the --statements option argument is an array of policy statements in JSON format. This argument can be provided as a string on the command line or in a file. For information about how to write policy statements, see Writing Policy Statements.

The argument that you provide for the --statements option replaces the existing statements in the policy. Be sure to include any statements that you want to keep from the existing policy. Use the policy get command to view and copy current policy statements.

If you do not specify the --force option, the system will display the existing statements in the policy and request that you confirm that you want to replace them.
(Optional) Construct arguments for defined or free-form tags for this policy as described in Adding Tags at Resource Creation.

Run the policy update command.

Syntax:

oci iam policy update --policy-id policy_OCID [ --description desc ] \
[ --defined-tags tags ] [ --freeform-tags tags ] \
[ --statements policy_statements --version-date "" ]

If you specify --statements, then you must include --version-date "".

This command returns the same output as the policy get command.

Deleting a Policy

Using the Compute Web UI

In the navigation menu, click Identity, and then click Policies.
If the policy that you want to delete is not listed, select the correct compartment from the Compartment drop-down menu above the policies list.
For the policy that you want to delete, click the Actions menu, and click the Delete option.
In the confirmation dialog, click the Delete button.

Using the OCI CLI

Get the policy OCID.

$ oci iam policy list --compartment-id compartment_OCID

Run the policy delete command.

Syntax:
```
oci iam policy delete --policy-id policy_OCID
```
This command returns the same output as the policy get command.

Federating with Microsoft Active Directory

Federating enables users at your company to use the same login credentials for the Private Cloud Appliance Compute Web UI that they already use for other logins in the company. To federate, an administrator creates a trust relationship between the existing identity provider and Oracle Private Cloud Appliance. When this relationship is established, federated users are prompted with a single sign-on when accessing the Compute Web UI.

For more information, see "Federating with Identity Providers" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.

You can federate multiple Active Directory (AD) accounts with Oracle Private Cloud Appliance. Each federation trust is for a single AD account. To create a trust, you perform some tasks in the Oracle Private Cloud Appliance Compute Web UI and some tasks in Active Directory Federation Services (ADFS).

Before you begin federating, make sure you have completed the following tasks:

Installed and configured Microsoft ADFS for your organization.
Created groups in AD that will map to groups in Oracle Private Cloud Appliance.
Created users in AD who will sign into the Oracle Private Cloud Appliance Compute Web UI.

Note:

Consider using a common prefix to name AD groups that you intend to map to Oracle Private Cloud Appliance. For example, use AD group names such as PCA_Administrators, PCA_NetworkAdmins, PCA_InstanceLaunchers.

Gathering Required Information from ADFS

To federate with Private Cloud Appliance, you need to have the SAML metadata document and the names of the AD groups that you want to map to Private Cloud Appliance groups.

Locate and download the SAML metadata document for your ADFS. The default location is:
```
https://your_hostname/FederationMetadata/2007-06/FederationMetadata.xml
```
You will upload this document when you create the identity provider.
Make a note of all the AD groups that you want to map to Private Cloud Appliance groups.

Important:

Ensure that you have all the Private Cloud Appliance groups configured before you add AD as an identity provider.

Verifying Identity Provider Self-Signed Certificates

Important:

You can skip this verification step if your ADFS certificate is signed by a known certificate authority. ADFS certificates that are signed by a known certificate authority should already exist in the Private Cloud Appliance certificate bundle.

The Private Cloud Appliance Certificate Authority (CA) is a self-signed OpenSSL generated root and intermediate x.509 certificate. This CA certificate is used to issue x.509 server/client certificates, enabling you to add outside CA trust information to the rack. If you use a self-signed certificate for ADFS, you will need to add outside CA trust information from ADFS to the management nodes on the rack.

Note:

If you are using the metadataUrl property to create or update an identity provider, then you need to add the identity provider's web server's certificate chain to the Private Cloud Appliance outside CA bundle. See your identity provider's documentation for how to find the web server's certificate chain and then perform Steps 3-8 in the following procedure.

Adding Outside CA Trust Information

From a browser, download the SAML metadata document for your ADFS as described in Gathering Required Information from ADFS

Open the file in a text or XML editor and locate the signing certificate section. For example:

<KeyDescriptor use="signing">
<KeyInfo>
<X509Data>
<X509Certificate>
<!--CERTIFICATE IS HERE-->
</X509Certificate>
</X509Data>
</KeyInfo>
</KeyDescriptor>

Log on to management node 1. By default, the name of management node 1 is pcamn01.
Navigate to /etc/pca3.0/vault and create a new directory named customer_ca.

Note:

You can use this directory for multiple files. For example, you can create a file for the identity provider certificate and one for the web server's certificate chain.
In the customer_ca directory, create a new file with extension .pem.
Copy the certificate from the FederationMetadata.xml file, which is located inbetween the <X509Certificate> and </X509Certificate> tag set, and paste the certificate into the new .pem file. Be sure to include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. For example:
```
-----BEGIN CERTIFICATE-----
CERTIFICATE CONTENT
-----END CERTIFICATE-----
```
Save and close the file.

Run the following command to update the ca_outside_bundle.crt on all management nodes:

python3 /usr/lib/python3.6/site-packages/pca_foundation/secret_service/cert_generator/cert_generator_app.py -copy_to_mns

Managing Identity Providers

To federate with an identity provider in Private Cloud Appliance, create the identity provider in the Compute Web UI, and map account groups.

This section also describes how to update your identity provider (for example, to update your metadata XML file when it expires), and how to view all identity providers, view details of an identity provider, and delete an identity provider.

Adding Active Directory as an Identity Provider

To federate with AD in Private Cloud Appliance, add AD as an identity provider. You can map account groups when you add AD as an identity provider, or you can map the account groups later.

Important:

Ensure that you have all the Private Cloud Appliance groups configured before you add AD as an identity provider.

Using the Compute Web UI

Sign in with your Private Cloud Appliance login and password.
Open the navigation menu, click Identity, and then click Federation.
On the Federation page, click the Create Identity Provider button.
On the Create Identity Provider dialog, provide the following information:
1. Display Name
  
  The name that the federated users see when they choose which identity provider to use to sign in to the Compute Web UI. This name must be unique across all identity providers that you add to the tenancy and cannot be changed.
2. Description
  
  A friendly description of the identity provider.
3. Authentication Contexts
  
  Click Add Class Reference and select an authentication context from the list.
  
  When one or more values are specified, Private Cloud Appliance (the relying party), expects the identity provider to use one of the specified authentication mechanisms when authenticating the user. The returned SAML response from the identity provider must contain an authentication statement with that authentication context class reference. If the SAML response authentication context does not match what is specified here, the Private Cloud Appliance authentication service rejects the SAML response with response code 400.
4. Encrypt Assertion (Optional)
  
  When enabled, the authorization service expects encrypted assertions from the identity provider. Only the authorization service can decrypt the assertion. When not enabled, the authorization service expects SAML tokens to be unencrypted, but protected, by SSL.
5. Force Authentication (Optional)
  
  When enabled, users are always asked to authenticate at their identity provider when redirected by the authorization service. When not enabled, users are not asked to re-authenticate if they already have an active login session with the identity provider.
6. Metadata
  
  Upload the FederationMetadata.xml document from your SAML 2.0 compliant identity provider. You can drag and drop the file or you can paste the XML content.
7. Tagging (Optional)
  
  Add any free-form or defined tags as described in Adding Tags at Resource Creation. Tags can also be applied later.
Click the Create Identity Provider button.

Your new identity provider is assigned an OCID and is displayed on the Federations page.

After the identity provider is added to your tenancy, create the group mappings between Private Cloud Appliance and Active Directory, as described in Creating Group Mappings.

Listing Identity Providers

Use this procedure to list all identity providers for a tenancy.

Using the Compute Web UI

Open the navigation menu, click Identity and then click Federation.

The Federation page opens with a list of all identity providers that are configured in this tenancy.

Using the OCI CLI

Get the following information:
- The OCID of the tenancy (oci iam compartment list -include-root)
- The protocol used for federation (SAML2)

Run the identity provider list command.

$ oci iam identity-provider list -c ocid1.tenancy.unique_ID \
--protocol SAML2

Viewing Identity Provider Details

Use this procedure to show detailed information for a specific identity provider.

The details shown for the identity provider include the OCID, authentication contexts, and settings such as the redirect URL.

Using the Compute Web UI

Open the navigation menu, click Identity and then click Federation.

The identity providers that are configured in this tenancy are listed.
For the identity provider whose details you want to view, click the Actions menu, and then click View Details.

The details page for that identity provider is displayed.

Using the OCI CLI

Get the OCID of the identity provider (oci iam identity-provider list)

Run the identity provider get command.

$ oci iam identity-provider get --identity-provider-id ocid1.identityprovider.unique_ID

Updating an Identity Provider

Using the Compute Web UI

Open the navigation menu, click Identity and then click Federation.

The identity providers that are configured in this tenancy are listed.
For the identity provider that you want to update, click the Actions menu, and then click Edit.
You can change any of the following information. For more complete descriptions, see Step 4 in Adding Active Directory as an Identity Provider. Consider the affect that some of these changes have on the federation.
- Description
- Authentication Contexts
  
  Add or delete a class reference.
- Encrypt Assertion
  
  Enable or disable encrypted assertions from the identity provider.
- Force Authentication
  
  Enable or disable redirect authentication from the identity provider.
- Metadata
  
  Upload a new FederationMetadata.xml document from the identity provider.
- Tagging
  
  Add or delete any free-form or defined tags.
Click the Update Identity Provider button.

Deleting an Identity Provider

If you want to remove the option for federated users to log into Private Cloud Appliance, you must delete the identity provider. Deleting the identity provider also deletes all of the associated group mappings.

Using the Compute Web UI

Open the navigation menu, click Identity and then click Federation.

The identity providers that are configured in this tenancy are listed.
For the identity provider that you want to delete, click the Actions menu and then click Delete.
At the Delete Identity Provider prompt, click Confirm.

A Success pop-up displays briefly, and then the identity provider is no longer in the Federation list.

Working with Group Mappings for an Identity Provider

When working with group mappings, keep in mind the following:

A given AD group is mapped to a single Private Cloud Appliance group.
Private Cloud Appliance group names cannot contain spaces and cannot be changed later. Allowed characters are letters, numerals, hyphens, periods, underscores, and plus signs (+).
You cannot update a group mapping. You can delete the mapping and add a new one.

Creating Group Mappings

After you have created an identity provider, you must create mappings from ADFS groups to Private Cloud Appliance groups.

Repeat the following procedure for each identity provider group you want to map.

Using the Compute Web UI

Open the navigation menu, click Identity and then click Federation.

The identity providers that are configured in this tenancy are listed.
Click the identity provider for which you want to create group mappings.

The details page for that identity provider is displayed.
Scroll to the Resources section and click Group Mappings.

The group mappings for this identity provider are listed.
Click the Add Mappings button.

The Create IDP Group Mapping dialog is displayed.
In the Name field, enter the exact name of the identity provider group.
From the Group list, select the Private Cloud Appliance group you want to map to the identity provider group.
Click Create IDP Group Mapping.

The new group mapping is displayed in the list.

Viewing Group Mappings

Using the Compute Web UI

Open the navigation menu, click Identity and then click Federation.

The identity providers that are configured in this tenancy are listed.
Click the name of the identity provider.

The details page for that identity provider is displayed.
Scroll to the Resources section and click Group Mappings.

The group mappings for this identity provider are listed.

Deleting a Group Mapping

Repeat the following procedure for each identity provider group you want to delete.

Using the Compute Web UI

Open the navigation menu, click Identity and then click Federation.

The identity providers that are configured in this tenancy are listed.
Click the identity provider for which you want to delete a group mapping.

The details page for that identity provider is displayed.
Scroll to the Resources section and click Group Mappings.

The group mappings for this identity provider are listed.
For the group mapping that you want to delete, click the Actions menu and then click Delete.
Click Confirm when prompted.

A Success pop-up displays briefly, and then the identity provider group mapping is no longer in the Group Mappings list.

Adding Oracle Private Cloud Appliance as a Trusted Relying Party in ADFS

Important:

The Private Cloud Appliance certificate bundle must be added to AD, so that ADFS can trust the Private Cloud Appliance certificate. If you do not do this, user logins will fail. For more information about the Private Cloud Appliancecertificate bundle, see Obtaining the Certificate Authority Bundle.

To complete the federation process, you must add Private Cloud Appliance as a trusted relying party in ADFS and then add associated relying party claim rules.

In the Compute Web UI on the Federation page, view the following text block:

You need the Private Cloud Appliance Federation Metadata document when setting up a trust with Microsoft Active Directory Federation Services or with other SAML 2.0-compliant identity providers. This is an XML document that describes the Private Cloud Appliance endpoint and certificate information. Click Here

Click "Click Here."

A metadata XML file opens in the browser with a URL similar to:

https://console.system-name.domain-name/wsapi/rest/saml/metadata/ocid1.tenancy.unique_ID

Copy the metadata XML file URL.
From the system installed with ADFS, open a browser window and paste the URL.
Save the file, making sure to use the .xml extension. For example, my-sp-metadata.xml.
Go to the AD FS Management Console and sign in to the account you want to federate.
Add Private Cloud Appliance as a trusted relying party.
1. Under AD FS, right-click Relying Party Trusts and the select Add Relying Party Trust.
2. In the Add Relying Party Trust Wizard Welcome page, select Claims Aware and then click Start.
3. On the Select Data Source page, select "Import data about the relying party from a file."
4. Click Browse and navigate to your my-sp-metadata.xml file and then click Open.
5. On the Specify Display Name page, enter a display name, add any optional notes for the relying party, and then click Next.
6. On the Choose Access Control Policy page, select the type of access you want to grant and then click Next.
7. On the Ready to Add Trust page, review the settings, and then click Next to save your relying party trust information.
8. On the Finish page, check "Configure claims issuance policy for this application" and then click Close.
  
  The Edit Claim Issuance Policy dialog appears, which you can leave open for the next section.

Adding Relying Party Claim Rules

After you add Private Cloud Appliance as a trusted relying party, you must add the claim rules so that the elements required (Name ID and groups) are added to the SAML authentication response.

To add a Name ID rule:

In the Edit Claim Issuance Policy dialog, click Add Rule.

The Select Rule Template dialog is displayed.
For Claim rule template, select Transform an Incoming Claim and then click Next.
Enter the following:
- Claim rule name: Enter a name for this rule. For example, nameid.
- Incoming claim type: Select the Microsoft Windows account name.
- Outgoing claim type: Select a claim type, for example, Name ID.
- Outgoing name ID format: Select Persistent Identifier.
- Select Pass through all claim values and then click Finish.
  
  The rule is displayed in the rules list.

The Issuance Transform Rules dialog displays the new rule.

If your AD users are in no more than 100 groups, you simply add the groups rule. However, if your AD users are in more than 100 groups, those users cannot be authenticated to use the Private Cloud Appliance Compute Web UI. For these groups, you must apply a filter to the groups rule.

To add the groups rule:

In the Issuance Transform Rules dialog, click Add Rule.

The Select Rule Template dialog is displayed.
For Claim rule template, select Send Claims Using a Custom Rule and then click Next.

In the Add Transform Claim Rule Wizard, enter the following:

Claim rule name: Enter groups.

Custom rule: Enter the custom rule.

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("https://auth.oraclecloud.com/saml/claims/groupName"), query = ";tokenGroups;{0}", param = c.Value);

Click Finish.

The Issuance Transform Rules dialog displays the new rule.

Setting Up Policies for the Groups

Configure policies to control the access the federated users have to the Private Cloud Appliance resources. For general information about policies, see "How Policies Work" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide. For specific information, see Managing Policies.

Providing Federated Users Sign-in Information

Do the following to enable a federated user to log into the Private Cloud Appliance Compute Web UI:

Provide the user with the URLfor the Compute Web UI.
Provide the user with the name of the tenancy to which they have access.
Ensure that you have configured the necessary group mappings.
Ensure that you have configured the necessary policies.

Important:

A federated user cannot log into Private Cloud Appliance by using the OCI CLI.