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.

[sudarshan12s]

Thanks @alexmocciaoci so much for your time and analysis. Token-based authentication/RPC has not started yet, but we are seeing a failure before that, in the CONNECT packet after the TLS exchange.

Could you share the client traces from your lab tests for thick mode, where it works? We would like to see if TOKEN_AUTH=OCI_TOKEN & TOKEN_LOCATION=<dir> (or default ~/.oci/db-token) are still injected in thick modes for this specific configurations. In thin mode, we do not send them as we do convey this information after CONNECT packet in OAUTH RPC..

inside sqlnet.ora , can you add the following:

ADR_BASE=/tmp/mylogs
TRACE_LEVEL_CLIENT=16

Make the directory:

mkdir /tmp/mylogs

Run your test program, preferably with only the connect portion, and you should see logs in a folder similar to:

/tmp/mylogs/oradiag_cjones/diag/clients/user_cjones/host_2709986801_110/trace.

You can then put the .trc file in a gist, if there is nothing secret in it or send us in mail..

Additionally, can you confirm these:

Does ADBS PDB have one way TLS enabled ?
Does it make difference if its enabled?
Are we using Walletless configurations?

I might have missed, But if we pass dsn including TOKEN_AUTH, TOKEN_LOCATION , does that help?
This is just to get an observation , Its not required to be passed.

dsn = """ 
(DESCRIPTION=
  (RETRY_COUNT=20)
  (RETRY_DELAY=3)
  (ADDRESS=
    (PROTOCOL=tcps)
    (HOST=adb.us-ashburn-1.oraclecloud.com)
    (PORT=1522)
  )
  (CONNECT_DATA=
    (SERVICE_NAME=g627e62277be9e1_db19_high.adb.oraclecloud.com)
  )
  (SECURITY=
    (SSL_SERVER_DN_MATCH=TRUE)
    (SSL_SERVER_CERT_DN="CN=adwc.uscom-east-1.oraclecloud.com, O=Oracle Corporation, L=Redwood City, ST=California, C=US")
     (TOKEN_AUTH=OCI_TOKEN)
     (TOKEN_LOCATION='/opt/oracle/token')
  )
)
""".strip()
con = oracledb.connect(
    user=db_config.user, password=db_config.pw, dsn=dsn)

[alexmocciaoci]

Thanks, this is very helpful.

Your clarification is important: in Thin mode, TOKEN_AUTH=OCI_TOKEN and TOKEN_LOCATION are not sent in the CONNECT packet, since the token-related information is conveyed later via OAUTH RPC. That is consistent with what I am observing in the lab: with ADB-S Private Endpoint, the listener appears to reject the session after TLS but before token-based authentication / OAUTH RPC starts.

Also, regarding your question about explicitly passing TOKEN_AUTH=OCI_TOKEN / TOKEN_LOCATION in the DSN: I already ran the Thin-mode packet/debug tests with PYO_DEBUG_PACKETS=1 in both variants:

1. DSN explicitly including TOKEN_AUTH=OCI_TOKEN
2. DSN without TOKEN_AUTH=OCI_TOKEN

In my lab traces, this made no observable difference to the outcome. In both cases, the ADB-S Private Endpoint listener rejected the session at the same stage, i.e. after the TLS exchange and before token-based authentication / OAUTH RPC started.

So, from the packet-level evidence already shared, explicitly adding TOKEN_AUTH=OCI_TOKEN to the DSN did not change the Thin-mode behavior in this scenario.

I can collect and share the Thick mode Oracle Net client trace as requested, using:

ADR_BASE=/tmp/mylogs
TRACE_LEVEL_CLIENT=16

I will run a minimal connect-only test to keep the trace focused.

For your questions:

The working Thick-mode test path is wallet-based, not walletless.
I will confirm separately whether one-way TLS is enabled on the ADB-S PDB and whether enabling/disabling it changes the observed behavior.

At this point, the key technical question seems to be whether the ADB-S Private Endpoint listener requires IAM-related semantics to be visible already in the CONNECT packet, before the post-CONNECT OAUTH RPC phase used by Thin mode.

I will share the Thick trace once collected.

[alexmocciaoci]

hello, @sudarshan12s , @anthony-tuininga

Thick mode Oracle Net trace — findings summary
I collected the Thick mode Oracle Net client trace (TRACE_LEVEL_CLIENT=16) for a minimal connect-only test against the same ADB-S Private Endpoint target.
Grep output for TOKEN_AUTH / TOKEN_LOCATION / OCI_TOKEN / token on the trace file:

D:2026-04-15 12:31:13.789895 : nspsend:24 5F 54 4F 4B 45 4E 5F |$TOKEN|
D:2026-04-15 12:31:13.887337 : nsbasic_bsd:5F 54 4F 4B 45 4E 5F 41 |_TOKEN_A|
D:2026-04-15 12:31:13.934234 : nsbasic_bsd:5F 54 4F 4B 45 4E 5F 41 |_TOKEN_A|
D:2026-04-15 12:31:14.180150 : nsbasic_brc:0C 54 4F 4B 45 4E 5F 47 |.TOKEN_G|

All four hits appear after nscon:connect handshake is complete. Token-related data is visible only in nspsend and nsbasic_bsd/nsbasic_brc calls — which are post-CONNECT Oracle Net transport layer operations. This is fully consistent with your clarification that in Thick mode the token is conveyed via OAUTH RPC, not in the CONNECT packet.
This means that in Thick mode, just like in Thin mode, no token data is present in the initial CONNECT packet. Both paths handle token information post-CONNECT via OAUTH RPC.
The open question therefore becomes more specific: if neither Thick nor Thin sends token data in the CONNECT packet, what is different in the initial CONNECT packet sent by Thin mode that causes the ADB-S Private Endpoint listener to refuse it — before the OAUTH RPC phase is ever reached — while accepting the identical topology from Thick mode?

[sudarshan12s]

hello, @sudarshan12s , @anthony-tuininga

Thick mode Oracle Net trace — findings summary I collected the Thick mode Oracle Net client trace (TRACE_LEVEL_CLIENT=16) for a minimal connect-only test against the same ADB-S Private Endpoint target. Grep output for TOKEN_AUTH / TOKEN_LOCATION / OCI_TOKEN / token on the trace file:

D:2026-04-15 12:31:13.789895 : nspsend:24 5F 54 4F 4B 45 4E 5F |$TOKEN| D:2026-04-15 12:31:13.887337 : nsbasic_bsd:5F 54 4F 4B 45 4E 5F 41 |_TOKEN_A| D:2026-04-15 12:31:13.934234 : nsbasic_bsd:5F 54 4F 4B 45 4E 5F 41 |_TOKEN_A| D:2026-04-15 12:31:14.180150 : nsbasic_brc:0C 54 4F 4B 45 4E 5F 47 |.TOKEN_G|

All four hits appear after nscon:connect handshake is complete. Token-related data is visible only in nspsend and nsbasic_bsd/nsbasic_brc calls — which are post-CONNECT Oracle Net transport layer operations. This is fully consistent with your clarification that in Thick mode the token is conveyed via OAUTH RPC, not in the CONNECT packet. This means that in Thick mode, just like in Thin mode, no token data is present in the initial CONNECT packet. Both paths handle token information post-CONNECT via OAUTH RPC. The open question therefore becomes more specific: if neither Thick nor Thin sends token data in the CONNECT packet, what is different in the initial CONNECT packet sent by Thin mode that causes the ADB-S Private Endpoint listener to refuse it — before the OAUTH RPC phase is ever reached — while accepting the identical topology from Thick mode?

Thanks @alexmocciaoci . Can you share us the entire trace file generated for oracledb.connect API assuming the config is for test and not very secret data used. You can send mail to us.

anthony.tuininga@oracle.com (Anthony is on leave till 17th )
sudarshan.ss.s@oracle.com
vignana.vadloori@oracle.com

[alexmocciaoci]

Hi @sudarshan12s , @anthony-tuininga

I cannot share the raw trace file.

The relevant findings from the Thick mode trace have already been summarized in the comment above, including the complete grep output for TOKEN_AUTH, TOKEN_LOCATION, OCI_TOKEN, and token.

Based on that trace, the important observation is that the token-related data appears only after nscon:connect is complete, in post-CONNECT Oracle Net operations. This is consistent with your clarification that token information is conveyed via OAUTH RPC, not in the initial CONNECT packet.

At this point, the remaining technical question seems to be the difference in CONNECT packet structure / semantics between Thick and Thin mode that leads the ADB-S Private Endpoint listener to reject Thin mode before the OAUTH RPC phase is reached.

Could you please try to reproduce this on your side with a test ADB-S Private Endpoint configuration? The setup is straightforward:

• ADB-S with Private Endpoint
• python-oracledb Thick mode + IAM DB token -> connects
• python-oracledb Thin mode + IAM DB token -> fails with ERR=12506 / EMFI=4

A server-side packet comparison at the PE listener now seems to be the most direct way to isolate the exact CONNECT-level difference.

Regards,
Alessandro Moccia

[sudarshan12s]

Hi @alexmocciaoci,

Could you please verify if one-way TLS token authentication works on your end? You can test this by deselecting the "Mutual TLS (mTLS) authentication" option under the Network settings.

Regarding the 12506 error on the CONNECT packet: this typically indicates a mismatch where the client is attempting a one-way TLS connection, but the database is still expecting mTLS. One of the reason , it can happen is if the wallet_password or wallet_location parameters are missing from your oracledb.connect configuration.

[alexmocciaoci]

Hi @sudarshan12s ,

That hypothesis does not match the test cases already documented in this issue.

wallet_location and wallet_password are explicitly present in all four Thin-mode tests already posted above. So this is not a case where Thin is falling back to one-way TLS because those parameters were omitted.

Also, the observed failure point is not consistent with a basic TLS setup problem. In the packet traces already shared, TCP/TLS completes and the listener then returns ERR=12506 / EMFI=4. So the rejection is occurring at listener level after TLS establishment, not as an initial wallet/password loading failure.

The comparative evidence remains:

• python-oracledb Thick + IAM DB token -> works
• JDBC Thin -> works
• SQL*Plus / OCI client -> works
• python-oracledb Thin + IAM DB token -> fails with ERR=12506 / EMFI=4

All of these tests use the same target ADB-S Private Endpoint, same machine, same network path, same wallet directory, and same IAM DB token flow.

So the remaining engineering question is still the same:

What is structurally different in the Thin-mode CONNECT packet that causes the ADB-S Private Endpoint listener to reject it at ACL filtering stage, while accepting the Thick-mode CONNECT packet in the same scenario?

At this point, the most direct next step still appears to be a listener-side / packet-level comparison of Thick vs Thin for the reproduced PE case.