Supported Mechanisms|CLI - Supported Mechanisms - Call-Level Interface Version 2

Teradata® Call-Level Interface Version 2 Reference for Workstation-Attached Systems - 20.00

Deployment
VantageCloud
VantageCore
Edition
Enterprise
IntelliFlex
Lake
VMware
Product
Call-Level Interface Version 2
Release Number
20.00
Published
January 2024
ft:locale
en-US
ft:lastEdition
2024-11-15
dita:mapPath
bmn1691484839905.ditamap
dita:ditavalPath
obe1474387269547.ditaval
dita:id
fvz1470444150352
lifecycle
latest
Product Category
Teradata Tools and Utilities

In general, mechanisms which perform authentication or validation do not require that a database username and password be included as part of the logon string. If these items are supplied in conjunction with such a mechanism, they will effectively be ignored.

The following mechanisms are supported:

Kerberos

In all environments that support Kerberos, the user may supply a userid, password, domain (or a realm), and password. The domain or realm must be supplied separately as mechanism data. After the user’s identity has been verified by Kerberos, an implicit logon will proceed using the tendered userid as the Teradata username.

.logmech KRB5
.logdata joe@domain1@@mypassword
.logon mydbs/

For single-domain environments, the gateway can be configured so that the domain or realm need not be indicated (this is discussed in the relevant gateway documentation).

.logmech KRB5
.logdata joe@@mypassword
.logon mydbs/

Alternatively, a Kerberos-mediated SSO-style logon can be used by omitting the userid, password, and domain or realm, and password. In this case, Kerberos uses the security credentials associated with the current client session.

.logmech KRB5
.logon mydbs/

If required, the user may include Teradata accounting information as part of .logon command as follows:

.logmech KRB5
.logdata joe@domain1@@mypassword
.logon mydbs/,,2345889909

or

.logmech KRB5
.logdata joe@@mypassword
.logon mydbs/,,2345889909

or

.logmech KRB5
.logon mydbs/,,2345889909

In all of the previous cases, there must exist a Teradata username defined in the target database that matches the actual or derived userid and, further, that username must have previously been granted the logon with null password privilege. The special “dbc” username cannot be used with this mechanism because “dbc” cannot be granted the logon with null password privilege (the database will return error 3790 in this case).

SPNEGO

The database employs the Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) to provide confidentiality and integrity while supporting non-LDAP external authentication for users logging on to the database through Windows .NET applications. The SPNEGO mechanism functions almost identically to the KRB5 mechanism, except that KRB5 cannot be used in a Windows .Net environment. See Kerberos.

LDAP

The LDAP mechanism allows a user to be authenticated through LDAP and, optionally, to assume a role or user identity other than his or her own, as allowed by the appropriate directory settings.

The user may supply a userid, password, and domain or realm. The exact contents of the LDAP .logdata information necessarily depends largely upon how the site is using LDAP, how LDAP has been configured, etc. The following samples are only generic examples. After the user’s identity has been verified by LDAP, an implicit logon will proceed using the userid as the Teradata username. Brackets denote optional fields and commands.

.logmech LDAP
.logdata authcid=joe password=password [realm=myrealm]
.logon mydbs/

.logmech LDAP
.logdata joe[@myrealm]@@password
.logon mydbs/

.logmech LDAP
[.logdata realm=myrealm]
.logon mydbs/joe,password

If required, the user may include Teradata accounting information as part of .logon command as follows:

.logmech LDAP
.logdata authcid=joe password=password realm=myrealm
.logon mydbs/,,2345889909

If the directory maps the userid to a specific Teradata username, that username must be defined in the target database and must have previously been granted the logon with null password privilege. After the user’s identity has been verified by LDAP, an implicit logon will proceed using the tendered userid as the Teradata username. The special “dbc” username cannot be used with this mechanism because “dbc” cannot be granted the logon with null password privilege (the database will return error 3790 in this case).

If the directory does not map the userid to a specific Teradata username, a generic username will be used and a role assigned. The role will be derived from information contained in the directory. Logon will be by extended logon.

BROWSER

The BROWSER mechanism allows a user to be authenticated using a federated identity provider that supports the OpenID Connect protocol. Browser authentication is supported on Windows and Mac OS only. The database must be configured with Identity Provider information for Federated Authentication. This task is covered in the reference Teradata Vantage™ - Analytics Database Security Administration, B035-1100.

The application should not provide username, password, or logon mechanism data when using browser authentication. Instead, CLI will launch the default browser and direct the user to the logon page for the identity provider.

.set logmech BROWSER
    .logon mydbs/

    UserId:
    Password:

In the previous example using interactive BTEQ, when prompted for UserId and Password, hit Enter. The default browser will launch and prompt the user for a UserId and Password. Once authenticated, the logon process will complete successfully.

TD2

TD2 represents the Teradata mechanism. It does not perform any authentication. Rather, it facilitates encryption/decryption for sessions connected absent the mediation of extended security. Therefore, a valid Teradata username and password are always required.

For TD2, there must be no .logdata parameter; if one is passed to CLIv2, it will be ignored.

TD2 is shipped as the default mechanism for the server-based XML config file.

.logmech TD2
.logon mydbs/joe,password

BEARER

The BEARER mechanism provides support for client authentication with a federated identity provider using client credentials grant and a JWT bearer token. This mechanism is intended for service accounts and automated jobs, not interactive users. The database must be configured with Identity Provider information for Federated Authentication. This task is covered in the reference Teradata Vantage™ - Analytics Database Security Administration, B035-1100. The database user must have the “logon with null password” permission enabled.

The application must not provide username, password, or logon mechanism data when using bearer authentication. The following connection string parameters are used during bearer authentication:

Parameters Description
jws_private_key Required. Location of the file that contains the JWS private key obtained from your identity provider. Can be in PEM or JWK format.
jws_cert Optional. Use if your identity provider requires an “x5t” header thumbprint.
oidc_clientid Optional. Commonly used to override the default client ID when using bearer authentication.
oidc_scope Optional. Used to override the default scope.
jws_algorithm Optional. Default is RS256.

For example, using bearer authentication a BTEQ script for an automated job:

.set logmech BEARER
.set connectstring jws_private_key=bearer_pkey.pem;oidc_clientid=app_clientid
.logon mydbs/
<script commands and SQL>
.quit

CLI will contact the identity provider and use the information in the connection string to obtain a JWT access token. No user interaction is required. Once authenticated, the logon process will complete successfully.

CRED

The CRED mechanism provides support for client authentication with a federated identity provider using client credentials grant and HTTP POST data provided by the user. This mechanism is intended for service accounts and automated jobs, not interactive users. The database must be configured with Identity Provider information for Federated Authentication. This task is covered in the reference Teradata Vantage™ - Analytics Database Security Administration, B035-1100. The database user must have the “logon with null password” permission enabled.

The application must not provide username, password, client ID, and scope when using CRED authentication. The logon mechanism data pointer should contain the client credentials grant request HTTP POST form data encoded as Content-Type application/x-www-form-urlencoded.

For example, using a BTEQ script for an automated job:

.set logmech CRED
.set logdata grant_type=client_credentials&scope=openid&client_id=app_clientid&client_secret=<client secret>
.logon mydbs/
<script commands and SQL>
.quit

CLI will contact the identity provider and use the information in the logon mechanism data to obtain a JWT access token. No user interaction is required. Once authenticated, the logon process will complete successfully.

CODE

The CODE mechanism is OAuth 2.0 Device Authorization Grant, commonly known as the Device Flow. It enables applications with limited input capabilities to secure user authorization.

The Device Flow involves an application requesting a unique code from the server, which is then shown to the user. Instructions are provided for the user to enter this code on a secondary device, such as a smartphone or a computer, via a web browser. After entering the code, the user logs in and authorizes the device through the authorization server, which then communicates permission to the application.

This method enhances security by avoiding direct credential input into the application and improves usability with limited input options.

The database must be configured with Identity Provider information for Federated Authentication. This task is covered in the reference Teradata Vantage™ - Analytics Database Security Administration, B035-1100. The database user must have the “logon with null password” permission enabled.

The application must not provide username, password, or logon mechanism data when using device-flow. The following connection string parameters are used during device-flow:

Parameters Description
code_append_file Optional.

<filename>: appends the verification URL and code to the specified file if the file already exists or creates a new file if the specified file does not exist.

-out: prints the verification URL and code to standard out (stdout)

-err: prints the verification URL and code to standard error (stderr)

oidc_clientid Optional. Used to override the default client id.
oidc_scope Optional. Used to override the default scope.

For example, using device-flow authentication a BTEQ script for an interactive session:

.set logmech CODE
.set connectstring <optional connection string>
.logon mydbs/
<type the commands interactively>
.quit

The CLI interacts with the identity provider, leveraging the optional connection string to acquire a JWT access token. Given the user interaction required by device-flow, it is best utilized in the application's interactive mode, like BTEQ interactive mode.

By default, on non-Windows systems, the URL and code are displayed on the terminal (/dev/tty); however, on Windows, they appear in a new pop-up window. If a pop-up window fails to appear for some reason, the information will be directly displayed on the screen (stdout).