The latest cloud infrastructure announcements, technical solutions, and enterprise cloud insights.

  • January 26, 2018

Announcing Instance Principals for Identity and Access Management

Moumita Ghosh
Sr Manager Software Development

We are excited to announce a new capability in the Oracle Cloud Infrastructure Identity and Access Management (IAM) service called instance principals. We have enhanced the the instance principals feature by adding the ability to include instances in a dynamic group by using their tags. Now it is easy to add instances to dynamic groups by simply tagging them. The “Create a Dynamic Group” section of this post has been updated to reflect this exciting new feature.

Currently customers have to manage credentials on compute instances (both bare metal and virtual machines) to make calls to IAM-protected Oracle Cloud Infrastructure APIs. These credentials need to be rotated at regular intervals for security and compliance. Based on the number of instances that need this access, this process can become tedious and error prone.

With instance principals, customers no longer need to configure user credentials on the services running on their compute instances, or rotate those credentials. Instances themselves are a new principal type in IAM. Each Compute instance has its own identity, and it authenticates by using certificates that are added to the instance by the new instance principals capability. Because these certificates are automatically created, assigned to instances, and rotated, customers do not need to manually distribute credentials to their hosts and rotate them.

Just as you can create policies to permit users, or groups, to make Oracle Cloud Infrastructure API calls, you can now use policies to permit Compute instances to do the same. You can group instances in logical sets called dynamic groups. Membership in the group can be determined by a set of matching rules. Resources that match the rule criteria are members of the dynamic group.

Applications can make calls to the following Oracle Cloud Infrastructure services by using instance principals:

  • Compute
  • Networking
  • Block Volumes
  • Object Storage
  • Load Balancing
  • Database

In this post, we’ll walk through an example that demonstrates the following steps, where an instance runs a Python script to read data from Object Storage:

  1. Create a dynamic group.
  2. Create a policy that grants permissions to that dynamic group.
  3. Build the script or application that will run on the instance.
  4. Deploy the application and Oracle Cloud Infrastructure SDK package to the instances in the dynamic group.

Note that you must be a tenant administrator to create and manage dynamic groups.

Create a Dynamic Group

When creating a dynamic group, you must provide a unique, unchangeable name for the dynamic group. The name must be unique across all groups within your tenancy. You can provide a description of the dynamic group, but it is not required. Oracle will assign the group a unique ID called an Oracle Cloud ID (OCID) after it is created.

  1. In the Oracle Cloud Infrastructure Console, go to the Identity tab, choose Dynamic Groups from the menu, and then click Create Dynamic Groups.

    You can use the rule builder or use the text box. The rule builder makes it easy to define the matching rules for a dynamic group and automatically constructs the rule. 

  2. Choose the attributes that you want to group instances on and add them to the dynamic group. The rule builder automatically populates the matching rule text box with the rule. Here we choose that any instance that meets all of the following rules will be included:
    • All the instances in the specified compartment ID
    • A particular instance​​

Tags are currently not supported on the rule builder. You will have to use the text box to construct the matching rule. 

Assume you have a tag namespace called operations and a tag key called department with value one.

The matching rule will have the following syntax:




  1. Click Add Rule.
  2. Click Create Dynamic Group.
    The group is created and appears in the list of dynamic groups on the same page.

Create a Policy

  1. Create a policy to allow instances in the dynamic group to read buckets from Object Storage. To learn more, see Overview of Object Storage.

  2. Create a bucket in Object Storage. Code running on the instances part of the dynamic group should be able to read objects from this Object Storage bucket, based on the policy defined in the previous step.

  3. Upload an object (in this example, test.txt) in the test bucket.

  4. Create an instance that is part of the dynamic group that you previously created (check the matching rules, and ensure that the instance fulfills this criteria). In this example, any instance with the compartment ID in the matching rules would be part of the dynamic group.

    The instance is now created, and you should be able to read the contents of the Object Storage bucket (TestBucket), based on the policy set on the dynamic group, from the instance.

Install the SDK on Instances in the Dynamic Group

  1. Log in to the instance and install the Python SDK.
  2. Run the following Python script on the instance. The script lists the available buckets in Object Storage in the compartment on which you defined the dynamic group, and also writes the contents of the TestBucket.

import oci

import os

compartment_id = '<use your compartment ocid'

bucket_name = 'TestBucket'

object_name = 'test.txt'

signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()


# listing the buckets in the object storage account

object_storage_client = oci.object_storage.ObjectStorageClient(config={}, signer=signer)


print(object_storage_client.list_buckets(namespace_name=object_storage_client.get_namespace().data, compartment_id=compartment_id).data)


# listing the objects in the bucket TestBucket

same_obj = object_storage_client.get_object(object_storage_client.get_namespace().data, bucket_name, object_name)

print('Object that we get from the bucket: {}'.format(same_obj.data.content))

The instance can execute the list bucket operation because you defined the policy on the dynamic group to be able to read buckets. Because the instance is part of the dynamic group, it inherits the policy defined on the dynamic group.

Executing the script produces the following output, which lists all the buckets in the compartment. The TestBucket bucket, created previously, is shown in the output. The contents of the bucket are also printed.



  "compartment_id": "ocid1.compartment.oc1..aaaaaaaazsqcco7shp5jm44q2fmshzzlehlacx4xqbkojbr7jjs5ueaxpysq",

  "created_by": "ocid1.user.oc1..aaaaaaaa3uxakjcfqmvrenyejkcdm6zohl6sj6dros3pjlj3dztxqr4beb4a",

  "etag": "52ae351a-3e78-4554-9b8b-da0c35fc114b",

  "name": "TestBucket",

  "namespace": "securityproducts",

  "time_created": "2017-12-20T22:07:02.062000+00:00"


The object that we get from the bucket is test.txt.

Our team is building this new instance principals capability in IAM in Oracle Cloud Infrastructure. If you have any questions related to this topic or you want to provide feedback, please post your comment below or reach out to me directly.

Moumita Ghosh, Sr Manager Software Development

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha