How Policies Work

Let's say your administrator creates a group called HelpDesk (in the default identity domain) whose job is to manage users and their credentials. Here is a policy that enables that:

Allow group default/HelpDesk to manage users in tenancy

Notice that because users reside in the tenancy (the root compartment), the policy simply states the word tenancy, without the word compartment in front of it.

Next, let's say you have a compartment called Project-A, and a group (in the default identity domain) called A-Admins whose job is to manage all of the Oracle Cloud Infrastructure resources in the compartment. Here's an example policy that enables that:

Allow group default/A-Admins to manage all-resources in compartment Project-A

Be aware that the policy directly above includes the ability to write policies for that compartment, which means A-Admins can control access to the compartment's resources. For more information, see Policy Attachment.

If you wanted to limit A-Admins' access to only launching and managing compute instances and block storage volumes (both the volumes and their backups) in the Project-A compartment, but the network itself lives in the Networks compartment, then the policy could instead be:

Allow group default/A-Admins to manage instance-family in compartment Project-A

Allow group default/A-Admins to manage volume-family in compartment Project-A

Allow group default/A-Admins to use virtual-network-family in compartment Networks

The third statement with the virtual-network-family resource-type enables the instance launch process, because the cloud network is involved. Specifically, the launch process creates a new VNIC and attaches it to the subnet where the instance resides.

For additional examples, see Common Policies.

Typically you'll specify a group or compartment by name in the policy. However, you can use the OCID instead. Just make sure to add "id" before the OCID. For example:

Allow group

 id ocid1.group.oc1..aaaaaaaaqjihfhvxmumrl3isyrjw3n6c4rzwskaawuc7i5xwe6s7qmnsbc6a

 to manage instance-family in compartment Project-A

You can specify multiple groups separated by IAM commas:

Allow group default/A-Admins, default/B-Admins to manage instance-family in compartment Projects-A-and-B

Oracle defines the possible verbs you can use in your policies. Here's a summary of the verbs, from least amount of access to the most:

The verb gives a certain general type of access (e.g., inspect lets you list and get resources). When you then join that type of access with a particular resource-type in a policy (e.g., Allow group XYZ to inspect compartments in the tenancy), then you give that group access to a specific set of permissions and API operations (e.g., ListCompartments, GetCompartment). For more examples, see Details for Verbs + Resource-Type Combinations. The Policy Reference includes a similar table for each service, giving you a list of exactly which API operations are covered for each combination of verb and resource-type.

There are some special exceptions or nuances for certain resource-types.

Users: Access to both manage users and manage groups lets you do anything with users and groups, including creating and deleting users and groups, and adding/removing users from groups. To add/remove users from groups without access to creating and deleting users and groups, only both use users and use groups are required. See Common Policies.

Policies: The ability to update a policy is available only with manage policies, not use policies, because updating a policy is similar in effect to creating a new policy (you can overwrite the existing policy statements). In addition, inspect policies lets you get the full contents of the policies.

Object Storage objects: inspect objects lets you list all the objects in a bucket and do a HEAD operation for a particular object. In comparison, read objects lets you download the object itself.

Load Balancer resources: Be aware that inspect load-balancers lets you get all information about your load balancers and related components (backend sets, etc.).

Networking resources:

Oracle also defines the resource-types you can use in your policies. First, there are individual types. Each individual type represents a specific type of resource. For example, the vcns resource-type is specifically for virtual cloud networks (VCNs).

To make policy writing easier, there are family types that include multiple individual resource-types that are often managed together. For example, the virtual-network-family type brings together a variety of types related to the management of VCNs (e.g., vcns, subnets, route-tables, security-lists, etc.). If you need to write a more granular policy that gives access to only an individual resource-type, you can. But you can also easily write a policy to give access to a broader range of resources.

In another example: Block Volume has volumes, volume-attachments, and volume-backups. If you need to give access to only making backups of volumes, you can specify the volume-backups resource-type in your policy. But if you need to give broad access to all of the Block Volume resources, you can specify the family type called volume-family. For a full list of the family resource-types, see Resource-Types.

Note that there are other ways to make policies more granular, such as the ability to specify conditions under which the access is granted. For more information, see Advanced Policy Features.

Some API operations require access to multiple resource-types. For example, LaunchInstance requires the ability to create instances and work with a cloud network. The CreateVolumeBackup operation requires access to both the volume and the volume backup. That means you'll have separate statements to give access to each resource-type (for an example, see Let volume backup admins manage only backups). These individual statements do not have to be in the same policy. And a user can gain the required access from being in different groups. For example, George could be in one group that gives the required level of access to the volumes resource-type, and in another group that gives the required access to the volume-backups resource-type. The sum of the individual statements, regardless of their location in the overall set of policies, gives George access to CreateVolumeBackup.

A basic feature of policies is the concept of inheritance: Compartments inherit any policies from their parent compartment. The simplest example is the Administrators group, which automatically comes with your tenancy (see The Administrators Group, Policy, and Administrator Roles). There's a built-in policy that enables the Administrators group (in the default identity domain) to do anything in the tenancy:

Allow group Administrators to manage all-resources in tenancy

Because of policy inheritance, the Administrators group can also do anything in any of the compartments in the tenancy.

To illustrate further, consider a tenancy with three levels of compartments: CompartmentA, CompartmentB, and ComparmentC, shown here:

Policies that apply to resources in CompartmentA also apply to resources in CompartmentB and CompartmentC. So this policy:

Allow group default/NetworkAdmins to manage virtual-network-family in compartment CompartmentA

allows the group NetworkAdmins (in the default identity domain) to manage VCNs in CompartmentA, CompartmentB, and CompartmentC.

Another basic feature of policies is the concept of attachment. When you create a policy you must attach it to a compartment (or the tenancy, which is the root compartment). Where you attach controls who can then modify it or delete it. If you attach it to the tenancy (for example, if the policy is in the root compartment), then anyone with access to manage policies in the tenancy can then change or delete it. Typically that's the Administrators group or any similar group you create and give broad access to. Anyone with access only to a child compartment can't change or delete that policy.

If you instead attach the policy to a child compartment, then anyone with access to manage the policies in that compartment can change or delete it. In practical terms, this means it's easy to give compartment administrators (for example, a group with access to manage all-resources in the compartment) access to manage their own compartment's policies, without giving them broader access to manage policies that reside in the tenancy. For an example that uses this kind of compartment administrator design, see Example Scenario. (Recall that because of policy inheritance, users with access to manage policies in the tenancy automatically can manage policies in compartments inside the tenancy.)

The process of attaching the policy is easy (whether attaching to a compartment or the tenancy): If you're using the Console, when you add the policy to IAM, ensure you're in the correct compartment when you create the policy. If you're using the API, you specify the OCID of the correct compartment (either the tenancy or other compartment) as part of the request to create the policy.

As described in the previous section, a policy statement must specify the compartment for which access is being granted (or the tenancy). Where you create the policy determines who can update the policy. If you attach the policy to the compartment or its parent, you can simply specify the compartment name. If you attach the policy further up the hierarchy, you must specify the path. The format of the path is each compartment name (or OCID) in the path, separated by a colon:

<compartment_level_1>:<compartment_level_2>: . . . <compartment_level_n>

For example, assume you have a three-level compartment hierarchy, shown here:

You want to create a policy to allow NetworkAdmins (in the default identity domain) to manage VCNs in CompartmentC. If you want to attach this policy to CompartmentC or to its parent, CompartmentB, write this policy statement:

Allow group default/NetworkAdmins to manage virtual-network-family in compartment CompartmentC

However, if you want to attach this policy to CompartmentA (so that only administrators of CompartmentA can modify it), write this policy statement that specifies the path:

Allow group default/NetworkAdmins to manage virtual-network-family in compartment CompartmentB:CompartmentC

To attach this policy to the tenancy, write this policy statement that specifies the path from CompartmentA to CompartmentC:

Allow group default/NetworkAdmins to manage virtual-network-family in compartment CompartmentA:CompartmentB:CompartmentC

It's possible that the definition of a verb or resource-type could change in the future. For example, let's say that the virtual-network-family resource-type changes to include a new kind of resource that's been added to Networking. By default, your policies automatically stay current with any changes in service definition, so any policy you have that gives access to virtual-network-family would automatically include access to the newly added resource.

The Policy Reference includes details of the specific resource-types for each service, and which verb + resource-type combination gives access to which API operations.