Introduction

OCI Workload Identity Federation (WIF) enables external workloads to securely exchange third-party OpenID Connect (OIDC) tokens (in the form of JSON Web Tokens) for OCI Security Tokens, which are short-lived. This approach preserves the workload’s existing identity context while enabling secure access to OCI APIs while eliminating the need for static credentials or identity duplication.

If you’re new to WIF, check out:  Workload Identity Federation

Implementing WIF involves two broad stages:

A. Preparing for Identity Propagation Trust in OCI

  1. Create a Service User (for user impersonation) – Represents the federated workload in OCI.
  2. Create a Token Exchange OAuth Client (Confidential Application)– Used by the workload to request a token exchange
  3. Configure Identity Propagation Trust – Establishes trust between OCI IAM and the external identity provider (for example, GitHub or Azure AD)

These steps can be automated using Terraform and Resource Manager, as explained in this blog.

B. Token Exchange (Client Side)

  1. Generate an RSA key pair.
  2. Call the token exchange endpoint, passing:
    • The JWT from your third-party identity provider (IDP).
    • The public key from the generated key pair.
    • Client ID and client Secret 
  3. OCI IAM validates the request and responds with a OCI security Token.
  4.  The OCI security Token must then be signed using the private key as proof of possession before you can invoke OCI APIs.

Manually implementing these steps can be cumbersome — which is where the Python WIF Signer simplifies things

The OCI Python SDK provides a ready-to-use helper — the Python WIF Signer— which automates:

  • RSA key generation
  • Token exchange (3rd party JWT → OCI Secuity Token)
  • Signing the Security Token with the private key for proof of possession

You simply provide:

  • JWT from your 3rd party IDP or a callable function that fetches the JWT from your third-party IdP
  • Your OCI domain ID
  • The OAuth Client ID and Client Secret (created earlier)

Example: Using the Workload Identity Federation Signer

Let’s walk through a simple example that uses the OCI Secrets service. We’ll authenticate using WIF signer and then retrieve a secret’s value.

Step 1 – Create the Token Exchange Signer

signer = oci.auth.signers.TokenExchangeSigner(
jwt,                # JWT from third-party IDP or a callable function that fetches the JWT from your third-party IDP
oci_domain_id,      # OCI IAM Domain ID
oci_client_id,      # Token Exchange OAuth Client ID
oci_client_secret   # Token Exchange OAuth Client Secret)

Step 2 – Create a Client Using the Signer

Once the signer is created, you can attach it to any OCI SDK client.In this example, we use the SecretsClient to retrieve a secret from OCI Vault.

secrets_client = oci.secrets.SecretsClient(
    config={"region": region},
    signer=signer
)

Step 3 – Retrieve a Secret.

To fetch a secret, you need its resource OCID (the OCID of the secret in OCI Vault).

response = secrets_client.get_secret_bundle(resource_ocid)
base64_content = response.data.secret_bundle_content.content

decoded_content = base64.b64decode(base64_content).decode("utf-8")
print(f"Resource value (decoded): {decoded_content}", flush=True)

That’s it — you’ve securely accessed OCI APIs using WIF without any long-lived credentials.

Handling Token Expiration and Automatic Refresh

By design, the duration of a OCI Security Token is determined by the minimum of:

  • The remaining lifetime of the IDP-issued JWT.
  • The duration specified in the token exchange request.
  • 60 minutes (the service-imposed maximum).

If your workload runs longer, you must refresh the token manually — unless you use the TokenExchangeSigner.

The WIF Python signer automatically refreshes the OCI security Token before it expires, as long as the third-party JWT remains valid. This makes it ideal for long-running jobs (for example, pipelines or background tasks).

Demonstrating Token Auto-Refresh

The following example retrieves a secret multiple times, pausing for about an hour between calls to simulate a long-running workload. The signer automatically refreshes the OCI Security Token behind the scenes — you don’t need to handle any of that logic manually.

for i in range(10):
    try:
        response = secrets_client.get_secret_bundle(resource_ocid)
        base64_content = response.data.secret_bundle_content.content

        decoded_content = base64.b64decode(base64_content).decode("utf-8")
        print(f"Resource value (decoded): {decoded_content}", flush=True)

    except Exception as e:
        print(f"Error reading resource {resource_ocid}: {e}", flush=True)

    if i < 9:
        time.sleep(3700)  # 61 minutes

Each call succeeds because the signer seamlessly handles token renewal. For a condensed, working example, see the OCI Python SDK GitHub repository.

Summary

Using the OCI Python Workload identity federation Signer, workloads can:

  •  Authenticate securely with OCI using short-lived tokens.
  •  Eliminate the need for storing long-term credentials.
  • Automatically refresh tokens without manual intervention.

This signer is particularly useful for CI/CD systems, serverless environments, and cloud workloads that rely on external identity providers like GitHub Actions or Azure AD.