Authentication

How ArpeTeradata logs on to Teradata, and how it protects the session. Every option named here is listed in the Connection option reference.

Two ways to log on

The driver speaks the Teradata wire protocol itself. It can log on in two ways, chosen by adbc.arpeteradata.sslmode:

	Over TLS	On the legacy port
When	The server offers TLS (Teradata 16.20.53.30 or later with a gateway certificate)	Servers without TLS, sslmode=disable, or a fallback from prefer / allow
Port	HTTPS port, 443 by default (https_port)	1025 by default (port)
Who performs the logon	The driver itself	Teradata's CLIv2 library, loaded from your TTU install
Teradata software on the client	None	TTU (CLIv2 and TeraGSS)
Session encrypted	Yes: every request and result goes over TLS 1.2 / 1.3	No: query text and results travel in clear
Mechanisms	TD2, JWT, KRB5, TDNEGO	TD2, LDAP, JWT, KRB5, TDNEGO

In both cases, once logged on the driver runs its own protocol on the session socket: TTU is never involved in a query.

Logon mechanisms

adbc.arpeteradata.logmech selects the mechanism and adbc.arpeteradata.logdata passes its data, as bteq's .logmech and .logdata do. Since v0.3.4; earlier releases log on with TD2 only.

logmech	Username / password	logdata	Logs on as	Over TLS without TTU
unset or TD2 (default)	required	—	the Teradata user	✅
LDAP	the directory user and password	none, or authcid=<user> password=<password> instead	the database user the directory user maps to	❌ legacy port only
JWT	none	token=<JWT>	the database user named in the token	✅
KRB5	none	—	your Kerberos principal (its ticket cache)	✅
TDNEGO	none	—	as KRB5: client and server negotiate, Kerberos when a ticket is there	✅

A mechanism without a TLS logon (LDAP, or TD2 / KRB5 / TDNEGO given logdata) runs on the legacy port, through TTU:

• with sslmode=require, verify-ca or verify-full, the connect fails with NOT_IMPLEMENTED;
• with prefer and allow, the driver skips TLS and goes straight to the legacy port.

logdata may hold a password or a token: the driver never returns it through GetOption, never puts it in error messages, and wipes it from memory when it is replaced or the database is released.

TD2 (username and password)

The classic Teradata logon, and the default. Supply username and password:

Python

db_kwargs = {
    "adbc.arpeteradata.server":   "td.example.com",
    "adbc.arpeteradata.username": "alice",
    "adbc.arpeteradata.password": "<pw>",
    "adbc.arpeteradata.sslmode":  "verify-full",
}

Over TLS, the password is protected by TLS only. That is why verify-ca or verify-full matters: with allow, prefer and require the certificate is not checked, so a party able to intercept the connection could present its own certificate and read the password. On the legacy port, TTU's TD2 exchange encrypts the credentials.

LDAP

Set logmech=LDAP and pass the directory user and password as username and password:

Python

db_kwargs = {
    "adbc.arpeteradata.server":   "td.example.com",
    "adbc.arpeteradata.sslmode":  "disable",
    "adbc.arpeteradata.logmech":  "LDAP",
    "adbc.arpeteradata.username": "jdoe",
    "adbc.arpeteradata.password": "<directory password>",
}

The same credentials can go in logdata instead, with no username: authcid=jdoe password=<password>.

LDAP needs the legacy port and TTU

Teradata's LDAP mechanism always runs its own key exchange, even inside TLS, and no server setting turns it off. ArpeTeradata does not reimplement that exchange, so LDAP logs on through TTU on the legacy port, also on a server that has TLS. Use sslmode=disable (or prefer / allow, which skip TLS for LDAP). To log on over TLS without TTU, use JWT (tokens from an identity provider in front of the directory) or Kerberos (for example Active Directory) instead.

JWT

Set logmech=JWT and logdata=token=<JWT>, with no username or password:

Python

db_kwargs = {
    "adbc.arpeteradata.server":  "td.example.com",
    "adbc.arpeteradata.sslmode": "verify-full",   # TLS, no TTU needed
    "adbc.arpeteradata.logmech": "JWT",
    "adbc.arpeteradata.logdata": "token=" + jwt,
}

• The token's sub claim names the database user. The server checks the signature against the key or issuer configured for its JWT mechanism, and the token's validity period.
• Over TLS the token goes to the server inside TLS. A token is a bearer credential: use verify-ca or verify-full so it only reaches the real server. On the legacy port, TTU encrypts it.
• logdata must have the form token=<JWT>; anything else fails with INVALID_ARGUMENT before any connection. Tokens up to 65000 bytes are sent over TLS.
• A token is valid until it expires: get a fresh one for each connection, or at least before it expires.

Kerberos (KRB5, TDNEGO)

Set logmech=KRB5 (or TDNEGO) with no username and no password: the driver logs on with the Kerberos ticket of the user running the process (single sign-on).

Python

db_kwargs = {
    "adbc.arpeteradata.server":  "td.example.com",
    "adbc.arpeteradata.sslmode": "verify-full",   # TLS, no TTU needed
    "adbc.arpeteradata.logmech": "KRB5",
}

Get the ticket first, for example with kinit user@REALM. Set KRB5CCNAME if the ticket cache is not the default one, and KRB5_CONFIG to use another krb5.conf.

Over TLS (no TTU). The driver runs a standard GSS-API Kerberos exchange itself, with mutual authentication. The Kerberos library is loaded when the first Kerberos logon runs:

• Linux: MIT Kerberos libgssapi_krb5.so.2 from the system library path (package krb5-libs on Red Hat, libgssapi-krb5-2 on Debian and Ubuntu). ARPETERADATA_GSSAPI_LIBRARY names another file.
• Windows: SSPI with the logged-on domain user's credentials (no kinit).

Service principal. The service ticket is for TERADATA/<server>, with <server> exactly as given in adbc.arpeteradata.server (no DNS lookup), in the default realm. Set adbc.arpeteradata.kerberos_spn when you connect by IP address or through a DNS alias, for example TERADATA/td.example.com@EXAMPLE.COM.

Kerberos errors (no library, no ticket, unknown principal) never fall back to the legacy port.

On the legacy port, TTU performs the same exchange. On Debian and Ubuntu, TTU looks for the Kerberos library only in the Red Hat locations, so the logon fails with CLIv2 error 507 (BADLOGMECH) until you link it there:

sudo apt-get install libgssapi-krb5-2
sudo mkdir -p /usr/lib64
sudo ln -s /usr/lib/x86_64-linux-gnu/libgssapi_krb5.so.2 /usr/lib64/libgssapi_krb5.so.2

Server prerequisites

• The mechanism must be enabled and configured in the server's TeraGSS configuration: the directory for LDAP, the verification key or issuer for JWT, the service keytab for Kerberos.

• LDAP, JWT and Kerberos users log on to a database user that has no password check, which a DBA grants once per user:

  GRANT LOGON ON ALL TO <user> WITH NULL PASSWORD;

  Without it, the directory or token check passes, but the gateway then refuses the logon (error 8017).

TLS

sslmode

adbc.arpeteradata.sslmode (default prefer, since v0.2.4) decides which path is tried and whether the certificate is checked:

sslmode	Tries	Falls back	Certificate check
disable	legacy port	—	—
allow	legacy port first, then TLS	yes (to TLS)	none
prefer (default)	TLS first	yes (to the legacy port)	none
require	TLS	no	none
verify-ca	TLS	no	chain (sslca, sslcapath or the system store)
verify-full	TLS	no	chain and host name or IP

• What triggers the fallback. With prefer (and allow), any TLS failure lets the driver try the legacy port: the HTTPS port is closed or silent, the TLS handshake or WebSocket upgrade fails, or the server does not accept the TLS logon. If the legacy port fails too, the error names both reasons.
• What never falls back. A rejected logon (wrong user or password), a certificate that fails verify-ca / verify-full, and Kerberos errors.
• Timeout. With prefer and allow, the TLS attempt is capped at 5 s (or login_timeout if shorter), so a server that does not answer on the HTTPS port leaves time for the legacy port. With require, verify-ca and verify-full, the TLS attempt gets the full login_timeout (60 s by default).
• Versions. TLS 1.2 and 1.3. The driver brings its own OpenSSL, so it does not depend on the host's TLS stack.

When a TLS logon succeeds without a certificate check (allow, prefer, require), the driver prints this line once per process on standard error:

WARNING: ArpeTeradata: TLS logon without server certificate verification (sslmode=<mode>); use sslmode=verify-ca or verify-full to protect the password.

Set ARPETERADATA_NO_TLS_WARNING=1 to silence it.

Where trusted certificates come from

For verify-ca / verify-full, the trusted CAs come from:

1. adbc.arpeteradata.sslca (a PEM file) and/or adbc.arpeteradata.sslcapath (a directory of PEM certificates), when set;
2. otherwise, the system's CA certificates:

Client OS	Without sslca / sslcapath
Linux	OpenSSL's default locations, then the first distribution bundle found: /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (RHEL, Fedora), /etc/pki/tls/certs/ca-bundle.crt, /etc/ssl/certs/ca-certificates.crt (Debian, Ubuntu, Alpine), /etc/ssl/ca-bundle.pem (SUSE), /etc/ssl/cert.pem. Setting SSL_CERT_FILE or SSL_CERT_DIR replaces this search: only the locations you name are used.
Windows	The Windows ROOT certificate store.

A gateway certificate signed by an internal CA is trusted only if that CA is in one of these places: give it with sslca.

Host name check

With verify-full, the host name you connect to must match the certificate; an IP address is matched against the certificate's IP addresses. SNI is sent whenever you connect by name.

Prerequisites (legacy port only)

These apply when the logon runs on the legacy port: sslmode=disable, a server without TLS, or a fallback from prefer / allow. A TLS logon needs none of this.

• Install Teradata Tools and Utilities on the machine that runs the driver. It is available from downloads.teradata.com. Only CLIv2 and TeraGSS are needed; no other TTU utility is used. CLIv2 must be 17.10 or later; TTU 20.00 is the tested release.
• TTU is not shipped with ArpeTeradata and is never redistributed: the driver loads your libcliv2.so (Linux) or wincli32.dll (Windows) at run time.
• The legacy port does not encrypt the session. The credentials are protected by the mechanism (TeraGSS encrypts the TD2 and LDAP password and the JWT; Kerberos sends no password), but query text and results go in clear.

Where the driver looks for TTU

The driver uses the first directory that contains the CLIv2 library.

Linux

TTU does not have to be installed: the driver only needs the folder that holds libcliv2.so. Point ttu_path (or ARPETERADATA_TTU_PATH) at it. A standard install under /opt/teradata/client is found without any option.

1. the database option adbc.arpeteradata.ttu_path;
2. the environment variable ARPETERADATA_TTU_PATH;
3. the directory of the driver library;
4. ../lib64 relative to the driver library;
5. /opt/teradata/client/20.00/lib64;
6. /opt/teradata/client/lib64;
7. the system library path (LD_LIBRARY_PATH, then the ldconfig cache).

Directories 3 to 6 are skipped when they, or the libcliv2.so in them, can be written by group or others; 3 and 4 also when they belong to a user other than root and the user running the process. A skipped directory shows in the error as <directory> (skipped: <reason>).

Windows

TTU for Windows comes as an installer, not as a DLL to copy. Run it and select CLIv2 (and TeraGSS) among the install options. The installer records the location in the registry, where the driver finds it: no option to set. Use ttu_path only for a copy outside a standard install.

1. the database option adbc.arpeteradata.ttu_path;
2. the environment variable ARPETERADATA_TTU_PATH;
3. the directory of the driver DLL, then its bin subdirectory;
4. the TTU installs recorded in the registry, newest version first;
5. %ProgramFiles%\Teradata\Client\<version>\bin, newest version first.

The versions looked for are 20.00, 17.20, 17.10, 17.00, 16.20, 16.10 and 16.00.

If none matches, the connect fails with INVALID_STATE and TTU CLIv2 not found (tried: …). See Troubleshooting → TTU.

warning

ttu_path and ARPETERADATA_TTU_PATH load code into your process. Point them only at a directory that no other user can write to.

The logon on the legacy port is bounded by login_timeout (default 60 s). The limits that come from running CLIv2 inside your process are listed in Connection → Legacy-port logon limits.

Not supported

• LDAP over TLS without TTU (see LDAP).
• Client certificates (mutual TLS): the driver presents no client certificate.
• A logon on the legacy port without TTU. TD2 on the legacy port is an interactive, Teradata-encrypted exchange that only CLIv2 performs. Over TLS the server skips that exchange, which is why the TLS logon needs no TTU.

Errors at logon are listed under Troubleshooting → Logon.