Introduction

This article shows how to configure a WebLogic Server JDBC data source to use an OCI IAM database token when connecting to Oracle AI Database on OCI through Oracle Base Database Service. The data source has no database username or password. OCI IAM issues a short-lived database token, Oracle JDBC Thin signs the token with its paired private key, and the database maps the IAM identity to a global database user.

The configuration was validated with a WebLogic Server 14.1.2 cluster, Oracle JDBC Thin 23.26.0.0.0, and Oracle AI Database 26ai Enterprise Edition High Performance on Base Database Service, version 23.26.3.0.0. The same approach applies to supported WebLogic Server releases with a compatible Oracle JDBC Thin driver.

IAM database tokens expire after one hour. Each managed-server host therefore needs an automatic refresh job that runs before expiry.

Unlike Autonomous Database, Base Database Service requires you to configure the database-side IAM integration, TCPS server wallet, and network access to OCI IAM. It also requires JDBC Thin client configuration.

In This Series

This is Part 2 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 (this article)
Operating OCI IAM Token Authentication for WebLogic JDBC Data Sources (planned)

Part 1 covers the Autonomous Database flow. This article covers Base Database Service. Part 3 will cover the shared operational practices: token renewal, pool behavior, monitoring, and troubleshooting.

What This Article Configures

OCI IAM authorizes a group to use database connections.
The Base Database CDB and target PDB enable OCI IAM.
The PDB maps the IAM group to a global application schema.
TCPS and the required Base Database TLS wallet are configured.
OCI CLI creates a database token and paired private key under the WebLogic operating-system account on every managed-server host.
A host-local cron job refreshes the token every 30 minutes.
A token-enabled TNS alias and a cluster-targeted Generic Data Source use no database password.
A simple application writes and reads rows through the cluster data source.

Replace values in angle brackets with values from your environment.

Prerequisites

You need:

The file-based TOKEN_AUTH=OCI_TOKEN flow in this article requires Oracle JDBC Thin 19.16 or later. WebLogic Server 12.2.1.4, 14.1.1, 14.1.2, and 15.1.1 include supported Oracle JDBC Thin versions when the latest applicable Oracle JDBC for Fusion Middleware JDBC 23.26.x/19.x Bundle Patch for that WebLogic Server release is applied. Confirm the exact installed driver version in your environment; if it is older than 19.16, apply the latest corresponding Bundle Patch. See (KA1182) Critical Patch Update (CPU) Patch Advisor for Oracle Fusion Middleware to identify the patch for the WebLogic Server release. The patch updates the JDBC drivers bundled with WebLogic Server to the upgraded driver versions.
A Base Database Service database and target PDB.
A TCPS listener and a server certificate whose DN is known to the clients.
An OCI IAM user with an API key, membership in an IAM group, and a policy granting database-connections access.
OCI CLI installed under the same operating-system account that runs WebLogic. This article uses the oracle account.
Permission to install a root-managed cron file on each managed-server host.
A Service Gateway route and HTTPS egress from the database subnet to Oracle Services Network. The database uses this path to communicate with OCI IAM.

IAM token access requires TCPS. Do not use native network encryption together with TCPS for the token connection; use TLS alone. See Use Identity and Access Management Authentication with Base Database Service.

1. Prepare the Base Database Service

Configure network and TLS prerequisites

Before enabling IAM, configure the database subnet with a Service Gateway route to Oracle Services Network and a stateful TCP 443 egress rule. Configure TCPS on the database listener and use a client trust wallet containing the issuing certificate or server certificate.

For Base Database Service, the server TLS wallet must be available beneath the database WALLET_ROOT using this layout:

<wallet_root>/<pdb_guid>/tls

Check the settings as a database administrator:

SHOW PARAMETER wallet_root
SHOW PDBS

Use Use Identity and Access Management Authentication with Base Database Service as the Base Database-specific prerequisite guide. For certificate and wallet creation choices, see Oracle Database Configuring Transport Layer Security Encryption.

The exact certificate commands depend on your certificate authority and on whether you use one-way TLS or mTLS. For the one-way TLS configuration used in this article, the server-side checklist is:

Obtain or create the database server certificate and the required certificate chain.
Create a server TLS wallet and add the server certificate, its private key, and the required trusted CA certificates.
Store the server TLS wallet at <wallet_root>/<pdb_guid>/tls, with ownership and permissions that allow the database and listener processes to read it.
Configure or verify the TCPS listener and record its port and server certificate DN.
Restart or reload the relevant database/listener services as required, then verify that the PDB service is registered on the TCPS listener.
Export the issuing CA certificate or server certificate for the WebLogic hosts. Import it into a separate *client trust wallet* on every managed-server host.

Do not treat a downloaded Autonomous Database wallet as a server wallet for Base Database Service. It is client connection material. The WebLogic client only needs to trust the Base Database server certificate for one-way TLS; mTLS is optional and is not required for OCI IAM token authentication.

Enable OCI IAM in the CDB and target PDB

ALTER SYSTEM SET IDENTITY_PROVIDER_TYPE=OCI_IAM SCOPE=BOTH;

Then enable it in the target PDB:

ALTER SESSION SET CONTAINER=<pdb_name>;
ALTER SYSTEM SET IDENTITY_PROVIDER_TYPE=OCI_IAM SCOPE=BOTH;

If the database previously used another external identity provider, reset the old configuration value before enabling OCI IAM:

ALTER SYSTEM RESET IDENTITY_PROVIDER_CONFIG SCOPE=BOTH;

Verify in both containers:

SELECT name, value
FROM v$parameter
WHERE name = 'identity_provider_type';

The result must be OCI_IAM.

Map the IAM group to a PDB schema

Create a shared global database user in the target PDB. Every member of the IAM group maps to this application schema:

ALTER SESSION SET CONTAINER=<pdb_name>;

CREATE USER <hello_app_schema>
  IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=<iam_group_name>';

GRANT CREATE SESSION TO <hello_app_schema>;
GRANT CREATE TABLE TO <hello_app_schema>;
ALTER USER <hello_app_schema> QUOTA UNLIMITED ON USERS;

For a small application test, create a table owned by that schema:

CREATE TABLE <hello_app_schema>.hello_messages (
  id         NUMBER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
  message    VARCHAR2(4000) NOT NULL,
  created_at TIMESTAMP DEFAULT SYSTIMESTAMP NOT NULL,
  created_by VARCHAR2(128) DEFAULT USER NOT NULL
);

2. Configure IAM and Generate a Database Token

Create an IAM policy for the group mapped to the PDB schema. This example limits access to a compartment:

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

You can further restrict the policy to one database resource using a target.database.id condition. The IAM user must be a member of this group.

Configure OCI CLI under the WebLogic operating-system account and create a profile that uses the IAM user’s API key:

[<oci_profile>]
user=<iam_user_ocid>
fingerprint=<api_key_fingerprint>
key_file=/home/oracle/.oci/<api_key_private_file>
tenancy=<tenancy_ocid>
region=<region>

Generate the database token as oracle:

sudo -u oracle /home/oracle/bin/oci iam db-token get --profile <oci_profile>

OCI CLI writes the token and proof-of-possession private key by default:

/home/oracle/.oci/db-token/token
/home/oracle/.oci/db-token/oci_db_key.pem

Restrict access to the WebLogic operating-system account:

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

The token and key permit database access for the IAM principal. Do not include them in deployment archives, source repositories, diagnostics, or support bundles.

3. Refresh the Token Automatically

Database tokens expire after one hour. Create this script as /home/oracle/bin/refresh-base-db-token on every managed-server host:

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

export PATH=/home/oracle/bin:/usr/bin:/bin
exec /home/oracle/bin/oci iam db-token get --profile <oci_profile>

Make it executable by the WebLogic operating-system account:

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

On hardened images, oracle might not be allowed to use crontab. Use a root-managed file named /etc/cron.d/base-db-token-refresh instead:

*/30 * * * * oracle /usr/bin/flock -n /home/oracle/.oci/db-token/.refresh.lock /home/oracle/bin/refresh-base-db-token >> /home/oracle/.oci/db-token/refresh.log 2>&1

Install the file with permissions appropriate for /etc/cron.d and protect the log because it can contain OCI CLI diagnostics:

sudo chown root:root /etc/cron.d/base-db-token-refresh
sudo chmod 644 /etc/cron.d/base-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

The job runs twice an hour, well inside the token lifetime. flock prevents overlapping refreshes. Verify it in the same operating-system context:

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

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

4. Configure the JDBC Thin TNS Alias

Create a protected client configuration directory on every managed-server host. The WebLogic operating-system user needs read access to the TNS files and trust wallet:

sudo -u oracle install -d -m 700 \
  /home/oracle/wls-base-db/network \
  /home/oracle/wls-base-db/trust

Create an auto-login trust wallet and add the certificate chain used by the Base Database TCPS listener. The exact certificate source depends on your PKI and Base Database TLS configuration:

<middleware_home>/bin/orapki wallet create \
  -wallet /home/oracle/wls-base-db/trust -auto_login_only

<middleware_home>/bin/orapki wallet add \
  -wallet /home/oracle/wls-base-db/trust \
  -trusted_cert -cert <database_ca_or_server_certificate.pem> \
  -auto_login_only

Create tnsnames.ora. Both TOKEN_AUTH and TOKEN_LOCATION must be inside the SECURITY section for JDBC Thin. Use an unquoted directory path. In this file, quotes become literal path characters for the JDBC Thin token loader.

<base_db_pdb_iam_alias> =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCPS)(HOST = <db_private_host_or_ip>)(PORT = 2484))
    (CONNECT_DATA = (SERVICE_NAME = <pdb_service_name>))
    (SECURITY =
      (WALLET_LOCATION = file:/home/oracle/wls-base-db/trust/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))
  )

This placement matters. If token settings are outside SECURITY, JDBC Thin can enter token mode without loading the token and private key. The resulting server-side symptom can be ORA-01017 with an empty identity or a verifier lookup for NULL.

5. Configure the Cluster-Targeted Data Source

Create a Generic Data Source that resolves the token-enabled TNS alias. Do not set a database user name or password. The database identity comes entirely from the OCI IAM token.

from java.lang import String
from jarray import array
from weblogic.management.configuration import TargetMBean
import os

admin_url = 't3s://<admin_host>:<admin_port>'
cluster_name = '<cluster_name>'
data_source_name = 'HelloBaseDbDataSource'

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

if getMBean('/JDBCSystemResources/' + data_source_name) is None:
    jdbc = cmo.createJDBCSystemResource(data_source_name)
    resource = jdbc.getJDBCResource()
    resource.setName(data_source_name)

    driver = resource.getJDBCDriverParams()
    driver.setDriverName('oracle.jdbc.OracleDriver')
    driver.setUrl('jdbc:oracle:thin:@<base_db_pdb_iam_alias>')
    driver.getProperties().createProperty('oracle.net.tns_admin').setValue(
        '/home/oracle/wls-base-db/network')

    resource.getJDBCDataSourceParams().setJNDINames(
        array(['jdbc/HelloBaseDbDataSource'], String))
    jdbc.setTargets(array([getMBean('/Clusters/' + cluster_name)], TargetMBean))

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

Run WLST using administrator credentials supplied through the environment:

export WLS_USER=<weblogic_administrator>
export WLS_PWD=<weblogic_administrator_password>
<middleware_home>/oracle_common/common/bin/wlst.sh configure_base_db_datasource.py

For a cluster, repeat the OCI CLI, token-refresh, trust-wallet, and TNS configuration on every managed-server host. A data source targeted to a cluster can create a physical JDBC connection on any cluster member.

6. Use the Data Source from an Application

The application needs no IAM or token code. It performs a normal JNDI lookup:

DataSource dataSource = (DataSource) new InitialContext()
    .lookup("java:comp/env/jdbc/HelloAppDataSource");

try (Connection connection = dataSource.getConnection()) {
    // Use the connection normally.
}

Map the application resource reference to the passwordless global JNDI name in WEB-INF/weblogic.xml:

<resource-description>
  <res-ref-name>jdbc/HelloAppDataSource</res-ref-name>
  <jndi-name>jdbc/HelloBaseDbDataSource</jndi-name>
</resource-description>

This preserves portable application code while allowing a separate deployment to use the Base Database token data source.

7. Verify the End-to-End Flow

First, create a fresh token on each managed-server host:

sudo -u oracle /home/oracle/bin/oci iam db-token get --profile <oci_profile>

Deploy the application to the cluster and write a message through the managed server or load balancer:

curl -k -X POST \
  --data-urlencode 'message=WebLogic Base DB passwordless OCI IAM token POC' \
  https://<managed_server_or_load_balancer>/hello-base-db/hello-db

curl -k https://<managed_server_or_load_balancer>/hello-base-db/hello-db

The test should return the stored row with the global database schema:

1 | WebLogic Base DB passwordless OCI IAM token POC | <timestamp> | HELLO_APP

Verify the authentication identity from a token-authenticated database connection:

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

For this shared global-user mapping, the values are:

USER                    HELLO_APP
AUTHENTICATED_IDENTITY  <iam_user_name>
AUTHENTICATION_METHOD   TOKEN_GLOBAL

Troubleshooting

ORA-01017 or an IAM lookup for `NULL`

Confirm that JDBC Thin is actually loading the token and paired private key. Check all of the following:

TOKEN_AUTH=OCI_TOKEN and TOKEN_LOCATION are inside the TNS SECURITY section.
TOKEN_LOCATION is an unquoted directory path.
The directory contains token and oci_db_key.pem.
Both files are readable by the WebLogic operating-system account.
oracle.net.tns_admin points to the directory containing this exact tnsnames.ora file.

ORA-18718: token configuration is invalid

This often means the token location does not resolve to a readable directory containing both required files. A quoted TNS value can cause JDBC Thin to look for a literal path such as "/home/oracle/.oci/db-token"/token. Remove the quotes and keep the token directory permissions restricted to the WebLogic OS user.

ORA-12514 after listener maintenance

The PDB service is not registered with the listener. Verify the service and force dynamic registration if appropriate:

ALTER SYSTEM REGISTER;

The token expires after one hour

Verify that the refresh job is installed and running on every managed-server host. A fresh physical JDBC connection made after expiry will otherwise fail. Existing pooled connections can remain usable until WebLogic needs to create or replace a physical connection.

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

Summary

WebLogic Server can connect to Oracle AI Database on OCI through Base Database Service without storing a database password in the data source. The critical pieces are Base Database IAM and TCPS prerequisites, a protected OCI token and private key on every managed-server host, and a JDBC Thin TNS descriptor that places TOKEN_AUTH and TOKEN_LOCATION inside SECURITY. Once configured, the application uses an ordinary WebLogic data source and the database records the IAM-authenticated session as TOKEN_GLOBAL. Keep the token current with a refresh job on every host that can service the application.

WebLogic Server and Oracle AI Database on OCI

Introduction

In This Series

What This Article Configures

Prerequisites

1. Prepare the Base Database Service

Configure network and TLS prerequisites

Enable OCI IAM in the CDB and target PDB

Map the IAM group to a PDB schema

2. Configure IAM and Generate a Database Token

3. Refresh the Token Automatically

4. Configure the JDBC Thin TNS Alias

5. Configure the Cluster-Targeted Data Source

6. Use the Data Source from an Application

7. Verify the End-to-End Flow

Troubleshooting

ORA-01017 or an IAM lookup for `NULL`

ORA-18718: token configuration is invalid

ORA-12514 after listener maintenance

The token expires after one hour

Summary

Adrian Padilla Duarte

Product Manager - WebLogic Server on OCI

Passwordless JDBC with OCI IAM Tokens: WebLogic Server and Autonomous Database 26ai

WebLogic Server and Oracle AI Database on OCI

Introduction

In This Series

What This Article Configures

Prerequisites

1. Prepare the Base Database Service

Configure network and TLS prerequisites

Enable OCI IAM in the CDB and target PDB

Map the IAM group to a PDB schema

2. Configure IAM and Generate a Database Token

3. Refresh the Token Automatically

4. Configure the JDBC Thin TNS Alias

5. Configure the Cluster-Targeted Data Source

6. Use the Data Source from an Application

7. Verify the End-to-End Flow

Troubleshooting

ORA-01017 or an IAM lookup for NULL

ORA-18718: token configuration is invalid

ORA-12514 after listener maintenance

The token expires after one hour

Summary

Authors

Adrian Padilla Duarte

Product Manager - WebLogic Server on OCI

Passwordless JDBC with OCI IAM Tokens: WebLogic Server and Autonomous Database 26ai

ORA-01017 or an IAM lookup for `NULL`