Introduction

Part 1, Passwordless JDBC with OCI IAM Tokens: WebLogic Server and Autonomous Database 26ai, and Part 2, WebLogic Server and Oracle AI Database on OCI, configured passwordless WebLogic JDBC data sources. This article covers the operational part of that design: keeping an OCI IAM database token current, making connection pools recover predictably, and observing the configuration without exposing credentials.

An OCI IAM database token is a short-lived proof-of-possession credential. OCI CLI writes the token and its paired private key to the host. Oracle JDBC Thin reads those files when it creates a physical database connection. WebLogic then lends that physical connection from its JDBC pool to applications.

The operational consequence is important: refreshing the token prepares new physical connections. It does not require application code changes or a data source redeployment. Existing healthy pool connections can continue serving work; a newly created connection uses the current token files.

This article applies to supported WebLogic Server releases with Oracle JDBC Thin 19.16 or later for the file-based TOKEN_AUTH=OCI_TOKEN flow. The examples use a WebLogic Server cluster and OCI CLI running as the oracle operating-system account. When the bundled driver needs an upgrade, apply the latest Oracle JDBC for Fusion Middleware JDBC 23.26.x/19.x Bundle Patch for the corresponding WebLogic Server release. The patch updates the JDBC drivers bundled with WebLogic Server. See (KA1182) Critical Patch Update (CPU) Patch Advisor for Oracle Fusion Middleware to identify the patch for the customer's WebLogic Server release.

In This Series

This is Part 3 of the Passwordless JDBC with OCI IAM Tokens series:

• WebLogic Server and Autonomous Database 26ai (Part 1)
• WebLogic Server and Oracle AI Database on OCI (Part 2)
• Operating OCI IAM Token Authentication for WebLogic JDBC Data Sources (this article)

The database-specific setup differs between Autonomous Database and Base Database Service. The operating model in this article is shared: token generation, protected host storage, renewal, physical-connection recovery, and evidence that the deployed application can still obtain a connection.

Operating Model

Keep the token lifecycle outside the deployed application. Each managed-server host that can create a JDBC connection needs all of the following:

1. OCI CLI and either an IAM user credential configuration or an OCI workload principal for the service identity.
2. A protected token directory containing token and oci_db_key.pem.
3. A scheduler that refreshes the token before its reported expiry time.
4. The TNS alias and trust material used by the data source.
5. WebLogic connection testing and retry settings appropriate for the service.

For a cluster, configure every managed-server host. Targeting a data source to a cluster does not centralize its physical JDBC connections; each server can create its own connections.

1. Establish a Host Credential Boundary

Run OCI CLI and WebLogic under the same dedicated operating-system account. In these examples, that account is oracle. Do not generate the token as root, opc, or an interactive administrator account and then rely on permissive file access for WebLogic to read it.

The IAM-user/API-key approach used in Parts 1 and 2 is practical for a proof of concept. In production, use a deliberately scoped service identity and grant only the database-connection permissions needed by the application. For an IAM group, for example:

Allow group <iam_group_name> to use database-connections in compartment <compartment_name>

The database-side global user mapping determines database privileges. The OCI policy permits the IAM principal to obtain a database connection token; it does not grant SQL privileges by itself.

For the IAM-user/API-key flow, protect the OCI configuration, API signing key, token, and private key. The following permissions give the oracle account exclusive access:

sudo chown -R oracle:oracle /home/oracle/.oci
sudo chmod 700 /home/oracle/.oci /home/oracle/.oci/db-token
sudo chmod 600 /home/oracle/.oci/config
sudo chmod 600 /home/oracle/.oci/<api_key_private_file>
sudo chmod 600 /home/oracle/.oci/db-token/token
sudo chmod 600 /home/oracle/.oci/db-token/oci_db_key.pem

Do not place these files in a domain archive, deployment artifact, source repository, shared filesystem, backup, diagnostic bundle, or support upload.

2. Choose the OCI Principal That Obtains the Token

The database always receives a short-lived db-token. The difference is the OCI identity used to obtain that token. The JDBC URL, TCPS connection, TNS configuration, and WebLogic data source do not change.

IAM user and API key

The flow in Parts 1 and 2 uses an IAM user, an API signing key, and an OCI CLI profile. It is useful for development, for workloads outside OCI, and where an application must act as a specific IAM user. It requires careful protection and rotation of the API signing key.

Instance principal

For WebLogic Server running on OCI Compute instances, an instance principal is often the preferred production option. OCI identifies the Compute instance, so the managed-server host does not need an IAM-user API key or an OCI CLI profile under /home/oracle/.oci.

Create a dynamic group that contains the WebLogic Compute instances and grant it permission to obtain database tokens:

Allow dynamic-group <weblogic_dynamic_group> to use database-connections in compartment <compartment_name>

Map the same dynamic group to a shared database schema:

CREATE USER <application_schema>
  IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=<weblogic_dynamic_group>';

GRANT CREATE SESSION TO <application_schema>;

The refresh command is then:

/home/oracle/bin/oci iam db-token get --auth instance_principal

By default, OCI CLI requests a database token with tenancy scope. If the dynamic-group policy is deliberately limited to the database compartment, pass an explicit matching scope when generating the token:

/home/oracle/bin/oci iam db-token get --auth instance_principal \
  --scope 'urn:oracle:db::id::<database_compartment_ocid>'

This allows the compartment-scoped policy shown above to authorize the request. Without --scope, grant the dynamic group tenancy-wide access instead:

Allow dynamic-group <weblogic_dynamic_group> to use database-connections in tenancy

Prefer the explicit compartment scope when the application only needs to connect to databases in that compartment. Ensure that the dynamic group matches the WebLogic Compute instances, not the database resource.

OCI can also map an individual instance principal exclusively to a database schema using its OCID:

CREATE USER <application_schema>
  IDENTIFIED GLOBALLY AS 'IAM_PRINCIPAL_OCID=<compute_instance_ocid>';

Use this only when a distinct database schema for that individual instance is intended. A shared schema mapped through a dynamic group is generally easier to operate across a WebLogic cluster.

Resource principal

An OCI application that has a resource principal, such as an OCI Function or a workload using a supported OCI resource-principal runtime, can also obtain a database token. Map the resource principal exclusively by OCID or map its dynamic group to a shared database schema using the same patterns above.

For the WebLogic-on-Compute architecture used in this series, an instance principal is the relevant workload-principal option. A resource principal is more appropriate when the application runtime itself, rather than the Compute instance hosting WebLogic, is the OCI identity.

The database system's own resource principal, which it uses to communicate with OCI IAM, is separate from the application principal described here.

For the supported principal mappings and token acquisition methods, see Accessing the Database Using an Instance Principal or a Resource Principal.

3. Make Token Refresh a Host Service

Oracle CLI reports the expiry time whenever it creates a token. Refresh on a regular interval that is comfortably before that time. This example refreshes every 30 minutes and assumes the CLI profile is stored in /home/oracle/.oci/config.

The script below shows the IAM-user/API-key flow used in Parts 1 and 2. For an instance-principal deployment, keep the same scheduler, lock, token directory, and log permissions, but replace the final OCI CLI command with the instance-principal command shown after the script.

Create /home/oracle/bin/refresh-oci-db-token on every managed-server host:

#!/usr/bin/env bash
set -euo pipefail
umask 077

export PATH=/home/oracle/bin:/usr/bin:/bin
export OCI_CLI_CONFIG_FILE=/home/oracle/.oci/config

exec /usr/bin/flock -n /home/oracle/.oci/db-token/.refresh.lock \
  /home/oracle/bin/oci iam db-token get --profile <oci_profile>

For an instance principal, no OCI CLI profile or API signing key is required. Use this final command instead:

exec /usr/bin/flock -n /home/oracle/.oci/db-token/.refresh.lock \
  /home/oracle/bin/oci iam db-token get --auth instance_principal \
  --scope 'urn:oracle:db::id::<database_compartment_ocid>'

Make the script executable and owned by the account that runs WebLogic:

sudo chown oracle:oracle /home/oracle/bin/refresh-oci-db-token
sudo chmod 700 /home/oracle/bin/refresh-oci-db-token

Use a root-managed cron file when the oracle account is not permitted to own a crontab. Create /etc/cron.d/oci-db-token-refresh with this content:

*/30 * * * * oracle /home/oracle/bin/refresh-oci-db-token >> /home/oracle/.oci/db-token/refresh.log 2>&1

Install it and protect the log. The log can contain OCI CLI diagnostics and should not be readable by other accounts:

sudo chown root:root /etc/cron.d/oci-db-token-refresh
sudo chmod 644 /etc/cron.d/oci-db-token-refresh
sudo touch /home/oracle/.oci/db-token/refresh.log
sudo chown oracle:oracle /home/oracle/.oci/db-token/refresh.log
sudo chmod 600 /home/oracle/.oci/db-token/refresh.log

flock ensures a delayed cron invocation cannot overlap a still-running refresh. It exits without changing the token when another invocation holds the lock.

Verify the exact execution context before relying on cron:

sudo -u oracle /bin/bash -lc \
  '/home/oracle/bin/refresh-oci-db-token \
  >> /home/oracle/.oci/db-token/refresh.log 2>&1'

sudo -u oracle tail -n 50 /home/oracle/.oci/db-token/refresh.log
sudo systemctl status crond

OCI CLI output includes the location of the token and private key and the time until which the token is valid. Confirm that those paths match the TOKEN_LOCATION used by JDBC Thin. See Authenticating and Authorizing IAM Users for Oracle AI Database.

4. Keep the JDBC Client Configuration Stable

Use one protected token directory per WebLogic operating-system account. The data source should resolve a TNS alias that identifies that directory. For the file-based flow, put both token properties inside the alias SECURITY section:

<iam_token_alias> =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCPS)(HOST = <database_host>)(PORT = <tcps_port>))
    (CONNECT_DATA = (SERVICE_NAME = <service_name>))
    (SECURITY =
      (WALLET_LOCATION = file:/home/oracle/<trust_wallet>/cwallet.sso)
      (SSL_SERVER_DN_MATCH = YES)
      (SSL_SERVER_CERT_DN = "CN=<database_certificate_common_name>")
      (TOKEN_AUTH = OCI_TOKEN)
      (TOKEN_LOCATION = /home/oracle/.oci/db-token))
  )

Use an unquoted TOKEN_LOCATION directory path. With this JDBC Thin setup, quotation marks become part of the path and prevent the driver from finding token and oci_db_key.pem.

The data source URL contains the alias and no database user name or password:

jdbc:oracle:thin:@<iam_token_alias>

Set oracle.net.tns_admin to the directory containing the exact tnsnames.ora file. Do not rely on a managed server inheriting an interactive shell's TNS_ADMIN value.

5. Tune the WebLogic Data Source for Recovery

Token renewal and connection-pool recovery solve different problems. Token renewal makes a valid credential available for the next physical connection. Connection testing detects a defunct connection before or while it is returned to application code.

Start with explicit, conservative testing settings, then measure their cost at your workload. The following WLST fragment uses Oracle's JDBC ping operation, tests a connection when reserved, periodically tests idle connections, and retries physical connection creation after a transient failure:

connect(os.environ['WLS_USER'], os.environ['WLS_PWD'], '<admin_url>')
edit()
startEdit()

jdbc = getMBean('/JDBCSystemResources/<data_source_name>')
pool = jdbc.getJDBCResource().getJDBCConnectionPoolParams()
pool.setTestTableName('SQL PINGDATABASE')
pool.setTestConnectionsOnReserve(True)
pool.setTestFrequencySeconds(300)
pool.setSecondsToTrustAnIdlePoolConnection(30)
pool.setConnectionCreationRetryFrequencySeconds(30)

save()
activate(block='true')
disconnect()
exit()

Test Connections On Reserve gives the application a usable connection or causes WebLogic to discard and replace a failed one. Test Frequency checks unused pool connections in the background. Seconds To Trust An Idle Pool Connection limits how long a recently used connection can bypass another test. Connection Creation Retry Frequency lets WebLogic retry a physical connection after a database or network interruption.

These are starting values, not universal targets. A high-throughput service may need a longer trust interval to reduce testing overhead; a critical service may choose to test more often. Do not use Inactive Connection Timeout as a substitute for applications closing connections promptly. It is intended to reclaim leaked reserved connections. Oracle documents the testing and retry attributes in JDBC Data Source: Configuration: Connection Pool.

6. Validate the Full Lifecycle

Perform these checks on every managed-server host after initial setup, after an OCI CLI or OS update, and after any change to the OCI profile, token directory, TNS alias, or wallet.

First, confirm the host can issue a fresh token as the WebLogic user:

sudo -u oracle /home/oracle/bin/oci iam db-token get --profile <oci_profile>
sudo -u oracle ls -l /home/oracle/.oci/db-token/token \
  /home/oracle/.oci/db-token/oci_db_key.pem

For an instance-principal deployment, use this command in place of the OCI CLI profile command:

sudo -u oracle /home/oracle/bin/oci iam db-token get --auth instance_principal \
  --scope 'urn:oracle:db::id::<database_compartment_ocid>'

Then validate a connection from the deployed application. A simple endpoint that writes and reads a row through the data source proves the full path:

curl -k -X POST \
  --data-urlencode 'message=OCI IAM token lifecycle check' \
  https://<application_endpoint>/hello-db/hello-db

curl -k https://<application_endpoint>/hello-db/hello-db

From a token-authenticated database connection, confirm the mapped identity:

SELECT
  USER,
  SYS_CONTEXT('USERENV', 'AUTHENTICATED_IDENTITY') AS authenticated_identity,
  SYS_CONTEXT('USERENV', 'AUTHENTICATION_METHOD') AS authentication_method
FROM dual;

Expected values resemble the following:

USER                      <global_database_user>
AUTHENTICATED_IDENTITY    <mapped_iam_identity>
AUTHENTICATION_METHOD     TOKEN_GLOBAL

For a controlled expiry test, use a non-production environment. Temporarily disable the cron file, wait until the token is past the expiry reported by OCI CLI, then force a new physical connection by resetting the test data source or restarting a managed server. The connection attempt should fail. Re-enable the job, refresh the token, and verify a newly created connection succeeds. Do not perform this test against a production pool without a maintenance plan.

7. Monitor the Things That Actually Fail

Monitor each managed-server host, not only the Administration Server. Useful signals include:

• The refresh log has a successful OCI CLI run within the intended interval.
• The token and paired private key exist, retain restrictive ownership and permissions, and change when the refresh runs.
• crond is active and the cron file remains installed after image or host maintenance.
• The WebLogic data source has no sustained increase in connection failures or waiters.
• Application health checks can obtain a connection and execute a lightweight query.

Avoid logging the token, the API signing key, TNS descriptors containing environment-specific host details, or complete OCI CLI configuration files. Alert on the command's exit status and the age of the latest successful refresh instead.

8. Troubleshooting Runbook

The application fails after the token expiry time

Check the token refresh path before changing WebLogic configuration:

sudo cat /etc/cron.d/oci-db-token-refresh
sudo systemctl status crond
sudo -u oracle tail -n 100 /home/oracle/.oci/db-token/refresh.log
sudo -u oracle /home/oracle/bin/refresh-oci-db-token

If the manual command works but cron does not, compare the cron environment with the script's explicit PATH and, for IAM-user deployments, OCI_CLI_CONFIG_FILE. Do not depend on profile variables loaded by .bashrc or another interactive shell startup file.

A new connection fails with ORA-01017

Confirm the data source does not set a database user or password, then verify:

• TOKEN_AUTH=OCI_TOKEN and TOKEN_LOCATION are inside the TNS SECURITY section.
• TOKEN_LOCATION is an unquoted directory path.
• Both token files exist and are readable by the account running WebLogic.
• oracle.net.tns_admin points to the intended TNS directory on the affected managed-server host.
• The IAM user or workload principal matches the expected group or exclusive database mapping.

The token refresh job reports authorization errors

For an IAM-user deployment, verify the OCI profile uses the expected IAM user and API signing key, then verify the user's IAM group has a use database-connections policy in the appropriate compartment or tenancy scope. For an instance-principal deployment, verify the Compute instance is a member of the intended dynamic group and that the dynamic group has that same policy. When the policy is compartment-scoped, verify the command supplies a matching --scope; without it, OCI CLI requests a tenancy-scoped token. Then check that the database global-user mapping matches the IAM group or the principal OCID. Remember that the database system also needs its OCI IAM and network configuration to validate tokens.

Only one managed server fails

Treat every server as an independent client. Compare the OCI CLI version, /home/oracle/.oci ownership and permissions, cron file, refresh log, token directory, wallet, tnsnames.ora, and oracle.net.tns_admin setting on the failed host with a healthy one.

Summary

OCI IAM token authentication keeps the database password out of the WebLogic data source, but it introduces a small operational responsibility: each host must maintain a usable token and private key. An IAM user and API key are a useful POC or off-cloud option; for WebLogic on OCI Compute, an instance principal and dynamic group often provide a cleaner production identity. Run refresh as the WebLogic OS account, configure it on every managed server, and use WebLogic JDBC testing and retry behavior to recover from new physical connection failures. The application continues to use an ordinary JDBC data source while authentication remains external to application code.