Advanced Policy Features

As part of a policy statement, you can specify one or more conditions that must be met in order for access to be granted.

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 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.

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.

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'}

You can scope access to only a set of allowed IP addresses. For example, you can write policy to allow only requests from a given public IP range to access a specific Object Storage bucket; or, you can allow only specific subnets of a specific VCN to make requests over a service gateway.

To restrict access to a set of IP addresses, do the following:

1. Create a network source object that specifies the allowed IP addresses. See Managing Network Sources for details.
2. Write a policy that uses the network source object in a condition.

Use the following variable in your policy:

request.networkSource.name='<network_source_name>'

For example:

allow group GroupA to manage object-family in tenancy where request.networkSource.name='corpnet'

You can use time-based variables in your policies to restrict the access granted in the policy to only certain time frames. This feature allows you to restrict actions on resources to particular times. For example, you can create a policy that allows access only through a specified date. A policy like this would be useful if your company hires contractors and you want to ensure access is not allowed past the contract end date. Or, you could allow access to resources only during business hours (for example, Monday-Friday 9:00 AM - 5:00 PM). This restriction can lower the risk of a bad actor making changes when they are more likely to go unnoticed.

The variables that you can use to scope access based on time are:

Usage for these variables is described in more detail in the following sections.

Allow group Contractors to manage instance-family in tenancy where request.utc-timestamp before '2022-01-01T00:00Z'

Allow group SummerInterns to manage instance-family in tenancy where ANY {request.utc-timestamp.month-of-year in ('6', '7', '8')}

Allow group ComplianceAuditors to read all-resources in tenancy where request.utc-timestamp.day-of-month = '1'

Allow group WorkWeek to manage instance-family where ANY {request.utc-timestamp.day-of-week in ('monday', 'tuesday', 'wednesday', 'thursday', 'friday')}

Allow group DayShift to manage instance-family where request.utc-timestamp.time-of-day between '17:00:00Z' and '01:00:00Z'

Allow group NightShift to manage instance-family where request.utc-timestamp.time-of-day between '01:00:00Z' and '17:00:00Z'