Getting Started with Policies
To get started, first decide whether and how to get started with policies and familiarize yourself with common questions about policies.
If you're new to IAM policies, this topic gives guidance on how to proceed.
If You're Doing a Proof-of-Concept
Create a proof-of-concept project with infrastructure resources.
If you're just trying out Oracle Cloud Infrastructure or doing a proof-of-concept project with infrastructure resources, you may not need more than a few administrators with full access to everything. In that case, you can simply create any new users you need and add them to the Administrators group. The users will be able to do anything with any kind of resource. And you can create all your resources directly in the tenancy (the root compartment). You don't need to create any compartments yet, or any other policies beyond the Tenant Admin Policy, which automatically comes with your tenancy and can't be changed.
Don't forget to add your new users to the Administrators group; it's easy to forget to do that after creating them.
If You're Past the Proof-of-Concept Phase
Restrictding access to resources after the proof-of-concept phase.
If you're past the proof-of-concept phase and want to restrict access to your resources, first:
- Make sure you're familiar with the basic IAM components, and read through the example scenario: Example Scenario
- Think about how to organize your resources into compartments: Learn Best Practices for Setting Up Your Tenancy
- Learn the basics of how policies work: How Policies Work
- Check out some typical policies: Common Policies
- Read the next section for more information
More Information About Policies
More information about policies.
All of them, including IAM itself. You can find specific details for writing policies for each service in the Policy Reference.
Yes. All users can automatically do these things without an explicit policy:
- Change or reset their own Console password.
- Manage their own API signing keys and other credentials.
You could put all your resources into a single compartment and use policies to control access, but then you would lose the benefits of measuring usage and billing by compartment, simple policy administration at the compartment level, and clear separation of resources between projects or business units.
Yes. However, a couple things to know first:
- Enterprise companies typically have several users that need similar permissions, so policies are designed to give access to groups of users, not individual users. A user gains access by being in a group.
- Policies are designed to allow access, and there's no explicit "deny" when you write a policy.
If you need to grant access to a particular user, you can add a condition to the policy that specifies the user's OCID in a variable. This construction restricts the access granted in the policy to only the user specified in the condition. For example:
allow any-group to read object-family in compartment ObjectStorage where request.user.id ='ocid1.user.oc1..<user_OCID>'For information about using conditions and variables in policies, see Conditions.
If you need to restrict a particular user's access, you can:
- Remove the user from the particular group of interest
- Delete the user entirely from IAM (you must remove the user from all groups first)
First ensure the user isn't in any groups. Only then can you delete the user.
You need to look at the individual statements in all your policies to see which statements apply to which group. There's not currently an easy way to get this information.
You need to look at the individual statements in all the policies in the tenancy to see if any apply to the particular compartment. You also need to look at any policies in the compartment itself. Policies in any of the sibling compartments cannot refer to the compartment of interest, so you don't need to check those policies.
Understanding Policies
IAM uses policies to restrict access to resources.
By default, policies exist at the tenancy level and can be applied to identity domains. You can also create policies with a smaller scope, for example, limiting access to a specific resource. See How Policies Work.
Example Scenario
Examples showing how different IAM components work together.
The goal of this scenario is to show how the different IAM components work together, and basic features of policies.
In this scenario, Acme Company has two teams that will be using Oracle Cloud Infrastructure resources for infrastructure: Project A and Project B. In reality, your company may have many more.
Acme Company plans to use a single virtual cloud network (VCN) for both teams, and wants a network administrator to manage the VCN.
Acme Company also wants the Project A team and Project B team to each have their own set of instances and block storage volumes. The Project A team and Project B teams shouldn't be able to use each other's instances. These two teams also shouldn't be allowed to change anything about the VCN set up by the network administrator. Acme Company wants each team to have administrators for that team's resources. The administrators for the Project A team can decide who can use the Project A cloud resources, and how. Same for the Project B team.
Acme Company Gets Started with Oracle Cloud Infrastructure
Acme Company signs up to use Oracle Cloud Infrastructure and tells Oracle that an employee named Wenpei will be the default administrator. In response, Oracle:
- Creates a tenancy for Acme Company (see the following diagram).
- Creates an IAM user account for Wenpei in the tenancy.
- Creates the Administrators group in the tenancy and places Wenpei in that group.
- Creates a policy in Acme Company's tenancy that gives the Administrators group access to manage all of the resources in the tenancy. Here's that policy:
Allow group Administrators to manage all-resources in tenancy
The Default Administrator Creates Some Groups and Another Administrator
Wenpei next creates several groups and users (see the following diagram). She:
- Creates groups called NetworkAdmins, A-Admins, and B-Admins (these last two are for Project A and Project B within the company)
- Creates a user called Alex and puts him in the Administrators group.
- Leaves the new groups empty.
To learn how to create groups, see Managing Groups. To learn how to create users and put them in groups, see Managing Users.
The Default Administrator Creates Some Compartments and Policies
Wenpei next creates compartments to group resources together (see the following diagram). She:
- Creates a compartment called Networks to control access to the Acme Company's VCN, subnets, Site-to-Site VPN, and other components from Networking.
- Creates a compartment called Project-A to organize Project A team's cloud resources and control access to them.
- Creates a compartment called Project-B to organize Project B team's cloud resources and control access to them.
To learn how to manage compartments, see Managing Compartments.
Wenpei then creates a policy to give the administrators for each compartment their required level of access. She attaches the policy to the tenancy, which means that only users with access to manage policies in the tenancy can later update or delete the policy. In this scenario, that is only the Administrators group. The policy includes multiple statements that:
- Give the NetworkAdmins group access to manage networks and instances (for the purposes of easily testing the network) in the Networks compartment
- Give both the A-Admins and B-Admins groups access to use the networks in the Networks compartment (so they can create instances into the network).
- Give the A-Admins group access to manage all resources in the Project-A compartment.
- Give the B-Admins group access to manage all resources in the Project-B compartment.
Here's what that policy looks like (notice it has multiple statements in it):
Allow group NetworkAdmins to manage virtual-network-family in compartment Networks
Allow group NetworkAdmins to manage instance-family in compartment Networks
Allow group A-Admins,B-Admins to use virtual-network-family in compartment Networks
Allow group A-Admins to manage all-resources in compartment Project-A
Allow group B-Admins to manage all-resources in compartment Project-B
Notice the difference in the verbs (manage, use), as well as the
resources (virtual-network-family, instance-family, all-resources).
For more information about them, see Verbs and
Resource-Types.To learn how to create
policies, see Creating a Policy.
A-Admins and B-Admins can use the virtual-network-family in the compartment Networks. However, they can't create instances in that compartment. They can only create instances in the Project-A or Project-B compartment. Remember, a compartment is a logical grouping, not a physical one, so resources that make up or reside on the same VCN can belong to different compartments.
Acme Company wants to let the administrators of the Project-A and Project-B compartments decide which users can use the resources in those compartments. So Wenpei creates two more groups: A-Users and B-Users. She then adds six more statements that give the compartment admins the required access they need in order to add and remove users from those groups:
Allow group A-Admins to use users in tenancy where target.group.name='A-Users'
Allow group A-Admins to use groups in tenancy where target.group.name='A-Users'
Allow group B-Admins to use users in tenancy where target.group.name='B-Users'
Allow group B-Admins to use groups in tenancy where target.group.name='B-Users'
Allow group A-Admins,B-Admins to inspect users in tenancy
Allow group A-Admins,B-Admins to inspect groups in tenancyNotice that this policy doesn't let the project admins create new users or manage credentials for the users. It lets them decide which existing users can be in the A-Users and B-Users groups. The last two statements are necessary for A-Admins and B-Admins to list all the users and groups, and confirm which users are in which groups.
| Item | Description |
|---|---|
 |
Policies attached to the tenancy:
|
An Administrator Creates New Users
At this point, Alex is in the Administrators group and now has access to create new users. So he provisions users named Leslie, Jorge, and Cheri and places them in the NetworkAdmins, A-Admins, and B-Admins groups, respectively. Alex also creates other users who will eventually be put in the A-Users and B-Users groups by the admins for Project A and Project B.
| Item | Description |
|---|---|
|
Policies attached to the tenancy:
|
The Network Admin Sets Up the Network
Leslie (in the NetworkAdmins group) has access to manage virtual-network-family and instance-family in the Networks compartment. She creates a virtual cloud network (VCN) with a single subnet in that compartment. She also sets up an Internet gateway for the VCN, and updates the VCN's route table to allow traffic via that gateway. To test the VCN's connectivity to the on-premises network, she launches an instance in the subnet in the VCN. As part of the launch request, she must specify which compartment the instance should reside in. She specifies the Networks compartment, which is the only one she has access to. She then confirms connectivity from the on-premises network to the VCN by logging in to the instance via SSH from the on-premises network.
Leslie terminates her test instance and lets Jorge and Cheri know that the VCN is up and running and ready to try out. She lets them know that their compartments are named Project-A and Project-B respectively. For more information about setting up a cloud network, see Networking. For information about launching instances into the network, see Compute.
Compartment Admins Set Up Their Compartments
Jorge and Cheri now need to set up their respective compartments. Each admin needs to do the following:
- Launch instances in their own compartment
- Put users in their "users" group (e.g., A-Users)
- Decide the type of access to give those users, and accordingly attach a policy to their compartment
Jorge and Cheri both launch instances into the subnet in the VCN, into their respective team's compartments. They create and attach block volumes to the instances. Only the compartment admins can launch/terminate instances or attach/detach block volumes in their respective team's compartments.
Network Topology and Compartment Access Are Different Concepts
It's important to understand the difference between the network topology of the VCN and the access control that the compartments provide. The instances Jorge launched reside in the VCN from a network topology standpoint. But from an access standpoint, they're in the Project-A compartment, not the Networks compartment where the VCN is. Leslie (the Networks admin) can't terminate or reboot Jorge's instances, or launch new ones into the Project-A compartment. But Leslie controls the instances' network, so she controls what traffic will be routed to them. If Jorge had specified the Networks compartment instead of the Project-A compartment when launching his instances, his request would have been denied. The story is similar for Cheri and the Project-B compartment.
But it's also important to note that Wenpei and Alex in the Administrators group do have access to the resources inside the compartments, because they have access to manage all kinds of resources in the tenancy. Compartments inherit any policies attached to their parent compartment (the tenancy), so the Administrators access also applies to all compartments within the tenancy.
Next, Jorge puts several of the users that Alex created into the A-Users group. Cheri does the same for B-Users.
Then Jorge writes a policy that gives users the level of access they need in the Project-A compartment.
Allow group A-Users to use instance-family in compartment Project-A
Allow group A-Users to use volume-family in compartment Project-A
Allow group A-Users to inspect virtual-network-family in compartment Networks
This lets them use existing instances (with attached block volumes) that the compartment admins already launched in the compartment, and stop/start/reboot them. It does not let A-Users create/delete or attach/detach any volumes. To give that ability, the policy would need to include manage volume-family.
Jorge attaches this policy to the Project-A compartment. Anyone with the ability to manage policies in the compartment can now modify or delete this policy. Right now, that is only the A-Admins group (and the Administrators group, which can do anything throughout the tenancy).
Cheri creates and attaches her own policy to the Project-B compartment, similar to Jorge's policy:
Allow group B-Users to use instance-family in compartment Project-B
Allow group B-Users to use volume-family in compartment Project-B
Allow group B-Users to inspect virtual-network-family in compartment Networks
Now the A-Users and B-Users can work with the existing instances and attached volumes in the Project-A and Project-B compartments, respectively. Here's what the layout looks like:
| Item | Description |
|---|---|
|
Policies attached to the tenancy:
|
 |
Policy attached and managed by Jorge:
|
 |
Policy attached and managed by Cheri:
|
For more information about basic and advanced features of policies, see How Policies Work. For examples of other typical policies your organization might use, see Common Policies.
Allow backup admins to manage only backups.
Type of access: Ability to do all things with volume backups, but not create and manage volumes themselves. This makes sense if you want to have a single set of volume backup admins manage all the volume backups in all the compartments. The first statement gives the required access to the volume that is being backed up; the second statement enables creation of the backup (and the ability to delete backups). The third statement enables the creation and management of user defined backup policies; the fourth statement enables assignment and removal of assignment of backup policies.
Where to create the policy: In the tenancy, so that the access is easily granted to all compartments by way of policy inheritance. To reduce the scope of access to just the volumes and backups in a particular compartment, specify that compartment instead of the tenancy.
Allow group VolumeBackupAdmins to use volumes in tenancy
Allow group VolumeBackupAdmins to manage volume-backups in tenancy
Allow group VolumeBackupAdmins to manage backup-policies in tenancy
Allow group VolumeBackupAdmins to manage backup-policy-assignments in tenancyIf the group will be using the Console, the following policy gives a better user experience:
Allow group VolumeBackupAdmins to use volumes in tenancy
Allow group VolumeBackupAdmins to manage volume-backups in tenancy
Allow group VolumeBackupAdmins to inspect volume-attachments in tenancy
Allow group VolumeBackupAdmins to inspect instances in tenancy
Allow group VolumeBackupAdmins to manage backup-policies in tenancy
Allow group VolumeBackupAdmins to manage backup-policy-assignments in tenancyThe last two statements are not necessary in order to manage volume backups. However, they enable the Console to display all the information about a particular volume and the available backup policies.
Policy Attachment
Policy attachments
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 it controls who can then modify it or delete it. If you attach it to the tenancy (in other words, 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 cannot modify 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 (i.e., 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 have the ability to 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, simply make sure you're in the desired compartment when you create the policy. If you're using the API, you specify the OCID of the desired compartment (either the tenancy or other compartment) as part of the request to create the policy.
When you attach a policy to a compartment, you must be in that compartment and you must indicate directly in the statement which compartment it applies to. If you are not in the compartment, you'll get an error if you try to attach the policy to a different compartment. Notice that attachment occurs during policy creation, which means a policy can be attached to only one compartment. To learn how to attach a policy to a compartment, see Creating a Policy.