Accessing Oracle Cloud Infrastructure Resources from Your Autonomous Database using Resource Principal

May 13, 2021 | 4 minute read
Can Tuzla
Principal Product Manager
Text Size 100%:

As we covered in a previous blog post, Autonomous Database on Shared Infrastructure (ADB-S) users often interact with other Oracle Cloud Infrastructure (OCI) resources to perform various common operations such as loading data from the Object Storage or creating an external table. The main goal of that blog post was to explain and demonstrate the available methods to create a credential object which is a requirement for ADB-S to access Object Storage. Using an auth token or OCI native authentication is still fully supported and if you’d like to learn more about them, you might want to take a look here. However, in this blog post we are going to be talking about a new concept that makes things a bit more interesting and easier, called OCI resource principal!

I’m excited to announce that ADB-S now supports OCI resource principal authentication. What does this mean for you? Let’s first start with understanding what a resource principal is. OCI resource principal is principal type in Oracle Identity and Access Management (IAM) that eliminates the need to create and configure OCI user credential objects in the database. In other words, a resource principle uses a certificate that is frequently refreshed to sign the API calls to certain OCI services (e.g. Object Storage, Vault) and the authorization is established through dynamic groups and IAM policies. A dynamic group is a logical group of OCI resources that you create while a policy is a statement (or list of statements) that specifies who can access which OCI resources that you have. If you’d like to learn more about dynamic groups, policies, or IAM in general, you can check out the documentation

Let’s get started with the fun part… a quick demo! In the remainder of this blog post, I’m going to demonstrate how to load data into my ADB-S instance from Object Storage using OCI resource principle. Here’re the steps that we are going to follow:

  • Create a dynamic group and a policy
  • Enable resource principal in ADB-S
  • Load data from Object Storage using resource principal

Create a dynamic group and policy

As we covered earlier, we need to first create a dynamic group and a policy to be able to use resource principal authentication. This is basically how we will be able tell IAM that a given Autonomous Database should be able to read from the Object Storage buckets and objects that are in a given compartment.

  • In the OCI console, go to ‘Identity and Security’ -> ‘Dynamic Groups’ -> ‘Create Dynamic Group
  • Since I want to include only my ADB-S instance to this dynamic group, I need to add the OCID of my instance in the following rule: = 'ocid1.autonomousdatabase.oc1.iad.osbgdthsnmakytsbnjpq7n37q'

Here's how my dynamic group looks after creation:

Please note that you can add multiple resources in your dynamic groups (e.g. all Autonomous Databases in the tenancy or in a given compartment). You can check out our documentation here for other examples.

Now that we have created a dynamic group that includes our ADB-S instance, we can go ahead and create a policy to allow this resource to access our Object Storage bucket that resides in a given compartment.

  • In the OCI console, go to ‘Identity and Security’ -> ‘Policies’-> ‘Create Policy
  • Add your policy statement in plain text or use the Policy Builder.
    	Allow dynamic-group ctuzlaDynamicGroup to read buckets in compartment ctuzlaRPcomp
    	Allow dynamic-group ctuzlaDynamicGroup to read objects in compartment ctuzlaRPcomp

Please note that my policy only allows read access to the Object Storage buckets and and objects that I specified. It’s also possible to allow higher levels of access as described in the documentation.

Enable resource principal in ADB-S

Resource principal is not enabled by default in ADB-S. In order to be able to use resource principal in our ADB-S instance, we need to enable it using the DBMS_CLOUD_ADMIN.ENABLE_RESOURCE_PRINCIPAL procedure:

  • As ADMIN user, execute the following statement:
    PL/SQL procedure successfully completed.
  • Verify that resource principle is enabled as follows:
    SELECT owner, credential_name 
    FROM   dba_credentials 
    WHERE credential_name = 'OCI$RESOURCE_PRINCIPAL' AND owner = 'ADMIN'; 
    -----  ----------------------
  • The first step above enables resource principle authentication for ADMIN user. If you’d like other database users to call DBMS_CLOUD APIs using resource principal, ADMIN user can enable resource principle authentication for other database users as well:
    PL/SQL procedure successfully completed.

Load data from Object Storage using resource principal

As the final step of our demonstration, let’s create a table and load data from our Object Storage bucket:
  (channel_id CHAR(1),
   channel_desc VARCHAR2(20),
   channel_class VARCHAR2(20)

Table CHANNELS created.

    table_name =>'CHANNELS',
    credential_name =>'OCI$RESOURCE_PRINCIPAL',
    file_uri_list =>'',
    format => json_object('ignoremissingcolumns' value 'true', 'removequotes' value 'true')

PL/SQL procedure successfully completed. 

As you might have noticed, OCI$RESOURCE_PRINCIPLE is the credential_name we need to specify in DBMS_CLOUD APIs whenever we want to use resource principal authentication.

To summarize, resource principal is a really neat Oracle IAM capability that enables your OCI resources to access various OCI services through dynamic groups and policies. Creating dynamic groups and policies can potentially be a one-time operation since you can define your dynamic group such that it includes all existing and future ADB-S instances in a given compartment. Whenever you provision a new ADB-S instance, all you have to do would be to enable resource principle for that instance via the DBMS_CLOUD_ADMIN API if the instance needs to access other OCI services or resources. Much simpler and easier than creating credential objects via auth tokens or OCI native authentication!

Can Tuzla

Principal Product Manager

Can is a Principal Product Manager for Oracle Autonomous Database (ADB-S) and has been with the company since 2014. Prior to joining the ADB-S team, he worked on the Oracle Multitenant and Oracle Query Optimizer teams. Can holds a MS (Computer Science) from Case Western Reserve University and a BS (Computer Engineering) from Bilkent University.

Previous Post

Autonomous Database Newsletter - April 27, 2021

Keith Laker | 8 min read

Next Post

Cross-Region Autonomous Data Guard - Your complete Autonomous Database disaster recovery solution!

Nilay Panchal | 3 min read
Everything you need to know about data warehousing with the world's leading cloud solution provider