Authentication

How ArpeOracle authenticates to Oracle, method by method. Every option named here is listed in the Connection option reference.

Password (O5LOGON)

The default. Supply User ID and Password; ArpeOracle performs Oracle's O5LOGON challenge-response. The 12c (PBKDF2-HMAC-SHA512) and 11g (SHA-1) verifiers are both supported and selected automatically from the server's challenge.

Server=dbhost:1521/orclpdb1;User ID=scott;Password=tiger

The password is never sent in clear, even without TLS: it is AES-encrypted under a key derived from the server's challenge, and the driver verifies the server's response in return (mutual auth), so a man-in-the-middle that accepts any password is detected. This protects the credential — it does not encrypt SQL text or result rows. For that, use TLS.

A wrong username or password fails fast with ORA-01017. Oracle does not distinguish "no such user" from "wrong password", and neither does the error.

Proxy authentication (connect through)

Authenticate as one account but run in another user's schema. The authenticating account must have been granted access:

ALTER USER target GRANT CONNECT THROUGH proxyacct;

Server=dbhost:1521/orclpdb1;User ID=proxyacct;Password=...;Proxy User=target

Inside the session, SYS_CONTEXT('USERENV','SESSION_USER') is TARGET and PROXY_USER is PROXYACCT. An ungranted target, or a wrong password for the authenticating account, is refused with ORA-01017.

Change password at connect

Change the login password as part of the connect — the way in past an expired one. The old password authenticates the request; the new one takes effect on success.

Server=dbhost:1521/orclpdb1;User ID=scott;Password=old;New Password=new

After a successful connect the new password authenticates and the old one no longer does.

TLS (TCPS)

Encrypts the whole connection. SSL Mode selects the level:

Mode	Encrypts	Authenticates the server
disable (default)	no	—
require	yes	no
verify-ca	yes	chain only
verify-full	yes	chain and hostname

Use verify-full for anything real. Trust comes from SSL Root Cert (a PEM CA bundle) or a Wallet Location directory holding ewallet.pem (client key + certificate + CAs in one PEM, the python-oracledb thin layout); Wallet Password unlocks an encrypted wallet key. Without either, OpenSSL's default locations are used, which on RHEL and Windows hold no CAs (see below). A wallet or CA bundle does not enable TLS on its own — combined with disable it is rejected. TLS 1.2 is the minimum. TCPS listeners conventionally use port 2484 — set Port explicitly.

Server=dbhost:2484/orclpdb1;User ID=scott;Password=tiger;
sslmode=verify-full;wallet_location=/etc/oracle/wallet

Protocol versions

TLS 1.2 is the minimum and TLS 1.3 is used when the server offers it. The minimum is fixed: there is no option to allow TLS 1.0 / 1.1.

Independent of the host's TLS stack

Because the driver brings its own OpenSSL, the TLS versions it can use do not depend on the host. A server that only accepts TLS 1.3 works even where the host's own TLS stack has no TLS 1.3: for example Windows Server 2019 and older (Schannel), or a Linux host whose system OpenSSL is 1.0.x. The limit on Linux is the C library: the released binary needs glibc 2.28 or later (RHEL 8, Debian 10, Ubuntu 20.04 or newer), so RHEL 7 is not supported.

Where trusted certificates come from

ArpeOracle carries its own copy of OpenSSL 3, linked into the library (the Linux release is built with OpenSSL 3.6.4). It never uses the operating system's TLS stack or certificate store. For verify-ca / verify-full, the CAs come from, in this order:

1. ssl_root_cert (a PEM file);
2. the wallet's ewallet.pem;
3. OpenSSL's default locations: the SSL_CERT_FILE (PEM bundle) / SSL_CERT_DIR (hashed directory) environment variables, else /etc/ssl/cert.pem and /etc/ssl/certs/ on Linux.

Client OS	Without ssl_root_cert or a wallet
Debian, Ubuntu	Works: /etc/ssl/certs holds the system CAs.
RHEL, Rocky, AlmaLinux 8 and newer	Fails with "unable to get local issuer certificate": the CA bundle lives under /etc/pki. Set ssl_root_cert, or SSL_CERT_FILE=/etc/pki/tls/certs/ca-bundle.crt.
Windows	Fails: the Windows certificate store is not read. Set ssl_root_cert to a PEM file holding the CA, or use a wallet.

Oracle Cloud ADB connections are not affected: the instance wallet carries the CAs.

Host name check and SNI

With verify-full, the host the driver connects to (after any listener redirect) must match the certificate's DNS SANs, or its CN when it has none. A wildcard must be the whole first label (*.example.com). Connect by DNS name: an IP address is not matched against IP SANs. Oracle's DN matching (SSL_SERVER_CERT_DN) is not supported. SNI is always sent.

Client certificates (mutual TLS)

A wallet's certificate and key are always presented to the server, in every ssl_mode including require. There is no separate client certificate or key option; wallet_password unlocks an encrypted key.

TCPS from a descriptor or tnsnames.ora

PROTOCOL=TCPS in a connect descriptor or alias turns TLS on as require: encrypted, but the certificate is not checked, and the descriptor's SECURITY section (SSL_SERVER_CERT_DN, wallet settings) is ignored. Set ssl_mode (and ssl_root_cert or wallet_location) to have the server checked.

OpenSSL configuration

Like any OpenSSL 3 program, the driver reads an OpenSSL configuration file at the first TLS connection: the file named by OPENSSL_CONF, else /etc/ssl/openssl.cnf on Linux. Settings there, such as cipher lists or the security level, apply. RHEL's system crypto-policies live under /etc/pki/tls/openssl.cnf, so they apply only if that file is the one loaded (for example with OPENSSL_CONF=/etc/pki/tls/openssl.cnf). sqlnet.ora is never read.

TLS errors are listed under Troubleshooting → TLS / wallets.

OCI IAM token (Oracle Cloud)

Version

Since ArpeOracle v0.2.0.

Auth Method=token logs in to Oracle Cloud with an OCI IAM database token instead of a password. token_location is a directory holding the token (token) and its PEM private key (oci_db_key.pem) — exactly what oci iam db-token get writes to ~/.oci/db-token. It is an ADBC option (adbc.arpeoracle.token_location), set via AdbcDatabaseSetOption, not a connection-string keyword. No username or password is set: the driver presents the token and proves it holds the matching private key by signing the login request with it (RSA-SHA256). The database validates the signature against the public key inside the token, so a token used with the wrong key is refused with an ORA error.

Server=adb.<region>.oraclecloud.com:1522/<svc>_low.adb.oraclecloud.com;
Auth Method=token;sslmode=verify-full;Wallet Location=/home/you/wallet;Wallet Password=...

with adbc.arpeoracle.token_location=/home/you/.oci/db-token set as an ADBC option alongside it (the same way the OAuth2 token options below are set).

The database must have IAM authentication enabled (DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION(type => 'OCI_IAM')) and the OCI identity mapped to a schema (CREATE USER … IDENTIFIED GLOBALLY AS 'IAM_PRINCIPAL_NAME=<user>'). ADB requires mutual TLS, so pair it with the instance wallet. Tokens expire (~1 h); re-mint with oci iam db-token get.

OAuth2 / Microsoft Entra ID bearer token

Version

Since ArpeOracle v0.2.2.

External authentication with a Microsoft Entra ID (Azure AD) access token — no Oracle password, no OCI private key. Set adbc.arpeoracle.access_token to the bearer JWT inline, or adbc.arpeoracle.token_file to a path holding just the JWT; if both are set, the inline access_token wins. These are ADBC options, not connection-string keywords — set them via AdbcDatabaseSetOption (or the equivalent in the language binding), not inside the Server=...;... string.

Setting either option auto-selects the method, so Auth Method does not need to be set explicitly; Auth Method=oauth2 (adbc.arpeoracle.auth_method) also works and is required if you want the driver to fail fast when neither token option ends up set. An explicit Auth Method naming anything other than oauth2 alongside access_token/token_file is rejected as a configuration conflict rather than silently overridden.

No username is configured: Oracle derives the global user from the token's upn claim.

Unlike the OCI IAM token above, a bearer token carries no private key, so there is no signature step: presenting the token is the whole login. Treat the token (and any token_file) as a secret.

Server=adb.<region>.oraclecloud.com:1522/<svc>_low.adb.oraclecloud.com;
sslmode=verify-full;Wallet Location=/home/you/wallet;Wallet Password=...

(with adbc.arpeoracle.access_token or adbc.arpeoracle.token_file set separately as an ADBC option — see above).

Autonomous Database setup: the Application ID URI

On Autonomous Database, the Entra app registration's Application ID URI must be a domain-qualified https:// URI — e.g. https://<tenant>.onmicrosoft.com/<appId> — not Azure's default api://<appId>. The application_id_uri passed to DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION must match it exactly. A non-https Application ID URI makes the ADB reject otherwise-valid tokens with a generic ORA-01017 — Oracle does not surface the real reason, so a misconfigured URI is easy to mistake for a bad token or a blocked account.

Connecting with an Entra token maps to an Autonomous Database global user (AUTHENTICATION_METHOD = TOKEN_GLOBAL) — a user created IDENTIFIED GLOBALLY AS 'AZURE_USER=<upn>'.

Not supported

• NTS/NTLM and Windows integrated authentication (SSPI), on any platform. Use one of the methods above (password, proxy, TLS, OCI IAM token, OAuth2/Entra), all available on both Linux and Windows.