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 or compute instances to access resources. The users or instances 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 subjects are granted access. This set of resources is also called the target. Conditions can be used to narrow the subject, the target, and the operations that can be performed on the target.

The following is the policy statement syntax:

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

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

subject

One or more user groups (group) or any-user, or one or more dynamic groups (dynamic-group). To specify more than one user group or dynamic 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 statements 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 tenancy, 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 tenancy, 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 tenancy 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.
  - Cannot include spaces. Can include only letters, numbers, hyphens, periods, or underscores.
- 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 Create Policy 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.