Instance Principal is the capability in the Oracle Cloud Infrastructure Identity and Access Management (IAM) service that allows you to make service calls from an instance. With instance principals, you no longer need to configure user credentials on the services running on your compute instances or rotate the 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 principal’s capability.
You use instance principals to authorize an instance to make API/CLI 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. You can read more details about calling services from an instance here.
To use instance principals, you need to create a dynamic group and policy as given below.
Dynamic Groups use rules to define which instances are members of the group. The matching rule can be a simple rule where you provide the OCID of the compute instance that is used for CLI. There is a Rule Builder that you can use from the OCI console to make the rule. To create a dynamic group using OCI console the documentation is given here.
To create a dynamic group, do the following:
If you are not sure how to define the rule you can use the Rule Builder to help you build the rule. Click the Rule Builder button. Enter the criteria for your rule. In this blog, I am using a very simple rule, where I specify the OCID of the compute VM where I will run the OCI CLI scripts.
Enter the matching rule and hit Add Rule button. In the Create Dynamic Group screen click Create button.
Once you have created the dynamic group, you need to create a policy that gives your group the privilege to stop, start, and update autonomous databases. Your group should have permission to manage autonomous-database-family. The documentation for writing policies is given here.
To create a policy do the following:
Allow dynamic-group to manage autonomous-database-family in compartment < name of compartment > |
Click Create button to create the policy.
Once you have created the Dynamic Group, the Matching Rule, and the Policy you are ready to use Instance Principals for authorizing OCI CLI calls. To enable Instance Principal authorization from the CLI, you can use the authorization option (--auth) for a command. For example:
oci ns get --auth instance_principal |
Alternatively, you can set OCI_CLI_AUTH 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 example, you can use the following OCI CLI command to start an ATP Database that uses Instance Principal for authorization.
oci db autonomous-database start –autonomous-database-id < adb OCID > --auth instance_principal |
For more information about working with the CLI, click here.