Oracle Cloud Infrastructure Documentation

Calling Services from an Instance

This topic describes how you can authorize instances to call services in Oracle Cloud Infrastructure.

Introduction

This procedure describes how you can authorize an instance to make API calls in Oracle Cloud Infrastructure services. After you set up the required resources and policies, an application running on an instance can call Oracle Cloud Infrastructure public services, removing the need to configure user credentials or a configuration file.

Concepts

Dynamic Group
Dynamic groups allow you to group Oracle Cloud Infrastructure instances as principal actors, similar to user groups. You can then create policies to permit instances in these groups to make API calls against Oracle Cloud Infrastructure services. Membership in the group is determined by a set of criteria you define, called matching rules.
Matching Rule
When you set up a dynamic group, you also define the rules for membership in the group. Resources that match the rule criteria are members of the dynamic group. Matching rules have a specific syntax you follow. See Writing Matching Rules to Define Dynamic Groups.
Instance Principals
The IAM service feature that enables instances to be authorized actors (or principals) to perform actions on service resources. Each compute instance has its own identity, and it authenticates using the certificates that are added to it. These certificates are automatically created, assigned to instances and rotated, preventing the need for you to distribute credentials to your hosts and rotate them.

Services That Support Access by Instances

The following services support access by instances:

  • Compute
  • Block Volume
  • Networking
  • Load Balancing
  • Object Storage
  • File Storage

Security Considerations

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

Process Overview

The following steps summarize the process flow for setting up and using instances as principals. The subsequent sections provide more details.

  1. Create a dynamic group. In the dynamic group definition, you provide the matching rules to specify which instances you want to allow to make API calls against services.

  2. Create a policy granting permissions to the dynamic group to access services in your tenancy (or compartment).

  3. A developer in your organization configures the application built using the Oracle Cloud Infrastructure SDK to authenticate using the instance principals provider. The developer deploys the application and the SDK to all the instances that belong to the dynamic group.

  4. The deployed SDK makes calls to Oracle Cloud Infrastructure APIs as allowed by the policy (without needing to configure API credentials).

  5. For each API call made by an instance, the Audit service logs the event, recording the OCID of the instance as the value of principalId in the event log.

Steps to Enable Instances to Call Services

Perform these tasks to enable an instance to call services:

Create a Dynamic Group and Matching Rules

Write Policies for Dynamic Groups

Configure the SDK, CLI, or Terraform

Creating a Dynamic Group and Matching Rules

See Managing Dynamic Groups.

Writing Policies for Dynamic Groups

After you have created a dynamic group, you need to create policies to permit the dynamic groups to access Oracle Cloud Infrastructure services.

Policy for dynamic groups follows the syntax described in How Policies Work. Review that topic to understand basic policy features.

The syntax to permit a dynamic group access to resources in a compartment is:

Allow dynamic-group <dynamic-group_name> to <verb> <resource-type> in compartment <compartment_name>

The syntax to permit a dynamic group access to a tenancy is:

Allow dynamic-group <dynamic-group_name> to <verb> <resource-type> in tenancy

Here are a few example policies:

To allow a dynamic group (FrontEnd) to use a load balancer in a specific compartment (ProjectA):

Allow dynamic-group FrontEnd to use load-balancers in compartment ProjectA

To allow a dynamic group to launch instances in a specific compartment:

Allow dynamic-group FrontEnd to manage instance-family in compartment ProjectA
Allow dynamic-group FrontEnd to use volume-family in compartment ProjectA
Allow dynamic-group FrontEnd to use virtual-network-family in compartment ProjectA

For more sample policies, see Common Policies.

Configuring the SDK, CLI, or Terraform

For information about SDKs, see Software Development Kits and Command Line Interface.

For the Java SDK:

In your Java SDK, create an InstancePrincipalsAuthenticationDetailsProvider object. For example:

public static void main(String[] args) throws Exception {

   InstancePrincipalsAuthenticationDetailsProvider provider =

      InstancePrincipalsAuthenticationDetailsProvider.builder().build();

   IdentityClient identityClient = new IdentityClient(provider);

...

For the Python SDK:

In your Python SDK, create an oci.auth.signers.InstancePrincipalsSecurityTokenSigner object. For example:

# By default this will hit the auth service in the region returned by http://169.254.169.254/opc/v1/instance/region on the instance.
			
signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()
identity_client = oci.identity.IdentityClient(config={}, signer=signer)

...

To refresh the token without waiting, use the following command:

signer.refresh_security_token()

Enabling Instance Principal Authorization for the CLI

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

Alternatively, you can set the following environment variable:

OCI_CLI_AUTH=instance_principal

Note that if both are set, the value set for --auth takes precedence over the environment variable.

For information about using the CLI, see Getting Started with the Command Line Interface.

Enabling Instance Principal Authorization for Terraform

To enable instance principal authorization in Terraform, you can set the auth attribute to "InstancePrincipal" in the provider definition as shown in the following sample:

variable "region" {}

provider "oci" {
   auth = "InstancePrincipal"  
   region = "${var.region}"

}

Note that when you use instance principal authorization you do not need to include the tenancy_ocid, user_ocid, fingerprint, and private_key_path attributes.

FAQs

How do I query the instance metadata service to query the certificate on the instance?
How frequently is the certificate rotated on each instance?
What happens if I try to use an expired certificate?
Can I change the frequency at which the certificate is rotated?
What happens if the certificate is rotated in the middle of a long running operation?
Are the certificates accessible for all users on an instance?
Can I remove an instance from a dynamic group?
Can I exclude specific instances in a compartment from the dynamic group?