Use Resource Principal to Access Oracle Cloud Infrastructure Resources

You can use an Oracle Cloud Infrastructure resource principal with Autonomous Database. 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.

About Using Resource Principal to Access Oracle Cloud Infrastructure Resources
You can use a resource principal to authenticate and access Oracle Cloud Infrastructure resources.
Perform Prerequisites to Use Resource Principal with Autonomous Database
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.
Enable Resource Principal to Access Oracle Cloud Infrastructure Resources
Perform the following steps to enable resource principal on Autonomous Database.
Disable Resource Principal on Autonomous Database
Shows the steps to disable resource principal for all Autonomous Database users or for a specified user.
Use Resource Principal with DBMS_CLOUD
When you specify a resource principal credentials in DBMS_CLOUD calls, the database authenticates the Oracle Cloud Infrastructure requests for you and the database provides the credentials to access to the resources.

Parent topic: Configure Policies and Roles to Access Resources

About Using Resource Principal to Access Oracle Cloud Infrastructure Resources

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.

Parent topic: Use Resource Principal to Access Oracle Cloud Infrastructure Resources

Perform Prerequisites to Use Resource Principal with Autonomous Database

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.

Perform the following steps before you use a resource principal with Autonomous Database:

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>'
```
- 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>'}
```
- 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>'}
```
See Managing Dynamic Groups for more information on creating a dynamic group and creating rules to add resources to the group.
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
```
4. Click Create.
  
  See Managing Policies for more information on policies.

Note:

The resource principal token is cached for two hours. Therefore, if you change the policy or the dynamic group, you have to wait for two hours to see the effect of your changes.

Parent topic: Use Resource Principal to Access Oracle Cloud Infrastructure Resources

Enable Resource Principal to Access Oracle Cloud Infrastructure Resources

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

As a prerequisite, configure dynamic groups and policies. See Perform Prerequisites to Use Resource Principal with Autonomous Database for more information.

To enable a resource principal on Autonomous Database:

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.
(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.

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';

GRANTEE   TABLE_NAME GRANTOR
--------- -------------------------------------
ADB_USER  OCI$RESOURCE_PRINCIPAL ADMIN

Enabling the resource principal on an Autonomous Database instance is one-time operation. You do not need to enable the resource principal again, unless you run DBMS_CLOUD_ADMIN.DISABLE_RESOURCE_PRINCIPAL to disable the resource principal.

Parent topic: Use Resource Principal to Access Oracle Cloud Infrastructure Resources

Disable Resource Principal on Autonomous Database

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

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.

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

To remove access to the resource principal credential for a specified database user, include the username parameter. This denies the specified user access to the OCI$RESOURCE_PRINCIPAL credential.

For example:

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

See DISABLE_RESOURCE_PRINCIPAL Procedure for more information.

Parent topic: Use Resource Principal to Access Oracle Cloud Infrastructure Resources

Use Resource Principal with DBMS_CLOUD

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

If you have not already done so, perform the required prerequisite steps:

Access to Oracle Cloud Infrastructure resources depends on the dynamic group rules and the policies you set in Oracle Cloud Infrastructure policies and dynamic groups. See Perform Prerequisites to Use Resource Principal with Autonomous Database for more information.
After you define the dynamic group and policies, enable the ADMIN schema or another schema to use a resource principal. See Enable Resource Principal to Access Oracle Cloud Infrastructure Resources for more information.

To use a DBMS_CLOUD procedure with resource principal credentials:

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

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

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;
/

If you compare the steps required to access Object Storage as shown in Create Credentials and Copy Data into an Existing Table, notice that Step 1, creating credentials is not required when you use resource principal because you are using the system defined OCI$RESOURCE_PRINCIPAL credentials.

Parent topic: Use Resource Principal to Access Oracle Cloud Infrastructure Resources