Accessing the Oracle Cloud Infrastructure API Using Instance Principals

Instance principals is a capability in Oracle Cloud Infrastructure Identity and Access Management (IAM) that lets you make service calls from an instance. With instance principals, you don’t need to configure user credentials on the services running on your compute instances or rotate the credentials. Instances themselves are now a principal type in IAM. Each compute instance has its own identity, and it authenticates by using certificates that are added to the instance. These certificates are automatically created, assigned to instances, and rotated.

You use instance principals to authorize an instance to make API or CLI calls in Oracle Cloud Infrastructure (OCI) services. After you set up the required resources and policies, an application running on an instance can call OCI public services. For more information, see Calling Services from an Instance.

Dynamic Groups and Matching Rules

Dynamic groups let you group OCI instances as principal actors, similar to group users into user groups. You can then create policies to permit instances in these groups to make API calls against OCI services.

Membership in the group is determined by a set of criteria that you define called matching rules. Resources that match the rule criteria are members of the dynamic group. Matching rules have a specific syntax.

Security Considerations

Any user who has access to the instance (who can use SSH to connect to the instance) automatically inherits the privileges granted to the instance. Before you grant permissions to an instance by using instance principals, ensure that you know who can access it and that they should be authorized with the permissions you are granting to the instance.

All compute instance principals are granted the compartment_inspect permission. You can’t revoke this permission.

Enable Instances to Call Services

Perform these tasks to enable an instance to call services:

1. Create an OCI instance on a public subnet

2. Create a dynamic group and matching rules

3. Write policies for dynamic groups

4. Install and configure the OCI CLI

5. Create an Object Storage bucket using the OCI CLI and instance principal authentication

Create an OCI Instance on Public Subnet

To create an OCI instance, sign in to the Oracle Cloud Infrastructure Console and follow these steps. You must already have created a virtual cloud network (VCN) with a public subnet.

1. Open the navigation menu, select Compute, and then select Instances.
2. Click Create Instance.
3. Specify a name for the instance, for example, Bastion.
4. Select the compartment in which you want to place the instance.

By default, the Oracle Linux operating system image is selected. You don’t need to change it for this exercise.

5. Choose the availability domain in which you want to place the instance.
6. Select a shape for the virtual machine (VM), for example, VM.Standard.E2.1.Micro (which is eligible for an Always Free account).
7. In the Configure networking section, select the compartment in which your VCN resides. This is typically in the same compartment in which you’re deploying this VM.
8. Select the VCN.
9. Select the compartment in which the subnet resides.
10. Select the public subnet.

Figure 1: Create a Compute Instance

11. In the Add SSH keys section, select Generate SSH Key Pair and click Save Private Key and Save Public Key to save the keys on your computer.
12. Click Create.

After the instance is created, the instance details page is displayed. Make a note of the OCID of this instance and also the public IP address.

Figure 2: Compute Instance Details Page

Create a Dynamic Group and Matching Rules

Dynamic groups allow you to group Oracle Cloud Infrastructure computer instances as “principal” actors (similar to user groups). You can then create policies to permit instances to make API calls against OCI services.

When you create a dynamic group, rather than adding members explicitly to the group, you instead define a set of matching rules to define the group members. For example, a rule could specify that all instances in a particular compartment are members of the dynamic group. The members can change dynamically as instances are created and deleted in that compartment.

To create a dynamic group and matching rules in the OCI Console, follow these steps.

1. Open the navigation menu, select Identity, and then select > Dynamic Groups.

2. Click Create Dynamic Group.

3. Provide a name and a short description.

4. In the Matching Rules section, write the following rule. Change > instance-OCID to the OCID of your instance.
   
   All {instance.id = 'instance-OCID'}
   
   
   
   Figure 3: Create a Dynamic Group

5. Click Create.

Write Policies for Dynamic Groups

After you create a dynamic group, you need to create policies to permit the dynamic group to access OCI services.

Here’s an example policy that allows a dynamic group (OracleDev) to manage all resources in the tenancy:

Allow dynamic-group OracleDev to manage all-resources in tenancy

You can also choose to specify a particular resource access for this dynamic group, such as Object Storage in a given compartment:

Allow dynamic-group OracleDev to manage object-family in compartment Dev

Install and Configure the OCI CLI

The Oracle Cloud Infrastructure CLI is a tool that you can use on its own or with Cloud Shell to complete OCI tasks. The CLI provides the same core functionality as the Console, plus additional commands.

The CLI is built on the Oracle Cloud Infrastructure SDK for Python and runs on Mac, Windows, or Linux. The Python code makes calls to OCI APIs to provide the functionality implemented for the various services. These are REST APIs that use HTTPS requests and responses.

In this step, you install the CLI onto the instance that you created in the previous step. The installer script automatically installs the CLI and its dependencies, Python and virtualenv. Before running the installer, ensure that you meet the requirements.

chmod 400 <path-of-the-private-ssh-key>
ssh -i <path-of-the-private-ssh-key> opc@<Public-IP-Address>

Note: Oracle Autonomous Linux 7 and Cloud Shell have the CLI preinstalled.

To install the CLI on Linux and UNIX (including Oracle Linux 8), following these steps:

1. From your local development environment, fix the permission of the private key that you downloaded from the Console (it has wide-open permission) and then run SSH to connect to the OCI instance by using the private key and the IP address of the VM that you created earlier:
    

   Note: opc is the user that is added to every Oracle Linux image that you deploy on OCI.

   
    
2. Run the installer script:
   
   bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"
3. Accept all defaults by pressing Enter.
4. After the CLI is installed, run the following command to check the version.
   
   oci -v

Create an Object Storage Bucket Using OCI CLI and Instance Principal Authentication

To enable instance principal authorization from the CLI, you can set the authorization option (--auth) for a command. For example:

oci os ns get --auth instance_principal

This command shows the Object Storage namespace, which is your tenancy name.

Alternatively, you can set the following environment variable:

export OCI_CLI_AUTH=instance_principal

To create an OCI Object Storage bucket, run the following command:

oci os bucket create --name ocidevbucket --compartment-id <compartment-OCID>

Change compartment-OCID to the compartment in which you deployed the instance.

Conclusion

This blog post gave you a short overview of how to use a dynamic group to create a group of instances and then give them permission to send authenticated calls to the OCI API or CLI without any configuration files. This post briefly discussed dynamic groups, matching rules, and IAM policies. To learn more, see this article.

Resources

• Creating an Instance
• Managing Dynamic Groups
• How Policies Work
• Command Line Interface

Oracle Cloud Infrastructure provides Enterprise features for developers to build modern cloud applications. Try the Oracle Cloud Free Tier with 300$ credits for a 30 Day Free Trial. Free Tier also includes a number of “Always Free” services that are available for an unlimited period of time even after your free credits expire.