Policy Statement Syntax

The overall syntax of a policy statement is as follows:

Allow <subject> to <verb> <resource-type> in <location> where <conditions>

Additional spaces or line breaks in the statement have no effect.

Subject

Specify a group by name or OCID. You can specify multiple groups separated by commas. To cover all users in the tenancy, specify any-user.

These examples show how you can specify the subject in a policy statement.

To specify a single group by name:

Allow group A-admins to manage all-resources in compartment Project-A

To specify multiple groups by name (a space after the comma is optional):

Allow group A-admins, B-admins to manage all-resources in compartment Projects

To specify a single group by OCID (the OCID is shortened for brevity):

Allow group id ocid1.group...........<group1_unique_id>
to manage all-resources in compartment Project-A

To specify multiple groups by OCID (the OCIDs are shortened for brevity):

Allow 
group id ocid1.group...........<group1_unique_id>, 
group id ocid1.group...........<group2_unique_id>
to manage all-resources in compartment Projects

To specify any user in the tenancy:

Allow any-user to inspect users in tenancy

Verb

Specify a single verb.

Allow group A-admins to manage all resources in compartment Project-A

The policy syntax supports the following verbs, ordered by increasing permissions:


Verb	Type of Access	Target User
`inspect`	Ability to list resources, without access to any confidential information or user-specified metadata that might be part of that resource. Notes: The operation to list policies includes the contents of the policies themselves. The list operations for the Networking resource types return all the information, including the contents of security lists and route tables.	Third-party auditors
`read`	Includes `inspect` plus the ability to get user-specified metadata and the actual resource itself.	Internal auditors
`use`	Includes `read` plus the ability to work with existing resources. The actions vary by resource type. Includes the ability to update the resource, except for resource types where the "update" operation has the same effective impact as the "create" operation; for example `UpdatePolicy`, `UpdateSecurityList`, etc. In those cases the "update" ability is available only with the `manage` verb. In general, the verb `use` does not include the ability to create or delete that type of resource.	Day-to-day end users of resources
`manage`	Includes all permissions for the resource.	Administrators

The verb gives a certain general type of access. For example, inspect lets you list and get resources. You then join that type of access with a particular resource type in a policy. For example, allow group XYZ to inspect compartments in the tenancy. As a result, that group gains access to a specific set of permissions and API operations; for example ListCompartments, GetCompartment.

Resource Type

Specify a single resource-type, which can be:

An individual resource type; for example: vcns, subnets, instances, volumes, etc.
A family resource type; for example: virtual-network-family, instance-family, volume-family, etc.

A family resource type covers a variety of individual resource types that are typically used together.
all-resources: Covers all resources in the compartment or tenancy.

These examples show how you can specify the resource type in a policy statement.

To specify a single resource type:

Allow group HelpDesk to manage users in tenancy

To specify multiple resource types, use separate statements:

Allow group A-users to manage instance-family in compartment Project-A
Allow group A-users to manage volume-family in compartment Project-A

To specify all resources in the compartment or tenancy:

Allow group A-admins to manage all-resources in compartment Project-A

Here is an overview of the family resource types can be used in policy statements:


Family Resource Type	Description
`compute-management-family`	This aggregate resource covers the following individual resource types: `instance-configurations`, `instance-pools`, `cluster-networks`.
`instance-family`	This aggregate resource covers the following individual resource types: `app-catalog-listing`, `console-histories`, `instances`, `instance-console-connection`, `instance-images`, `volume-attachments`.
`volume-family`	This aggregate resource covers all individual resource types related to block volumes: `volumes`, `volume-attachments`, `volume-backups`, `boot-volume-backups`, `backup-policies`, `backup-policy-assignments`, `volume-groups`, `volume-group-backups`.
`virtual-network-family`	This aggregate resource covers all individual resource types related to the networking service. For example: VCNs, subnets, route tables, gateways, VNICs, network security groups, and so on.
`file-family`	This aggregate resource covers all individual resource types related to the file storage service: `file-systems`, `mount-targets`, `export-sets`.
`object-family`	This aggregate resource covers all individual resource types related to the object storage service: `objectstorage-namespaces`, `buckets`, `objects`.
`compute-container-family`	This aggregate resource covers all individual resource types related to the container instances service: `compute-container-instances` and `compute-containers`.

Location

Specify a single compartment by name or OCID. Or simply specify tenancy to cover the entire tenancy. Remember that users, groups, and compartments reside in the tenancy. Policies can be attached to either the tenancy or a child compartment.

The location is required in the statement. To attach a policy to a compartment, you must be in that compartment when you create the policy.

These examples show how you can specify the location in a policy statement.

To specify a compartment by name:

Allow group A-admins to manage all-resources in compartment Project-A

To specify a compartment by OCID:

Allow group A-admins to manage all-resources
in compartment id ocid1.compartment.oc1..aaaaaaaaexampleocid

To specify multiple compartments, use separate statements:

Allow group InstanceAdmins to manage instance-family in compartment Project-A
Allow group InstanceAdmins to manage instance-family in compartment Project-B

Allow group InstanceAdmins to manage instance-family
in compartment id ocid1.compartment.oc1..aaaaaaaayzexampleocid
Allow group InstanceAdmins to manage instance-family
in compartment id ocid1.compartment.oc1..abcabcabcexampledocid

Conditions

Specify one or more conditions. With multiple conditions, use any or all for a logical OR or AND, respectively.

These are the types of values you can use in conditions:


Value Type	Examples
String	Single quotation marks are required around the value. `'johnsmith@example.com'` `'ocid1.compartment.oc1..aaaaaaaaph...ctehnqg756a'`
Pattern	`/HR/` - matches strings that start with "HR" `/HR/` - matches strings that end with "HR" `/HR/` - matches strings that contain "HR"

These examples show how you can specify conditions in a policy statement.

Note

In the example statements, the condition to match group names makes it impossible for GroupAdmins to list all users and groups. The list operation does not involve specifying a group, which means there is no value to match the condition variable target.group.name. To resolve this, a statement including the inspect verb is added.

The following policy enables the GroupAdmins group to create, update, or delete any groups with names that start with "A-Users-":

Allow group GroupAdmins to manage groups in tenancy where target.group.name = /A-Users-*/
Allow group GroupAdmins to inspect groups in tenancy

The following policy enables the NetworkAdmins group to manage cloud networks in any compartment except the one specified:

Allow group NetworkAdmins to manage virtual-network-family in tenancy
where target.compartment.id != 'ocid1.compartment.oc1..aaaaaaaaexampleocid'

The following policy uses multiple conditions and lets GroupAdmins create, update, or delete any groups whose names start with "A-", except for the A-Admins group itself: