DPY-6005 / ORA-12506: All documented Thin mode IAM token approaches fail on ADB-S Private Endpoint — TOKEN_AUTH not included in TNS Connect packet

[alexmocciaoci]

1. What versions are you using?

platform.platform: Windows-11-10.0.xxxxx-xxx
sys.maxsize > 2**32: True
platform.python_version: 3.12.0
oracledb.__version__: 3.4.2
Oracle Database: Autonomous Database Serverless (ADB-S) — Private Endpoint on OCI VCN private subnet
init_oracle_client(): NOT called — Thin mode confirmed via oracledb.is_thin_mode() → True

2. Is it an error or a hang or a crash?

Immediate error on every connect attempt.

3. What error(s) or behavior you are seeing?

DPY-6005: cannot connect to database.
DPY-6000: Listener refused connection. (Similar to ORA-12506)

All pre-connection checks pass:

• DNS resolves PE hostname to private IP xx.x.x.x — OK
• TCP port 1522 reachable — OK
• ewallet.pem present and valid — OK
• IAM DB token acquired via oci iam db-token get — OK (1934 chars, valid)
• Private key file present — OK (1703 chars, PKCS8)

The same token, wallet, and network path work correctly with:

• python-oracledb Thick mode → CONNECTS
• JDBC Thin (SQL Developer) → CONNECTS
• SQL*Plus with OCI Instant Client (Thick) → CONNECTS

4. Does your application call init_oracle_client()?

No. Thin mode only. Confirmed via oracledb.is_thin_mode() → True.

5. Include a runnable Python script that shows the problem.

We tested all documented Thin mode approaches for OCI IAM token authentication as described in the official documentation at:
https://python-oracledb.readthedocs.io/en/stable/user_guide/authentication_methods.html

All four tests fail with the same identical error.

---

Test 1 — extra_auth_params with oci_tokens plugin (ConfigFileAuthentication)

This is the primary documented approach for Thin mode in the official docs.

import oracledb
import oracledb.plugins.oci_tokens

WALLET_DIR = r"path\to\wallet"
WALLET_PWD = "wallet_password"
PE_HOST    = "<pe-host>.adb.xx-xxxxx-x.oraclecloud.com"
PE_PORT    = 1522
SERVICE    = "<hash>_<dbname>_high.adb.oraclecloud.com"

dsn = (
    f"(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(PORT={PE_PORT})(HOST={PE_HOST}))"
    f"(CONNECT_DATA=(SERVICE_NAME={SERVICE}))"
    f"(SECURITY=(SSL_SERVER_DN_MATCH=YES)))"
)

conn = oracledb.connect(
    dsn=dsn,
    config_dir=WALLET_DIR,
    wallet_location=WALLET_DIR,
    wallet_password=WALLET_PWD,
    extra_auth_params={
        "auth_type": "ConfigFileAuthentication",
        "profile": "DEFAULT"
    }
)

Result:

DPY-6005: cannot connect to database.
DPY-6000: Listener refused connection. (Similar to ORA-12506)

---

Test 2 — access_token 2-tuple with TNS alias from wallet tnsnames.ora

import oracledb

WALLET_DIR = r"path\to\wallet"
WALLET_PWD = "wallet_password"

with open(r"~\.oci\db-token\token") as f:
    db_token = f.read().strip()
with open(r"~\.oci\db-token\oci_db_key.pem") as f:
    db_key = f.read().strip()

conn = oracledb.connect(
    dsn="<tns_alias>",
    config_dir=WALLET_DIR,
    wallet_location=WALLET_DIR,
    wallet_password=WALLET_PWD,
    access_token=(db_token, db_key)
)

Note: tnsnames.ora downloaded from ADB-S console does not contain TOKEN_AUTH in the SECURITY section — this is the as-is wallet file as downloaded from Oracle Cloud Console.

Result:

DPY-6005: cannot connect to database.
DPY-6000: Listener refused connection. (Similar to ORA-12506)

---

Test 3 — access_token 2-tuple with explicit DSN, no TOKEN_AUTH

import oracledb

WALLET_DIR = r"path\to\wallet"
WALLET_PWD = "wallet_password"
PE_HOST    = "<pe-host>.adb.xx-xxxxx-x.oraclecloud.com"
PE_PORT    = 1522
SERVICE    = "<hash>_<dbname>_high.adb.oraclecloud.com"

with open(r"~\.oci\db-token\token") as f:
    db_token = f.read().strip()
with open(r"~\.oci\db-token\oci_db_key.pem") as f:
    db_key = f.read().strip()

dsn = (
    f"(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(PORT={PE_PORT})(HOST={PE_HOST}))"
    f"(CONNECT_DATA=(SERVICE_NAME={SERVICE}))"
    f"(SECURITY=(SSL_SERVER_DN_MATCH=YES)))"
)

conn = oracledb.connect(
    dsn=dsn,
    wallet_location=WALLET_DIR,
    wallet_password=WALLET_PWD,
    access_token=(db_token, db_key)
)

Result:

DPY-6005: cannot connect to database.
DPY-6000: Listener refused connection. (Similar to ORA-12506)

---

Test 4 — access_token 2-tuple with explicit DSN and TOKEN_AUTH=OCI_TOKEN injected in SECURITY section

We explicitly added TOKEN_AUTH=OCI_TOKEN to the DSN SECURITY section to verify whether the driver passes it in the TNS Connect packet.

import oracledb

WALLET_DIR = r"path\to\wallet"
WALLET_PWD = "wallet_password"
PE_HOST    = "<pe-host>.adb.xx-xxxxx-x.oraclecloud.com"
PE_PORT    = 1522
SERVICE    = "<hash>_<dbname>_high.adb.oraclecloud.com"

with open(r"~\.oci\db-token\token") as f:
    db_token = f.read().strip()
with open(r"~\.oci\db-token\oci_db_key.pem") as f:
    db_key = f.read().strip()

dsn = (
    f"(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(PORT={PE_PORT})(HOST={PE_HOST}))"
    f"(CONNECT_DATA=(SERVICE_NAME={SERVICE}))"
    f"(SECURITY=(SSL_SERVER_DN_MATCH=YES)(TOKEN_AUTH=OCI_TOKEN)))"
)

conn = oracledb.connect(
    dsn=dsn,
    wallet_location=WALLET_DIR,
    wallet_password=WALLET_PWD,
    access_token=(db_token, db_key)
)

Result:

DPY-6005: cannot connect to database.
DPY-6000: Listener refused connection. (Similar to ORA-12506)

TOKEN_AUTH=OCI_TOKEN in the DSN has no effect — the listener refuses the connection identically.

---

Additional findings from source code inspection

We inspected the source of oci_tokens.py (installed version 3.4.2). The plugin hook function is:

def oci_token_hook(params: oracledb.ConnectParams):
    if params.extra_auth_params is not None:
        def token_callback(refresh):
            return generate_token(params.extra_auth_params, refresh)
        params.set(access_token=token_callback)

oracledb.register_params_hook(oci_token_hook)

The plugin only sets access_token on ConnectParams. It does not inject TOKEN_AUTH or any other parameter into the TNS Connect descriptor. This is consistent with Test 4 showing that even manually adding TOKEN_AUTH=OCI_TOKEN in the DSN has no effect on the listener response.

---

Key question to the driver team

The ADB-S Private Endpoint listener applies ACL filtering on the initial TNS Connect packet. Based on our tests and investigation, the hypothesis is:

When access_token is set as a 2-tuple (OCI IAM token) in Thin mode — either directly or via the oci_tokens plugin — does the driver include TOKEN_AUTH=OCI_TOKEN in the serialized TNS Connect packet sent to the listener?

JDBC Thin and OCI Thick clients both successfully connect to the same ADB-S Private Endpoint with the same token and wallet. The only client that fails is python-oracledb Thin mode.

Important note: The official documentation at
https://python-oracledb.readthedocs.io/en/stable/user_guide/authentication_methods.html
states that OCI IAM token-based authentication is supported in both Thin and Thick modes. However, it does not explicitly document whether Private Endpoint is a supported topology for Thin mode with IAM token. All documentation examples appear to target public ADB-S endpoints. If Private Endpoint is a known unsupported topology for Thin mode + IAM token, this should be explicitly documented.

---

Test	Method	DSN TOKEN_AUTH	Result
1	extra_auth_params + oci_tokens plugin	Not present	DPY-6005 ORA-12506
2	access_token=(token, key) + TNS alias	Not present in tnsnames.ora	DPY-6005 ORA-12506
3	access_token=(token, key) + explicit DSN	Not present	DPY-6005 ORA-12506
4	access_token=(token, key) + explicit DSN	TOKEN_AUTH=OCI_TOKEN present	DPY-6005 ORA-12506
Thick mode	access_token=(token, key)	N/A	CONNECTS
JDBC Thin	Java driver	Injected automatically	CONNECTS

[anthony-tuininga]

I will let @vignanv and @suraj-ora-2020 look into this further as they have more knowledge of this area than I do! The error you are getting, however, indicates that the listener has refused the connection and the token authentication hasn't even been attempted. The error in question is as follows: ORA-12506: TNS:listener rejected connection based on service ACL filtering. This is the error that is generally returned when regular TLS is not supported and mTLS is mandated -- and the wallet that has been provided (or the wallet password) are invalid. JDBC thin and python-oracledb thick mode use different files, unfortunately! So that issue needs to be addressed first -- at which point you may discover that there is no bug with token authentication!

[alexmocciaoci]

Update — April 2026 | Final user-side investigation summary
Following the SR exchange with Engineering and additional source code analysis, here is the complete picture of what has been tested and what remains unresolved.
Three distinct approaches have now been exhausted on the public API:
Test 1 and 2 (already in the issue): oci_tokens plugin via extra_auth_params and explicit access_token=(token, key) tuple, both with and without TOKEN_AUTH=OCI_TOKEN in the DSN SECURITY section. All fail identically with DPY-6005 / DPY-6000 / ERR=12506 / EMFI=4 at the listener acceptance stage.
Test 3 (new): Based on source code inspection of the Thin mode TNS builder, an attempt was made to inject TOKEN_AUTH=OCI_TOKEN directly into CONNECT_DATA via extra_connect_data_args. This parameter exists internally in the driver's parser/builder chain but is not exposed in the public API:
connect() got an unexpected keyword argument 'extra_connect_data_args'
TypeError
This means even the internal-level workaround suggested by source analysis is not applicable from user code.
The packet traces confirm the following:
In one Thin test, TOKEN_AUTH=OCI_TOKEN was present in the outbound connect descriptor under SECURITY. In another it was absent. The listener response was byte-for-byte identical in both cases: ERR=12506 / EMFI=4, immediate disconnect. Therefore the text content of the descriptor does not explain the rejection.
Current position:

python-oracledb Thin: fails on all documented and undocumented paths
python-oracledb Thick: connects successfully
JDBC Thin: connects successfully

The problem is not configuration, not DNS, not TCP reachability, not token validity, not wallet content. It is specific to the Thin mode initial connection acceptance path against ADB-S Private Endpoint with OCI IAM DB token authentication.
The proposed extra_connect_data_args workaround is not available through the public connect API. There is no remaining user-side action to take.
The open question for Engineering remains the same:
Is python-oracledb Thin officially supported for OCI IAM DB token authentication against ADB-S Private Endpoint — yes or no? If yes, which exact internal fix is required in the Thin ConnectMessage construction path to match the handshake that Thick and JDBC Thin are performing successfully on the same target?

[alexmocciaoci]

Hi @anthony-tuininga , thank you.
A clarification on the wallet point: the packet traces show that TCP connectivity and TLS establishment both succeed in Thin mode. The ewallet.pem and wallet password are valid — the connection reaches the listener, the listener processes the ConnectMessage, and returns ERR=12506 in its response packet. If the wallet or password were invalid, the TLS handshake would fail before the listener could respond with ORA-12506.
The rejection happens at the listener ACL filtering stage, after TLS is already established, not at the TLS layer itself.
Happy to share the full packet traces again if useful for @vignanv and @suraj-ora-2020.

[alexmocciaoci]

While waiting for Engineering's analysis, I reviewed the public python-oracledb source (v3.4.2) to see whether the Thin and Thick paths visibly differ during initial connection setup. I may be misreading internals, so I am sharing this only as a hypothesis for the driver team to confirm or correct.

---

Observation 1 — Thin ConnectMessage appears token-agnostic in phase 1

In src/oracledb/impl/thin/messages/connect.pyx, ConnectMessage.send() has the signature send(self, WriteBuffer buf) and sets:

c

uint8_t nsi_flags = TNS_NSI_SUPPORT_SECURITY_RENEG | TNS_NSI_DISABLE_NA

From the public source, I do not see any visible branch in this method based on access_token / token presence. If I am reading this correctly, the phase-1 Connect packet header is built the same way regardless of whether OCI IAM token auth is active.

---

Observation 2 — Thin connect descriptor construction does not visibly consult token state

In src/oracledb/impl/thin/utils.pyx, _get_connect_data() builds the CID from program, machine, and osuser, then calls description.build_connect_string(cid). From the public Thin-side code path I reviewed, I do not see _token or _private_key state being consulted during this phase-1 connect data construction.

---

Observation 3 — Thick passes token state into OCI/ODPI-C before connection creation

In src/oracledb/impl/thick/connection.pyx, when a token is present, the driver sets:

c

common_params.accessToken = &access_token

and, when username/password are absent:

c

conn_params.externalAuth = 1

before dpiConn_create() is called.

---

My working hypothesis

My current hypothesis is not that I know the exact missing wire-level field, but simply that the Thin and Thick paths are not signaling the initial connection phase in the same way when OCI IAM DB token authentication is used.

That would fit the observed behavior in my tests:

Client | Result -- | -- python-oracledb Thick | ✅ Connects JDBC Thin | ✅ Connects python-oracledb Thin | ❌ Refused — ERR=12506 / EMFI=4 before IAM token flow is reached

If Engineering confirms that this interpretation is wrong, I would appreciate the correction. If it is directionally correct, then it may help explain why python-oracledb Thin fails specifically on ADB-S Private Endpoint in this topology even though Thick succeeds on the same target.