Oracle Kubernetes Engine (OKE) and Autonomous Database (ADB) are widely used services for building modern cloud-native applications. A common need is connecting workloads in OKE to data in ADB securely, without hardcoding credentials. OCI IAM enables token-based authentication, allowing OKE workloads to connect to ADB without storing usernames and passwords.

This post explains how OKE Workload Identity authentication works with IAM, what makes it unique, and how you can configure it step by step.

Why IAM-based Authentication?

Traditionally, database clients rely on usernames and passwords. But this model doesn’t scale well in cloud-native environments. Instead, with IAM you can:

  • Eliminate password management.
  • Bind cloud identities (instances, workloads or namespaces) to DB users.
  • Control access using IAM groups and policies.
  • Ensure identities are short-lived, token-based, and auditable.

OKE Workload Identity Authentication Flow

An OKE Workload Identity behaves much like an instance, but with one key difference: OKE does not publish a Workload Identity OCID directly. Instead, the OCID is included in a database token (db-token). You must generate and decode the token to retrieve the OCID and map it to a database user.

Here’s the sequence:

Step 1 : Create a Dynamic Group (name like WorkloadGroup) that allows Kubernetes workloads to request database tokens 

            ALL { resource.type = 'workload' }

This rule captures all OKE workloads running in the tenancy. If you want to narrow the scope, you can match by cluster or a specific workload identity OCID.

          ALL { resource.id= 'ocid1.workload_Identity_OCID' }

Step 2 : Grant Permissions with a IAM policy

           allow dynamic-group WorkloadGroup to use database-tools-family in tenancy 
allow dynamic-group WorkloadGroup to {db_connect} in tenancy

Step 3: Generate DB Token

To generate a database token from a pod in OKE using the OCI CLI, simply invoke the command that requests a db-token for your cluster or workload. The typical command from the pod CLI is

           oci iam db-token get --auth oke_workload_identity --region "us-ashburn-1"

This command requests a short-lived OCI IAM db-token tied to the Workload Identity and can be used with Autonomous Database for secure authentication. 

Step 4 : Fetch the Workload Identity OCID

DB Token Issuance

  • When a pod in a namespace requests a DB token, IAM issues a JWT (JSON Web Token).
  • This JWT contains claims about the identity and context.

Workload Identity OCID in the Token

  • The JWT includes the Workload Identity OCID in the sub claim.
  • By decoding the JWT, you can extract this OCID value.

Step 5: Create a Database User Mapped to the Workload Identity

In your Autonomous Database, create a user that maps directly to the Workload Identity OCID:

CREATE USER ns_user IDENTIFIED GLOBALLY AS 'IAM_PRINCIPAL_OCID=ocid1.workload.oc1.sjc.ctlk4lwchmq.mdaw...';
  • This command creates a database user ns_user and ties it directly to the Workload Identity OCID.
  • The mapping ensures that when IAM issues tokens for workloads in this Workload Identity, they can authenticate as ns_user.

After creating the user, you must grant the required database permissions. For example:

GRANT CREATE SESSION TO ns_user;
GRANT SELECT, INSERT, UPDATE, DELETE ON my_schema.my_table TO ns_user;
  • CREATE SESSION is mandatory so the user can log in.
  • Additional privileges depend on what the Workload need (schema access, role grants, etc.).

Step 6 : Runtime Authentication:

At runtime:

  • Pods in the namespace (tied to Workload Identity) request db-tokens.
  • They connect to ADB using these tokens with supported clients (SQL*Plus, SQLcl, etc.).
  • ADB checks the OCID against the mapped database user.
  • If a match exists, the user (ns_user) is authenticated and granted access.

Important Considerations

  • Workload Identity OCID Stability: The OCID is stable across restarts, but it changes if you modify the cluster ID, namespace name or service account. If it changes, you must update the ADB user mapping.
  • Granular Access Control: You can create different DB users for different namespaces, enabling fine-grained access control.

Conclusion

OCI IAM makes OKE Workload Identity first class principals for Autonomous Database access. By mapping Workload Identity OCIDs to database users, you remove embedded secrets, scale securely with Kubernetes workloads and keep IAM policies at the center of access governance.

This approach:

  • Strengthens security by eliminating static passwords.
  • Scales naturally with containerized workloads.
  • Provides centralized, auditable access control.

Additional Resources