Give Oracle Database access to OCI with Database Tools Identity

You can use a Database Tools identity in Oracle Cloud Infrastructure (OCI) to give Oracle Databases access to OCI resources through something called a "resource principal". There are a few configuration requirements and the use case is interesting in general, so let's check it out!

Why use an identity?

Database Tools identities offer schema-level definitions of OCI native credentials that can be used to call OCI services using a distinct resource principal. This means you get fine-grained access control without needing to upload developer or user-specific private keys to a database credential.

Identities fit somewhere in-between the higher level ADB resource principal and the current user-specific credentials with a few added benefits that we will cover below.

Example of the benefit of Database Tools identity schema-level credentials.

It is interesting to note that creating an OCI native database credential has been supported in the Oracle Database for quite some time. For example:

Autonomous Database in OCI and has a resource principal credential called OCI$RESOURCE_PRINCIPAL, and if you have used it to make calls to OCI then you have already used a database credential.
If you have created an OCI native credential using DBMS_CLOUD by setting a user, private key, tenancy, etc. then you have already seen credentials.

With these existing solutions you may wonder why we need to use identities. The answer to that question lies in that middle ground, somewhere between either of the above two existing solutions.

At a high level:

Identities are associated with credentials owned by individual schemas within a database. This is slightly more fine-grained than the existing ADB resource principal because each identity resource principal can have a different set of IAM policies. With this setup, Finance schemas could have a different resource principal and different policies granting access to sensitive resources, versus say, HR- or IT-owned resources.
Identities support OCI native credentials for both Autonomous Database (ADB) and Oracle Base Database (i.e. VMDB systems). This one is actually a pretty big deal!
Developer private keys associated with an OCI user are often long-lived and have certain trade-offs when used in production applications. Identities do not require an individual developer to upload private keys or update them when they expire or become obsolete. The identity resource manages a credential that is automatically refreshed securely, multiple times per day.
Identity resources are first-class citizens and have support for the OCI Terraform provider, CLI, and SDK. This means you can automate the creation and removal of identities along with the rest of your infrastructure.

The rest of this post assumes you want to understand how to use DBMS_CLOUD and similar packages with Oracle Database to make calls to OCI services in the cloud. Database Tools identities open several possibilities for your databases talking to OCI.

💡

Note, as of the time of this writing, identities are only supported for Oracle Databases with a minimum version of DBMS_CLOUD installed and configured to allow communication with OCI endpoints. It is also not possible to use Database Tools identities with other databases such as MySQL.

If you want to skip the rest of this post and go straight to the manual, you can find the documentation here for more details.

More About Database Tools Identity

A Database Tools identity is a new type of OCI resource principal managed by the Database Tools service. Identities are built to work in conjunction with Database Tools connection resources, which also received an update as part of this release.

💡

You will need to create a new type of connection that also uses resource principals as the "runtime identity" type. See below for more details.

Let's take a look at how identities are set up.

Database Tools Identity circa 2025

Starting at the top we can see an identity (1) is created that points to a connection resource (2) which describes how to connect to an Oracle Database. Once the identity is configured the magic starts to happen. In concrete terms, a new database credential is created owned by the specified schema in an Oracle Database (3).

Here is the gist of it: an identity uses a connection to talk to an Oracle Database to manage a database credential.

💡

If you are not familiar with Database Tools connections, I have written other posts you can find on this blog. I won't cover connections in this post except where it clarifies what is new and required to make identities work!

When you create a connection for this use case, you must configure the runtime identity to be Resource Principal instead of the default (authenticated principal.) What I show below is not the entire connection creation flow, but it is the most important part for a connection that will support identities.

Example creating a connection and selecting advanced options -> runtime identity.

Your new connection will itself be a resource principal and is required to grant the connection access to the secrets in a vault to support credential refreshes. I'll cover more on connection resource principals in a future post. For now, we just need to know that we will need a resource principal connection and IAM policies to make identities work.

Once your connection is created you should see something similar to the following on the connection details page for your new connection.

Example connection details showing runtime identity of type "Resource Principal"

After you create a resource principal connection you need to grant the connection resource principal access to read secrets in the vault. This is done by adding an IAM policy statement similar to the following:

allow any-user to read secret-family in compartment <your-compartment> where any { request.principal.id = 'ocid1.databasetoolsconnection.oc1.phx.aaaaaabbbbccccdddddexample' }

Example IAM policy statement for connection resource principal access to secrets in vault.

💡

Instead of specifying the OCID of a connection in the policy, you can also create a dynamic group in IAM and grant the dynamic group access to the secrets. Each approach has pros and cons. I will leave that as an exercise. You can find an example policy using dynamic groups in the updated Database Tools documentation.

Creating an Identity

Finally! Once you have a resource principal-based connection with a proper policy in place, you can create an identity from the new "Identities" tab.

Example of the new "Identities" tab for resource principal-based connections.

Pressing the "Create identity" button will present a form that asks you for a few pieces of information to configure the identity. Most notable here is the name of the database credential that will be created within the schema.

Example of creating an Identity with a database credential called "DEMOCRED".

By principle of least privilege, you need to grant the identity resource principal access to OCI resources before you can use it. Once again, you could choose to use dynamic groups, see the identity documentation, but in this example I reference the resource OCID in a request principal filter.

allow any-user to read object-family in compartment <your-compartment> where any { request.principal.id = 'ocid1.databasetoolsidentity.oc1.phx.aaaaaabbbbccccdddddexample' }

Example IAM policy granting an identity access to use object storage in a compartment.

Notice that the new entity type in the OCID is databasetoolsidentity in this policy.

Once created, you can check the database credential associated with the identity exists in the target schema by switching to the SQL Worksheet for the connection and querying all_credentials. Here is an example:

Example showing credentials in an Oracle Database by selecting from all_credentials.

In the example above you can see DEMOCRED which is the name of the credential I defined when I created the Database Tools identity. We also include a new "Credentials" tab under resource principal connections that you can use to verify the same.

Now what?

Given a Database Tools identity-managed credential, here is how you use it:

Example calling OCI services from an Oracle Database using a credential.

In the above example the Oracle Database uses the OCI native credential (1) by passing it to DBMS_CLOUD. The credential is typically referenced as credential_name. A request is signed using the identity resource principal (2) and the request is processed by OCI services to grant access to resources that exist in a tenancy (3).

Here I show an example of using a database credential (DEMOCRED in this case) to call OCI and load a file from object storage into a table:

Example using OCI native credentials to load data from object storage into a table.

There is nothing technically new in this example. Using credentials to call OCI was already possible. If you had an OCI native credential before, you could do the exact same with OCI$RESOURCE_PRINCIPAL or a user-specific credential.

DBMS_CLOUD.COPY_DATA is not the only way to use OCI credentials. You will find most OCI services have PL/SQL packages that you can use to interact with your resources. You can also skip the packages (if you prefer) and call OCI directly using SEND_REQUEST. Here is some documentation for more details.

In future posts I'll look at other features of Database Tools identity such as OCI CLI integration, infrastructure as code (via Terraform), database credential sharing, identity metrics, work requests, validation, and also how to fix problems that may come up. I hope this overview of the new Database Tools identity resource and related credential was helpful.

Thanks for reading and I will see you next time.

Cheers!