You can use a resource principal to authenticate and access Oracle Cloud Infrastructure resources.

A resource principal consists of a temporary session token and secure credentials that enable the database to authenticate itself to other Oracle Cloud Infrastructure services. Using a resource principal to access services, the token stored with the credentials on Autonomous Database is only valid for the resources to which the dynamic group has been granted access.

To use Resource Principal, you or your tenancy administrator define the Oracle Cloud Infrastructure policies and a dynamic group that allows you to access Oracle Cloud Infrastructure resources with a resource principal. You do not need to create a credential object and Autonomous Database creates and secures the resource principal credentials you use to access the specified Oracle Cloud Infrastructure resources.

For example, while using Autonomous Database you might want to use Oracle Cloud Infrastructure resources to do the following:

• Access data from an Object Storage bucket, perform some operation on the data, and then write the modified data back to the Object Storage bucket.

• Access your vaults, keys, or secrets.

• List work requests or list work request errors.

When you are working with the database, you authenticate and access the database as a database user. An Autonomous Database user does not have an Oracle Cloud Infrastructure Identity and Access Management (IAM) identity, so as an Autonomous Database user you cannot use your database credentials to access Oracle Cloud Infrastructure services. Without a resource principal you must obtain credentials to access Oracle Cloud Infrastructure resources and create a credential object to access a resource from Autonomous Database.

A resource principal enables resources to be authorized to perform actions on Oracle Cloud Infrastructure services. Each resource has its own identity, and the resource authenticates using the certificates that are added to it. These certificates are automatically created, assigned to resources, and rotated, avoiding the need for you to create and manage your own credentials to access the resource.

Autonomous Database lets you use a resource principal to authenticate to Oracle Cloud Infrastructure APIs using the following interfaces:

• DBMS_CLOUD procedures and functions that take a credential argument
• Oracle Cloud Infrastructure PL/SQL SDK APIs

When you authenticate using a resource principal, Autonomous Database provides a secure method to access Oracle Cloud Infrastructure resources.

There are several steps required to set up a resource principal on Autonomous Database:

• You must create an define Oracle Cloud Infrastructure Infrastructure Identity and Access Management (IAM) policies. See Perform Prerequisites to Use Resource Principal with Autonomous Database for more information.

• You must enable the resource principal for the ADMIN user, and optionally enable the resource principal for a database user. See Enable Resource Principal to Access Oracle Cloud Infrastructure Resources for more information.

When you authenticate using a resource principal, you do not need to create and manage credentials to access Oracle Cloud Infrastructure resources. Autonomous Database makes the resource principal available to you and secures the resource principal for you.

Prior to making a call to an Oracle Cloud Infrastructure resource using a resource principal, an Oracle Cloud Infrastructure tenancy administrator must create Oracle Cloud Infrastructure policies, dynamic groups, and rules that define the resource principal privileges.

1. Create an Oracle Cloud Infrastructure dynamic group.
   1. In the Oracle Cloud Infrastructure console click Identity and Security and click Dynamic Groups
   2. Click Create Dynamic Group and enter a Name, a Description, and a rule or use the Rule Builder to add a rule.
   3. Click Create.

   Resources that meet the rule criteria are members of the dynamic group. When you define a rule for a dynamic group, consider what resource is going to be given access to other resources.

   For example, consider the following examples:

   • Allow a specific Autonomous Database instance to access a resource.

     The Autonomous Database is specified in the resource.id parameter with an OCID:

     resource.id = 'your_Autonomous_Database_instance_OCID'

     You need to add a Domain Name when the tenancy uses an Identity Domain. For example:

     resource.id = 'identity_domain_name/your_Autonomous_Database_instance_OCID'

   • Allow all Autonomous Databases in a compartment.

     The Autonomous Databases are specified in the resource.type parameter and the compartment is identified by a specified OCID in the resource.compartment.id parameter:

     ALL {resource.type = 'autonomousdatabase', resource.compartment.id = 'your_Compartment_OCID'}

     You need to add a Domain Name when the tenancy uses an Identity Domain. For example:

     ALL {resource.type = 'autonomousdatabase', resource.compartment.id = 'identity_domain_name/your_Compartment_OCID'}

   • Allow all resources in the compartment

     The resource type identified by the OCID, specified in the resource.compartment.id parameter:

     ALL
             {resource.compartment.id='your_Compartment_OCID'}

     You need to add a Domain Name when the tenancy uses an Identity Domain. For example:

     ALL
             {resource.compartment.id='identity_domain_name/your_Compartment_OCID'}

   See Managing Dynamic Groups for more information on creating a dynamic group and creating rules to add resources to the group.

2. Write policy statements for the dynamic group to enable access to Oracle Cloud Infrastructure resources.
   1. In the Oracle Cloud Infrastructure console click Identity and Security and click Policies.
   2. To write policies for a dynamic group, click Create Policy, and enter a Name and a Description.
   3. Use the Policy Builder to create a policy.

      For example to create a policy to allow access to Oracle Cloud Infrastructure Object Store to manage buckets and objects in the Object Store in a tenancy:

      Allow dynamic-group Example5 to manage buckets in tenancy
      Allow dynamic-group Example5 to manage objects in tenancy

      You need to add a Domain Name when the tenancy uses an Identity Domain. For example:

      Allow dynamic-group identity_domain_name/Example5 to manage buckets in tenancy
      Allow dynamic-group identity_domain_name/Example5 to manage objects in tenancy

   4. Click Create.

Perform the following steps to enable resource principal on Autonomous Database.

1. As the ADMIN user, enable resource principal for the Autonomous Database instance.

   For example:

   EXEC DBMS_CLOUD_ADMIN.ENABLE_RESOURCE_PRINCIPAL();
   
   PL/SQL procedure successfully completed. 
   

   See ENABLE_RESOURCE_PRINCIPAL Procedure for more information.

   This creates the credential OCI$RESOURCE_PRINCIPAL.

2. (Optional) This step is only required if you want to grant access to the resource principal credential to a database user other than the ADMIN user. As the ADMIN user, enable resource principal for a specified database user.

   For example:

   EXEC DBMS_CLOUD_ADMIN.ENABLE_RESOURCE_PRINCIPAL(username => 'adb_user');
   
   PL/SQL procedure successfully completed. 
   

   This grants the user adb_user access to the credential OCI$RESOURCE_PRINCIPAL.

   If you want the specified user to have privileges to enable resource principal for other users, set the grant_option parameter to TRUE.

   For example:

   BEGIN
   DBMS_CLOUD_ADMIN.ENABLE_RESOURCE_PRINCIPAL(
        username => 'adb_user',
        grant_option => TRUE);
   END;
   /

   After you run this command, adb_user can enable resource principal for another user. For example, if you connect as adb_user, you can run the following command:

   EXEC DBMS_CLOUD_ADMIN.ENABLE_RESOURCE_PRINCIPAL(username => 'adb_user2');
   

   See ENABLE_RESOURCE_PRINCIPAL Procedure for more information.
3. Verify that the resource principal credential is enabled.

   For example, as the ADMIN user query the view DBA_CREDENTIALS:

   SELECT owner, credential_name FROM dba_credentials 
           WHERE credential_name = 'OCI$RESOURCE_PRINCIPAL' AND owner = 'ADMIN'; 
   
   OWNER  CREDENTIAL_NAME
   -----  ----------------------
   ADMIN  OCI$RESOURCE_PRINCIPAL 
   

   For example, as a non-ADMIN user query the view ALL_TAB_PRIVS:

   SELECT grantee, table_name, grantor FROM ALL_TAB_PRIVS
           WHERE grantee = 'ADB_USER' AND
                table_name = 'OCI$RESOURCE_PRINCIPAL' AND 
                owner = 'ADMIN';
   
   GRANTEE   TABLE_NAME                GRANTOR
   --------- -----------------------   -------------
   ADB_USER  OCI$RESOURCE_PRINCIPAL    ADMIN

Shows the steps to disable resource principal for all Autonomous Database users or for a specified user.

1. To disable resource principal for all users, as the ADMIN user, run the following command:

   EXEC DBMS_CLOUD_ADMIN.DISABLE_RESOURCE_PRINCIPAL();

   This removes the credential OCI$RESOURCE_PRINCIPAL.

2. Verify that the resource principal credential is disabled.

   For example:

   SELECT owner, credential_name FROM dba_credentials 
           WHERE credential_name = 'OCI$RESOURCE_PRINCIPAL' AND owner = 'ADMIN';
   
   No rows selected
   

EXEC DBMS_CLOUD_ADMIN.DISABLE_RESOURCE_PRINCIPAL(username => 'ADB_USER');

When you specify resource principal credentials with DBMS_CLOUD calls, the database authenticates the Oracle Cloud Infrastructure requests for you and the database provides the credentials to access Oracle Cloud Infrastructure resources.

1. Use a DBMS_CLOUD procedure or function and specify OCI$RESOURCE_PRINCIPAL as the credential name.

   For example, you can access Oracle Cloud Infrastructure Object Storage using a resource principal:

   CREATE TABLE CHANNELS
      (channel_id CHAR(1),
       channel_desc VARCHAR2(20),
       channel_class VARCHAR2(20)
      );
   /
   
   BEGIN
    DBMS_CLOUD.COPY_DATA(
       table_name =>'CHANNELS',
       credential_name =>'OCI$RESOURCE_PRINCIPAL',
       file_uri_list =>'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/channels.txt',
       format => json_object('delimiter' value ',')
    );
   END;
   /