Oracle Cloud Infrastructure Documentation

Advanced Policy Features

This section describes policy language features that let you grant more granular access.

Conditions

As part of a policy statement, you can specify one or more conditions that must be met in order for access to be granted. For a simple example, see Let group admins manage group membership.

Each condition consists of one or more predefined variables that you specify values for in the policy statement. Later, when someone requests access to the resource in question, if the condition in the policy is met, it evaluates to true and the request is allowed. If the condition is not met, it evaluates to false and the request is not allowed.

There are two types of variables: those that are relevant to the request itself, and those relevant to the resource(s) being acted upon in the request, also known as the target. The name of the variable is prefixed accordingly with either request or target followed by a period. For example, there's a request variable called request.operation to represent the API operation being requested. This variable lets you write a broad policy statement, but add a condition based on the specific API operation. For an example, see Let users write objects to Object Storage buckets.

Variables that Aren't Applicable to a Request Result in a Declined Request

If the variable is not applicable to the incoming request, the condition evaluates to false and the request is declined. For example, here are the basic policy statements that together let someone add or remove users from any group except Administrators:

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

Allow group GroupAdmins to use groups in tenancy
where target.group.name != 'Administrators'

Given the above policy, if GroupAdmins tried to call a general API operation for users such as ListUsers or UpdateUser (which lets you change the user's description), the request would be declined, even though those API operations are covered by use users.This is because the above policy statement for use users also includes the target.group.name variable, but the ListUsers or UpdateUser request doesn't involve specifying a group. There is no target.group.name for those requests, so the request is declined.

If you want to also grant access to general user API operations that don't involve a particular group, you would need an additional statement that gives the level of access you want to grant, but without the condition. For example, if you want to grant access to ListUsers, you need this additional statement:

Allow group GroupAdmins to inspect users in tenancy

Or if you want to grant access to UpdateUser, you need this additional statement (which also covers ListUsers because the use verb includes the capabilities of the inspect verb):

Allow group GroupAdmins to use users in tenancy

This general concept also applies to groups (e.g., ListGroups and UpdateGroup), and any other resource type with target variables.

For more information about the syntax of conditions, see Conditions. For a list of all the variables you can use in policies, see the tables in the Policy Reference.

Permissions

Permissions are the atomic units of authorization that control a user's ability to perform operations on resources. Oracle defines all the permissions in the policy language. When you write a policy giving a group access to a particular verb and resource-type, you're actually giving that group access to one or more predefined permissions. The purposes of verbs is to simplify the process of granting multiple related permissions that cover a broad set of access or a particular operational scenario. The next sections give more details and examples.

Relation to Verbs

To understand the relationship between permissions and verbs, let's look at an example. A policy statement that allows a group to inspect volumes actually gives the group access to a permission called VOLUME_INSPECT (permissions are always written with all capital letters and underscores). In general, that permission enables the user to get information about block volumes.

As you go from inspect > read > use > manage, the level of access generally increases, and the permissions granted are cumulative. The following table shows the permissions included with each verb for the volumes resource-type. Notice that no additional permissions are granted going from inspect to read.

Inspect Volumes Read Volumes Use Volumes Manage Volumes
VOLUME_INSPECT VOLUME_INSPECT

VOLUME_INSPECT

VOLUME_UPDATE

VOLUME_WRITE

VOLUME_INSPECT

VOLUME_UPDATE

VOLUME_WRITE

VOLUME_CREATE

VOLUME_DELETE

The policy reference lists the permissions covered by each verb for each given resource-type. For example, for block volumes and other resources covered by the Core Services, see the tables in Details for Verb + Resource-Type Combinations. The left column of each of those tables lists the permissions covered by each verb. The other sections of the policy reference include the same kind of information for the other services.

Relation to API Operations

Each API operation requires the caller to have access to one or more permissions. For example, to use either ListVolumes or GetVolume, you must have access to a single permission: VOLUME_INSPECT. To attach a volume to an instance, you must have access to multiple permissions, some of which are related to the volumes resource-type, some to the volume-attachments resource-type, and some related to the instances resource-type:

  • VOLUME_WRITE
  • VOLUME_ATTACHMENT_CREATE
  • INSTANCE_ATTACH_VOLUME

The policy reference lists which permissions are required for each API operation. For example, for the Core Services API operations, see the table in Permissions Required for Each API Operation.

Understanding a User's Access

The policy language is designed to let you write simple statements involving only verbs and resource-types, without having to state the desired permissions in the statement. However, there may be situations where a security team member or auditor wants to understand the specific permissions a particular user has. The tables in the policy reference show each verb and the associated permissions. You can look at the groups the user is in and the policies applicable to those groups, and from there compile a list of the permissions granted. However, having a list of the permissions isn't the complete picture. Conditions in a policy statement can scope a user's access beyond individual permissions (see the next section). Also, each policy statement specifies a particular compartment and can have conditions that further scope the access to only certain resources in that compartment.

Scoping Access with Permissions or API Operations

In a policy statement, you can use conditions combined with permissions or API operations to reduce the scope of access granted by a particular verb.

For example, let's say you want group XYZ to be able to list, get, create, or update groups (i.e., change their description), but not delete them. To list, get, create, and update groups, you need a policy with manage groups as the verb and resource-type. According to the table in Details for Verbs + Resource-Type Combinations, the permissions covered are:

  • GROUP_INSPECT
  • GROUP_UPDATE
  • GROUP_CREATE
  • GROUP_DELETE

To restrict access to only the desired permissions, you could add a condition that explicitly states the permissions you want to allow:

Allow group XYZ to manage groups in tenancy

where any {request.permission='GROUP_INSPECT', request.permission='GROUP_CREATE', request.permission='GROUP_UPDATE'}

An alternative would be a policy that allows all permissions except GROUP_DELETE:

Allow group XYZ to manage groups in tenancy where request.permission != 'GROUP_DELETE'

However, with this approach, be aware that any new permissions the service might add in the future would automatically be granted to group XYZ. Only GROUP_DELETE would be omitted.

Another alternative would be to write a condition based on the specific API operations. Notice that according to the table in Permissions Required for Each API Operation, both ListGroups and GetGroup require only the GROUP_INSPECT permission. Here's the policy:

Allow group XYZ to manage groups in tenancy

where any {request.operation='ListGroups', request.operation='GetGroup', request.operation='CreateGroup', request.operation='UpdateGroup'}

It can be beneficial to use permissions instead of API operations in conditions. In the future, if a new API operation is added that requires one of the permissions listed in the permissions-based policy above, that policy will already control XYZ group's access to that new API operation.

But notice that you can further scope a user's access to a permission by also specifying a condition based on API operation. For example, you could give a user access to GROUP_INSPECT, but then only to ListGroups.

Allow group XYZ to manage groups in tenancy

where all {request.permission='GROUP_INSPECT', request.operation='ListGroups'}

Policy Language Version

As mentioned in Policies and Service Updates, by default your policies stay current with any changes to the definitions of verbs and resources as the services change. If you'd prefer to limit access according to the definitions that were current on a specific date, you can do that. When creating a policy, you can specify a date, and that is considered its "version". You can also update the version for an existing policy. For more information, see To create a policy and also To update the version date for an existing policy.