OpenText Analytics Database 26.2.x – Client authentication

Security-and-Authentication: Default authentication records

Mon, 01 Jan 0001 00:00:00 +0000

OpenText™ Analytics Database automatically creates the following default authentication records and grants them to the public role. These have the lowest possible priority (-1), so user-created authentication records take priority over these default records:

=> SELECT auth_name,is_auth_enabled,auth_host_type,auth_method,auth_priority,is_fallthrough_enabled FROM client_auth;
         auth_name         | is_auth_enabled | auth_host_type | auth_method | auth_priority | is_fallthrough_enabled
---------------------------+-----------------+----------------+-------------+---------------+------------------------
 default_hash_network_ipv4 | True            | HOST           | PASSWORD    |            -1 | False
 default_hash_network_ipv6 | True            | HOST           | PASSWORD    |            -1 | False
 default_hash_local        | True            | LOCAL          | PASSWORD    |            -1 | False
(3 rows)

Note

Do not use the password method for your custom authentication records. If you want to use password-based authentication for your custom authentication records, use hash instead.

If no authentication records are defined (and the default authentication records are dropped), only the dbadmin and users without passwords can access the database. For details, see Implicit authentication.

Security-and-Authentication: Configuring client authentication

Mon, 01 Jan 0001 00:00:00 +0000

You can restrict how database users can connect with authentication records. The OpenText™ Analytics Database uses client authentication to establish the identity of the connecting client and determines whether that client is authorized to connect to the database using the supplied credentials and from their host address.

Basic authentication configuration workflow

In general, the workflow for configuring client authentication is as follows:

Create an authentication record. Authentication records are enabled automatically after creation. For details, see Creating authentication records.
Grant the authentication to a user or role.

To view existing authentication records, query the system table CLIENT_AUTH.

IPv4 and IPv6 for client authentication

The database supports clients using either the IPv4 or the IPv6 protocol to connect to the database server. Internal communication between database servers must consistently use one address family (IPv4 or IPv6). The client, however, can connect to the database from either type of IP address.

If the client will be connecting from either IPv4 or IPv6, you must create two authentication methods, one for each address. Any authentication method that uses HOST authentication requires an IP address.

For example, the first statement allows users to connect from any IPv4 address. The second statement allows users to connect from any IPv6 address:

=> CREATE AUTHENTICATION <name> METHOD 'gss' HOST '0.0.0.0/0'; --IPv4
=> CREATE AUTHENTICATION <name> METHOD 'gss' HOST '::/0'; --IPv6

If you are using a literal IPv6 address in a URL, you must enclose the IPv6 address in square brackets as shown in the following examples:

=> ALTER AUTHENTICATION Ldap SET host='ldap://[1dfa:2bfa:3:45:5:6:7:877]';
=> ALTER AUTHENTICATION Ldap SET host='ldap://[fdfb:dbfa:0:65::177]';
=> ALTER AUTHENTICATION Ldap SET host='ldap://[fdfb::177]';
=> ALTER AUTHENTICATION Ldap SET host='ldap://[::1]';
=> ALTER AUTHENTICATION Ldap SET host='ldap://[1dfa:2bfa:3:45:5:6:7:877]:5678';

If you are working with a multi-node cluster, any IP/netmask settings in (HOST, HOST TLS, HOST NO TLS) must match all nodes in the cluster. This setup allows the database owner to authenticate with and administer every node in the cluster. For example, specifying 10.10.0.8/30 allows a CIDR address range of 10.10.0.8-10.10.0.11.

For detailed information about IPv6 addresses, see RFC 1924 and RFC 2732.

Supported client authentication methods

The database supports the following client authentication methods:

trust: Users can authenticate with a valid username (that is, without a password).
reject: Rejects the connection attempt.
hash: Users must provide a valid username and password. For details, see Hash authentication.
gss: Authorizes clients that connect to the database with an MIT Kerberos implementation. The Key Distribution Center (KDC) must support Kerberos 5 using the GSS-API. Non-MIT Kerberos implementations must use the GSS-API. For details, see Kerberos authentication.
ident: Authenticates the client against a username on an Ident server. For details, see Ident authentication.
ldap: Authenticates a client and their username and password with an LDAP or Active Directory server. For details, see LDAP authentication.
tls: Authenticates clients that provide a certificate with a Common Name (CN) that specifies a valid database username. The database must be configured for mutual mode TLS to use this method. For details, see TLS authentication
oauth: Authenticates a client with an access token. For details, see OAuth 2.0 authentication.

Local and host authentication

You can define a client authentication method as:

Local: Local connection to the database.
Host: Remote connection to the database from different hosts, each with their own IPv4 or IPv6 address and host parameters. For more information see IPv4 and IPv6 for Client Authentication above.

Some authentication methods can only be designated as local or host, as listed in this table:

Authentication Method	Local?	Host?
`gss` (Kerberos)	No	Yes
`ident`	Yes	No
`ldap`	Yes	Yes
`hash`	Yes	Yes
`reject`	Yes	Yes
`trust`	Yes	Yes
`tls`	No	Yes
`oauth`	Yes	Yes

Authentication for chained users and roles

The database supports creating chained users and roles, where you can grant ROLE2 privileges to ROLE1. All users in ROLE1 use the same authentication assigned to ROLE2. For example:

=> CREATE USER user1;
=> CREATE ROLE role1;
=> CREATE ROLE role2;
=> CREATE AUTHENTICATION h1 METHOD 'hash' LOCAL;
=> GRANT AUTHENTICATION h1 to role2;
=> GRANT role2 to role1;
=> GRANT role1 to user1;

The user and role chain in the example above can be illustrated as follows:

auth1 -> role2 -> role1 -> user1

In this example, since role2 privileges are granted to role1 you only need to grant authentication to role2 to also enable it for role1.

Security-and-Authentication: Fallthrough authentication

Mon, 01 Jan 0001 00:00:00 +0000

Normally, if a user fails to authenticate with the first chosen authentication record, the user is rejected. However, certain authentication methods can be specified to instead, upon failure, "fall through" to an authentication record with a lower priority. This can be useful, for example, for using multiple LDAP search attributes.

Authentication fallthrough is disabled by default for new records.

Another way to bypass method priority or implement fallthrough authentication is to implement it on the client instead. For details, see Authentication filtering.

Authentication method compatibility

The following table shows each authentication method's compatibility with fallthrough authentication. A value of "yes" indicates that the method in the column can fall through and validate the row method it falls through to. A value of "no" indicates that you cannot fall through to it and authentication ends.

A value of "-" (dash) indicates that while fallthrough works, it has no meaningful effect. For example, a hash authentication record can fall through to another hash authentication record, but authentication will always fail because you cannot fall through to a correct password:

Column falls through to row	ldap	hash	tls	ident	oauth	gss	trust	reject
ldap	yes	yes	yes	yes	no	no	no	no
hash	yes	-	yes	yes	no	no	no	no
tls	yes	yes	-	yes	no	no	no	no
ident	yes	yes	yes	yes	no	no	no	no
oauth	no	no	no	no	no	no	no	no
gss	no	no	no	no	no	no	no	no
trust	yes	yes	yes	yes	no	no	no	no
reject	yes	yes	yes	yes	no	no	no	no

For example, suppose the user Bob was granted the following authentication record with fallthrough enabled:

=> CREATE AUTHENTICATION v_tls_auth METHOD 'tls' HOST TLS '0.0.0.0/0' FALLTHROUGH;

In addition, Bob has the public role, and therefore has the default authentication records:

=> SELECT auth_name,is_auth_enabled,auth_host_type,auth_method,auth_priority,is_fallthrough_enabled FROM client_auth;
         auth_name         | is_auth_enabled | auth_host_type | auth_method | auth_priority | is_fallthrough_enabled
---------------------------+-----------------+----------------+-------------+---------------+------------------------
 default_hash_network_ipv4 | True            | HOST           | PASSWORD    |            -1 | False
 default_hash_network_ipv6 | True            | HOST           | PASSWORD    |            -1 | False
 default_hash_local        | True            | LOCAL          | PASSWORD    |            -1 | False
(3 rows)

If Bob, connecting from a remote address, fails to authenticate with v_tls_auth, Vertica attempts to authenticate him with the next (in order of priority) authentication record, default_hash_network_ipv4.

Logging authentication failures

Login failures are only logged if the user is rejected after all granted authentication records have failed. Only the final failure is logged.

For example, suppose a user is granted both tls and password authentication records, and the tls record falls through to the password record.

If the user fails to authenticate with both the tls record and the password record, then only the password failure is logged in LOGIN_FAILURES.

However, if the user fails to authenticate with the tls record, but succeeds with the password record, then no failure is logged in LOGIN_FAILURES because the user was not rejected at the end of the record chain.

Examples

To enable fallthrough on a new authentication record, use CREATE AUTHENTICATION:

=> CREATE AUTHENTICATION v_tls_auth METHOD 'tls' HOST TLS '0.0.0.0/0' FALLTHROUGH;

To toggle fallthrough on an existing authentication record, use ALTER AUTHENTICATION:

=> ALTER AUTHENTICATION v_tls_auth NO FALLTHROUGH; -- disable
=> ALTER AUTHENTICATION v_tls_auth FALLTHROUGH; -- enable

Security-and-Authentication: Authentication filtering

Mon, 01 Jan 0001 00:00:00 +0000

You can filter for and authenticate with authentication records that use a particular method by specifying the credentials for that method. This process skips any higher-priority, non-trust authentication records.

If the selected record fails and fallthrough is enabled, Vertica uses to the record with the next highest priority.

If you provide the credentials for an authentication method for which you have not been granted, Vertica instead attempts to authenticate you with the highest priority authentication record.

The following table shows the credentials the client provides and the requested authentication method in descending filter priority. If you attempt to provide more than one type of credential, your client selects and sends the one with the higher priority:

Credentials sent by client	Requested authentication method
OAuthRefreshToken or OAuthAccessToken	`oauth`
Non-default KerberosServiceName or KerberosHostname	`gss`
Username, Password	`ldap`, `hash`, `ident`, `trust`, `tls`

For example, if a client provides a username and password for user Alice, and the Alice has oauth, ldap, and hash records, then Vertica attempts to authenticate the client with ldap or hash, whichever has the higher priority.

Similarly, if Alice instead provides an OAuthAccessToken, username, and password, then Vertica attempts to authenticate her with the oauth record because it has a higher filter priority.

However, if Alice provides a KerberosHostname, Vertica attempts to authenticate her with the highest priority authentication record between her oauth, ldap, and hash records.

Client-side fallthrough authentication

A workaround for the incompatibility of certain authentication methods with fallthrough authentication is to use authentication filtering to manually fall through to the proper authentication record by detecting the initial authentication failure, and then making a new connection attempt with a different set of credentials.

For example, oauth and hash cannot fall through to each other, so if a user is granted authentication records with these methods, they can only authenticate with the higher priority record. As a workaround, you can detect the authentication failure with oauth and then filter for hash in another connection attempt. Doing this programmatically depends on the client. In JDBC, you can catch SQLInvalidAuthorizationSpecException and then try to reconnect in the exception handler. In ODBC, you can check the return value of SQLDriverConnect():

// error checking omitted for brevity
    SQLHENV hdlEnv;
    SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlEnv);
    SQLHDBC hdlDbc;
    SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION,
                (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER);
    SQLAllocHandle(SQL_HANDLE_DBC, hdlEnv, &hdlDbc);
    SQLRETURN ret = SQLDriverConnect(hdlDbc, NULL, (SQLCHAR *)("DSN=VerticaDSN;OAuthAccessToken=" + accessToken + ";OAuthRefreshToken=" + refreshToken + ";OAuthClientSecret=" + clientSecret).c_str(), SQL_NTS, NULL, 0, NULL, false);

    if (!SQL_SUCCEEDED(ret))
    {
        std::cout << "Could not connect to database with OAuth, retrying with hash authentication" << std::endl;
        reportError <SQLHDBC>(SQL_HANDLE_DBC, hdlDbc);
        SQLAllocHandle(SQL_HANDLE_DBC, hdlEnv, &hdlDbc);
        const char* dsnName = "ExampleDB";
        const char* userID = "Alice";
        const char* passwd = "mypassword";
        SQLConnect(hdlDbc, (SQLCHAR*)dsnName,SQL_NTS,(SQLCHAR*)userID,SQL_NTS,(SQLCHAR*)passwd, SQL_NTS);
    }

Examples

In the following example, the user Bob is granted two authentication records: one that uses Kerberos authentication (gss) and another that uses password authentication (hash):

=> SELECT auth_name, auth_host_type, auth_method FROM client_auth;
       auth_name     | auth_host_type | auth_method
---------------------+----------------+-------------
 v_hash              | HOST           | HASH
 v_kerberos          | HOST           | GSS
(2 rows)

Bob attempts to authenticate with Kerberos, but fails (the exact error message varies):

$ vsql -h vertica_db.example.com -K vcluster.example.com -U Bob
vsql: GSSAPI continuation error: Unspecified GSS failure.  Minor code may provide more information
GSSAPI continuation error: No Kerberos credentials available (default cache: KEYRING:persistent:0)

Bob notices the failure. The steps involved in detecting this programmatically depend on your client.
An authentication record that uses gss cannot fall through to one that uses hash, so the only way for Bob to authenticate to the database is to filter for the hash by providing the username and password:
```
=> vsql -h vertica_db.example.com -U Bob -w 'mypassword'
```

To implement client-side fallthrough authentication, check the initial connection/authentication attempt for errors and then create a new connection in the error handler. For example, the user Alice is granted oauth and hash authentication records:

=> SELECT auth_name, auth_host_type, auth_method FROM client_auth;
       auth_name     | auth_host_type | auth_method
---------------------+----------------+-------------
 v_oauth             | HOST           | OAUTH
 v_hash              | HOST           | HASH
(2 rows)

Security-and-Authentication: Implicit authentication

Mon, 01 Jan 0001 00:00:00 +0000

OpenText™ Analytics Database has implicit (that is, not reflected in the CLIENT_AUTH system table) authentication records reserved for the dbadmin and users without passwords. These records cannot be dropped.

For the dbadmin user:

The trust method is used if all of the following are true:
- The dbadmin does not have a password.
- The connection is local (that is, from a database node).
The hash method is used if all of the following are true:
- The dbadmin has a password.
- The connection is local (that is, from a database node).

For a non-dbadmin user, the trust method is used if all of the following are true:

The user does not have a password.
No custom (that is, non-default) authentication methods are enabled.

Security-and-Authentication: Dbadmin authentication access

Mon, 01 Jan 0001 00:00:00 +0000

The dbadmin user must have access to the database at all times. OpenText™ Analytics Database automatically ensures that a client can authenticate as the dbadmin from a LOCAL connection.

If you need to authenticate as the dbadmin from a remote connection, the dbadmin must have a password. You can use the following methods:

Use fallthrough authentication.
Create a custom, dbadmin-specific authentication method.

Authenticating from a local connection

You can always implicitly authenticate as the dbadmin from a local connection. These dbadmin-specific authentication records are implicit, so they are not listed in the CLIENT_AUTH system table, and cannot be dropped.

If the dbadmin user does not have a password, then the database authenticates them with the trust method. Otherwise, the database authenticates them with the password method.

In this example, the dbadmin did not have a password and connected to the database from a local connection:

=> SELECT authentication_method, client_authentication_name FROM vs_sessions;
 authentication_method | client_authentication_name
-----------------------+----------------------------
 ImpTrust              | default: Implicit Trust

Authenticating from a remote connection

Fallthrough authentication

The database automatically creates the following authentication records and grants them to the public role (for details, see Client authentication):

=> SELECT auth_name,is_auth_enabled,auth_host_type,auth_method,auth_priority,is_fallthrough_enabled FROM client_auth;
         auth_name         | is_auth_enabled | auth_host_type | auth_method | auth_priority | is_fallthrough_enabled
---------------------------+-----------------+----------------+-------------+---------------+------------------------
 default_hash_network_ipv4 | True            | HOST           | PASSWORD    |            -1 | False
 default_hash_network_ipv6 | True            | HOST           | PASSWORD    |            -1 | False
 default_hash_local        | True            | LOCAL          | PASSWORD    |            -1 | False
(3 rows)

These default authentication records ensure that all users with the public role (which includes dbadmin) have access to the database, provided that any custom authentication records are set to fall through (disabled by default) to the default records.

For example, the following ldap authentication enables fallthrough, so if the LDAP server is down, users can still authenticate with password authentication (as defined by the default records).

=> CREATE AUTHENTICATION ldap1 METHOD 'ldap' LOCAL FALLTHROUGH;
=> ALTER AUTHENTICATION ldap1 SET host='ldap://localhost:5389',
    binddn='cn=Manager,dc=example,dc=com',
    bind_password='password',
    basedn='ou=dev,dc=example,dc=com',
    search_attribute='cn';

Custom authentication records

A dbadmin-specific authentication record should:

Use the hash authentication method (so authentication is not dependent on some external service).
Have a high priority (e.g. 10,000) so it supersedes all other authentication records.

The following example creates an authentication record v_dbadmin_hash and grants it to the dbadmin user. The hash method indicates that the dbadmin must provide a password when logging in. The HOST '0.0.0.0/0' access method indicates that the dbadmin can connect remotely from any IPv4 address:

=> CREATE AUTHENTICATION v_dbadmin_hash METHOD 'hash' HOST '0.0.0.0/0';
=> ALTER AUTHENTICATION v_dbadmin_hash PRIORITY 10000;
=> GRANT AUTHENTICATION v_dbadmin_hash TO dbadmin;

If you want to authenticate as the dbadmin from a local connection, but want to use an authentication record with the HOST access method, specify the --host option with the hostname or IP address of the database:

$ vsql database_name user --host hostname_or_ip;

Security-and-Authentication: Creating authentication records

Mon, 01 Jan 0001 00:00:00 +0000

You can manage client authentication records with vsql. You must be connected to the database as a supseruser.

Important

You cannot modify client authentication records using the Administration Tools. The Administration Tools interface allows you to modify the contents of the vertica.conf file. However, OpenText™ Analytics Database ignores any client authentication information stored in that file.

Create an authentication records, specifying:
- The name of the authentication record.
- The authentication method, one of the following:
  - trust: Users can authenticate with a valid username (that is, without a password).
  - reject: Rejects the connection attempt.
  - hash: Users must provide a valid username and password. For details, see Hash authentication.
  - gss: Authorizes clients that connect to the database with an MIT Kerberos implementation. The Key Distribution Center (KDC) must support Kerberos 5 using the GSS-API. Non-MIT Kerberos implementations must use the GSS-API. For details, see Kerberos authentication.
  - ident: Authenticates the client against a username on an Ident server. For details, see Ident authentication.
  - ldap: Authenticates a client and their username and password with an LDAP or Active Directory server. For details, see LDAP authentication.
  - tls: Authenticates clients that provide a certificate with a Common Name (CN) that specifies a valid database username. The database must be configured for mutual mode TLS to use this method. For details, see TLS authentication
  - oauth: Authenticates a client with an access token. For details, see OAuth 2.0 authentication.
- The access method, one of the following, which specify the allowed connection type:
  - LOCAL: Authenticates users or applications that attempt to connect from the same node that the database is running on.
  - HOST: Authentications users or applications that attempt to connect from a node that has a different IPv4 or IPv6 address than the database. You can use TLS or NO TLS to specify an encrypted or plaintext connection, respectively.
- Whether to enable Fallthrough authentication (disabled by default).
Grant the authentication record to a user or role.

Examples

The following examples show how to create authentication records.

Create authentication method localpwd to authenticate users who are trying to log in from a local host using a password:

=> CREATE AUTHENTICATION localpwd METHOD 'hash' LOCAL;

Create authentication method v_ldap that uses LDAP over TLS to authenticate users logging in from the host with the IPv4 address 10.0.0.0/23:

=> CREATE AUTHENTICATION v_ldap METHOD 'ldap' HOST TLS '10.0.0.0/23';

Create authentication method v_kerberos to authenticate users who are trying to connect from any host in the networks 2001:0db8:0001:12xx:

=> CREATE AUTHENTICATION v_kerberos METHOD 'gss' HOST '2001:db8:1::1200/56';

Create authentication method ldap_mfa that uses LDAP to authenticate users logging in from the host ldap.vertica.local and enforces multi-factor authentication:

=> CREATE AUTHENTICATION ldap_mfa TYPE LDAP HOST 'ldap.vertica.local' ENFORCEMFA;

Create authentication records with multi-factor authentication.

=> CREATE AUTHENTICATION ad_auth METHOD 'ldap' HOST '0.0.0.0/0' ENFORCEMFA;

Create authentication method pw_local to authenticate users who are trying to log in from a local host using a password with multi-factor authentication:

=> CREATE AUTHENTICATION pw_local method 'password' local enforcemfa;

Create authentication method pw_ipv4 to authenticate users logging in from the host with the IPv4 address 0.0.0.0 using a password and enforce multi-factor authentication:

=> CREATE AUTHENTICATION pw_ipv4 method 'password' host '0.0.0.0/0' enforcemfa;

Create authentication method pw_ipv6 to authenticate users logging in from a host with the IPv6 address using a password and enforce multi-factor authentication:

=> CREATE AUTHENTICATION pw_ipv6 method 'password' host '::/0' enforcemfa;

Create authentication method v_krb to authenticate users logging in from the host gss with the IPv4 address 0.0.0.0 and enforce multi-factor authentication:

=> CREATE AUTHENTICATION v_krb method 'gss' host '0.0.0.0/0' ENFORCEMFA;

Create authentication method v_oauth to authenticate users logging in from the host oauth with the IPv4 address 0.0.0.0 and enforce multi-factor authentication:

=> CREATE AUTHENTICATION v_oauth METHOD 'oauth' HOST '0.0.0.0/0' ENFORCEMFA;

The following authentication record v_oauth authenticates users from any IP address by contacting the identity provider to validate the OAuth token (rather than a username and password) and uses the following parameters:

validate_type: The method used to validate the OAuth token. This should be set to IDP (default) to validate the OAuth token for confidential clients.
client_id: The client in the identity provider.
client_secret: The client secret generated by the identity provider. This is required if validate_type is IDP.
discovery_url: Also known as the OpenID Provider Configuration Document, OpenText™ Analytics Database uses this endpoint to retrieve information about the identity provider's configuration and other endpoints (Keycloak only).
introspect_url: Used by the database to introspect (validate) access tokens. You must specify the introspect_url if you do not specify the discovery_url and are not using JWT validation.

If discovery_url and introspect_url are both set, discovery_url takes precedence. The following example sets both for demonstration purposes; in general, you should prefer to set the discovery_url:

=> CREATE AUTHENTICATION v_oauth METHOD 'oauth' HOST '0.0.0.0/0';
=> ALTER AUTHENTICATION v_oauth SET validate_type = 'IDP';
=> ALTER AUTHENTICATION v_oauth SET client_id = 'vertica';
=> ALTER AUTHENTICATION v_oauth SET client_secret = 'client_secret';
=> ALTER AUTHENTICATION v_oauth SET discovery_url = 'https://203.0.113.1:8443/realms/myrealm/.well-known/openid-configuration';
=> ALTER AUTHENTICATION v_oauth SET introspect_url = 'https://203.0.113.1:8443/realms/myrealm/protocol/openid-connect/token/introspect';

Alternatively, if your identity provider supports the OpenID Connect protocol and your client is public, the database can use JWT validation, where the database validates OAuth tokens by verifying that it was signed by the identity provider's private key.

The database does not contact the identity provider for JWT validation, unless jwt_jwks_url is configured, in which case the database retrieves signing keys from the identity provider's JWK endpoint.

JWT validation requires the following parameters:

validate_type: The method used to validate the OAuth token. This should be set to JWT to validate the OAuth token for public clients.
jwt_issuer: The issuer of the OAuth token. For Keycloak, this is the token endpoint.
jwt_user_mapping: The name of the database user.

At least one of the following key parameters must be set:

jwt_rsa_public_key: In PEM format, the RSA public key used to sign the client's OAuth token. The database uses this to validate the OAuth token. If your identity provider does not natively provide PEM-formatted public keys, you must convert them to PEM format. For example, keys retrieved from an Okta endpoint are in JWK format and must be converted.
jwt_ec_public_key: In PEM format, the EC public key used to sign the client's OAuth token. This is the EC key equivalent of jwt_rsa_public_key.
jwt_jwks_url: URL to retrieve JWKs from the identity provider. All keys returned by this endpoint are used when validating a user logging in with a JWT. This eliminates the need to manually update keys during identity provider key rotation. For Keycloak, the URL format is https://keycloak.host/realms/realm/protocol/openid-connect/certs.

You can also specify the following parameters to define a whitelist based on fields of the OAuth token:

jwt_accepted_audience_list: Optional, a comma-delimited list of values to accept from the client JWT's aud field. If set, tokens must include in aud one of the accepted audiences to authenticate.
jwt_accepted_scope_list: Optional, a comma-delimited list of values to accept from the client JWT's scope field. If set, tokens must include in scope at least one of the accepted scopes to authenticate.

The following authentication record v_oauth_jwt authenticates users from any IP address by verifying that the client's OAuth token was signed by the identity provider's private key. It uses a static RSA public key and also requires the user to provide the proper values in the token's aud and scope fields:

=> CREATE AUTHENTICATION v_oauth_jwt METHOD 'oauth' HOST '0.0.0.0/0';
=> ALTER AUTHENTICATION v_oauth_jwt SET validate_type = 'JWT';
=> ALTER AUTHENTICATION v_oauth_jwt SET jwt_rsa_public_key = '-----BEGIN PUBLIC KEY-----public-key-value-----END PUBLIC KEY-----';
=> ALTER AUTHENTICATION v_oauth_jwt SET jwt_issuer = 'https://keycloak.host/realms/realm_name';
=> ALTER AUTHENTICATION v_oauth_jwt SET jwt_user_mapping = 'preferred_username';
=> ALTER AUTHENTICATION v_oauth_jwt SET jwt_accepted_audience_list = 'vertica,local';
=> ALTER AUTHENTICATION v_oauth_jwt SET jwt_accepted_scope_list = 'email,profile,user';

Alternatively, you can use jwt_jwks_url to automatically retrieve signing keys from the identity provider's JWK endpoint. This approach eliminates the need to manually update keys during key rotation:

=> CREATE AUTHENTICATION v_oauth_jwks METHOD 'oauth' HOST '0.0.0.0/0';
=> ALTER AUTHENTICATION v_oauth_jwks SET validate_type = 'JWT';
=> ALTER AUTHENTICATION v_oauth_jwks SET jwt_jwks_url = 'https://keycloak.host/realms/realm_name/protocol/openid-connect/certs';
=> ALTER AUTHENTICATION v_oauth_jwks SET jwt_issuer = 'https://keycloak.host/realms/realm_name';
=> ALTER AUTHENTICATION v_oauth_jwks SET jwt_user_mapping = 'preferred_username';

For example, to reject all plaintext client connections, specify the reject authentication method and the HOST NO TLS access method as follows:

=> CREATE AUTHENTICATION RejectNoSSL METHOD 'reject' HOST NO TLS '0.0.0.0/0';  --IPv4
=> CREATE AUTHENTICATION RejectNoSSL METHOD 'reject' HOST NO TLS '::/0';       --IPv6

Security-and-Authentication: Modifying authentication records

Mon, 01 Jan 0001 00:00:00 +0000

To modify existing authentication records, you must first be connected to your database. The following examples show how to make changes to your authentication records. For more information see ALTER AUTHENTICATION.

Rename an authentication method

Rename the v_kerberos authentication method to K5, and enable it. All users who have been associated with the v_kerberos authentication method are now associated with the K5 method granted instead.

=> ALTER AUTHENTICATION v_kerberos RENAME TO K5 ENABLE;

Specify a priority for an authentication method

Specify a priority of 10 for K5 authentication:

=> ALTER AUTHENTICATION K5 PRIORITY 10;

For more information see Authentication record priority.

Change a parameter

Set the system_users parameter for ident1 authentication to root:

=> CREATE AUTHENTICATION ident1 METHOD 'ident' LOCAL;
=> ALTER AUTHENTICATION ident1 SET system_users='root';

Change the IP address and specify the parameters for an LDAP authentication method named Ldap1.

In this example, you specify the bind parameters for the LDAP server. OpenText™ Analytics Database connects to the LDAP server, which authenticates the database client. If the authentication succeeds, the database authenticates any users who have been granted the Ldap1 authentication method on the designated LDAP server:

=> CREATE AUTHENTICATION Ldap1 METHOD 'ldap' HOST '172.16.65.196';
=> ALTER AUTHENTICATION Ldap1 SET host='ldap://172.16.65.177',
   binddn_prefix='cn=', binddn_suffix=',dc=qa_domain,dc=com';

Change the IP address, and specify the parameters for an LDAP authentication method named Ldap1. Assume that the database does not have enough information to create the distinguished name (DN) for a user attempting to authenticate. Therefore, in this case, you must specify to use LDAP search and bind:

=> CREATE AUTHENTICATION LDAP1 METHOD 'ldap' HOST '172.16.65.196';
=> ALTER AUTHENTICATION Ldap1 SET host='ldap://172.16.65.177',
basedn='dc=qa_domain,dc=com',binddn='cn=Manager,dc=qa_domain,
dc=com',search_attribute='cn',bind_password='secret';

Change the associated method

Change the localpwd authentication from trust to hash:

=> CREATE AUTHENTICATION localpwd METHOD 'trust' LOCAL;
=> ALTER AUTHENTICATION localpwd METHOD 'hash';

ALTER AUTHENTICATION validates the parameters you enter. If there are errors, it disables the authentication method that you are trying to modify.

Using the administration tools

The advantages of using the Administration Tools are:

You do not have to connect to the database
The editor verifies that records are correctly formed
The editor maintains records so they are available to you to edit later

Note

You must restart the database to implement your changes.

For information about using the Administration Tools to create and edit authentication records, see Creating authentication records.

Deleting authentication records

To delete client authentication record, use DROP AUTHENTICATION. To use this approach, you have to be connected to your database.

To delete an authentication record for md5_auth use the following command:

=> DROP AUTHENTICATION md5_auth;

To delete an authentication record for a method that has been granted to a user, use the CASCADE keyword:

=> CREATE AUTHENTICATION localpwd METHOD 'password' LOCAL;
=> GRANT AUTHENTICATION localpwd TO jsmith;
=> DROP AUTHENTICATION localpwd CASCADE;

Security-and-Authentication: Authentication record priority

Mon, 01 Jan 0001 00:00:00 +0000

Each authentication record has a priority. If a user is granted more than one authentication record, OpenText™ Analytics Database attempts to authenticate the user with the authentication record with the highest priority and rejects the user if authentication fails.

There are two ways to authenticate with a record other than that with the highest priority:

Fallthrough authentication: If authentication fails, the database attempts to authenticate the client with the record with the next highest priority.
Authentication filtering: Clients can send the credentials required for a particular authentication method to authenticate with a record that uses that method.

Determining authentication priority

The following factors contribute to an authentication record's priority, as reflected in the CLIENT_AUTH system table:

=> SELECT auth_name, auth_method, auth_priority, method_priority, address_priority FROM client_auth;
   auth_name   | auth_method | auth_priority | method_priority | address_priority
---------------+-------------+---------------+-----------------+------------------
 ldap_auth     | LDAP        |             5 |               5 |               96
 hash_auth     | HASH        |             5 |               2 |              126
 tls_auth      | TLS         |             0 |               5 |               96
 oauth_auth    | OAUTH       |             0 |               5 |               96
 gss_auth      | GSS         |             0 |               5 |               96
 trust_auth    | TRUST       |             0 |               0 |               96
 reject_auth   | REJECT      |             0 |              10 |               96
(7 rows)

Note

Greater values indicate higher priorities. For example:

A priority of 10 is higher than a priority of 5.
A priority 0 is the lowest possible value.

Priorities are divided into tiers and listed in order of importance; in the event of a tie at one priority tier, the database checks the next priority tier. For example, if a user had both ldap and hash authentication records with an auth_priority of 5, the database would attempt to use the ldap authentication record because it has a greater method_priority value:

auth_priority: The priority explicitly set with ALTER AUTHENTICATION (default: 0).
method_priority: The priority specific to the authentication method. These priorities are as follows:
- trust: 0
- hash: 2
- ldap: 5
- tls: 5
- oauth: 5
- gss: 5
- reject: 10
address_priority: The priority for IP address specified in HOST [ TLS | NO TLS ] 'host-ip-address'. This priority is determined by the size of the netmask of the address; fewer zeros indicate greater specificity, and therefore higher priority. LOCAL has the lowest priority: 0.

Setting authentication priority

To set authentication priority:

=> ALTER AUTHENTICATION authentication_name PRIORITY value;

Security-and-Authentication: Viewing information about client authentication records

Mon, 01 Jan 0001 00:00:00 +0000

For information about client authentication records that you have configured for your database, query the following system tables in the V_CATALOG schema:

To determine the details behind the client authentication used for a particular user session, query the following tables in the V_MONITOR schema:

Security-and-Authentication: Enabling and disabling authentication methods

Mon, 01 Jan 0001 00:00:00 +0000

When you create an authentication method, OpenText™ Analytics Database stores it in the catalog and enables it automatically. To enable or disable an authentication method, use the ALTER AUTHENTICATION statement. To use this approach, you must be connected to your database.

If an authentication method has not been enabled, the database cannot use it to authenticate users and clients trying to connect to the database.

To enable an authentication method:

ALTER AUTHENTICATION v_kerberos ENABLE;

To disable this authentication method:

ALTER AUTHENTICATION v_kerberos DISABLE;

Security-and-Authentication: Granting and revoking authentication methods

Mon, 01 Jan 0001 00:00:00 +0000

Before OpenText™ Analytics Database can validate a user or client through an authentication method, you must first associate that authentication method with the user or role that requires it, with GRANT (authentication). When that user or role no longer needs to connect to the database using that method, you can disassociate that authentication from that user with REVOKE AUTHENTICATION.

Grant authentication methods

You can grant an authentication method to a specific user or role. You can also specify the default authentication method by granting an authentication method to PUBLIC, as in the following examples.

Associate v_ldap authentication with user jsmith:
```
=> GRANT AUTHENTICATION v_ldap TO jsmith;
```

Associate v_gss authentication to the role DBprogrammer:


=> CREATE ROLE DBprogrammer;
=> GRANT AUTHENTICATION v_gss TO DBprogrammer;

Associate client authentication method v_localpwd with role PUBLIC, which is assigned by default to all users:
```
=> GRANT AUTHENTICATION v_localpwd TO PUBLIC;
```

Revoke authentication methods

If you no longer want to authenticate a user or client with a given authentication method, use the REVOKE (authentication) statement as in the following examples.

Revoke v_ldap authentication from user jsmith:

=> REVOKE AUTHENTICATION v_ldap FROM jsmith;

Revoke v_gss authentication from the role DBprogrammer:
```
=> REVOKE AUTHENTICATION v_gss FROM DBprogrammer;
```
Revoke localpwd as the default client authentication method:
```
=> REVOKE AUTHENTICATION localpwd FROM PUBLIC;
```

Security-and-Authentication: Hiding database usernames

Mon, 01 Jan 0001 00:00:00 +0000

If you want to keep certain database usernames a secret from connecting clients and your authentication records do not use Fallthrough authentication, then these two user groups must share the same single authentication method (not necessarily the same authentication record):

Users whose usernames must be kept secret.
Users with the PUBLIC role.

If your authentication records use fallthrough, then ensure that the first authentication method that prompts for a password in the authentication chain is the same for both the secret users and the PUBLIC role. The following methods prompt for a password:

A simple way to satisfy this condition is by duplicating the fallthrough chain for both groups with the same methods. For example, a valid authentication chain would be tls > ldap for both the secret users and the PUBLIC role.

Another valid configuration would be tls > ldap > hash for secret users, and ldap for the PUBLIC role.

Security-and-Authentication: Hash authentication

Mon, 01 Jan 0001 00:00:00 +0000

The hash authentication method authenticates users with passwords.

In general, you should prefer other authentication methods over hash.

Security-and-Authentication: Ident authentication

Mon, 01 Jan 0001 00:00:00 +0000

The Ident protocol, defined in RFC 1413, authenticates a database user with a system user name.To see if that system user can log in without specifying a password, you configure OpenText™ Analytics Database client authentication to query an Ident server. With this feature, the DBADMIN user can run automated scripts to execute tasks on the database server.

Caution

Ident responses can be easily spoofed by untrusted servers. Use Ident authentication only on local connections, where the Ident server is installed on the same computer as the database server.

Following the instructions in these topics to install, set up, and configure Ident authentication for your database:

Examples

The following examples show several ways to configure Ident authentication.

Allow system_user1 to connect to the database as vuser1:

=> CREATE AUTHENTICATION v_ident METHOD 'ident' LOCAL;
=> ALTER AUTHENTICATION v_ident SET system_users='system_user1';
=> GRANT AUTHENTICATION v_ident to vuser1;
=> ALTER AUTHENTICATION v_ident ENABLE;

Allow system_user1, system_user2, and system_user3 to connect to the database as vuser1. Use colons (:) to separate the user names:

=> CREATE AUTHENTICATION v_ident METHOD 'ident' LOCAL;
=> ALTER AUTHENTICATION v_ident SET system_users='system_user1:system_user2:system_user3';
=> GRANT AUTHENTICATION v_ident TO vuser1;
=> ALTER AUTHENTICATION v_ident ENABLE;

Associate the authentication with Public using a GRANT AUTHENTICATION statement. The users, system_user1, system_user2, and system_user3 can now connect to the database as any database user:

=> CREATE AUTHENTICATION v_ident METHOD 'ident' LOCAL;
=> ALTER AUTHENTICATION v_ident SET system_users='system_user1:system_user2:system_user3';
=> GRANT AUTHENTICATION v_ident to Public;
=> ALTER AUTHENTICATION v_ident ENABLE;

Set the system_users parameter to * to allow any system user to connect to the database as vuser1:

=> CREATE AUTHENTICATION v_ident METHOD 'ident' LOCAL;
=> ALTER AUTHENTICATION v_ident SET system_users='*';
=> GRANT AUTHENTICATION v_ident TO vuser1;
=> ALTER AUTHENTICATION v_ident ENABLE;

Using a GRANT statement, associate the v_ident authentication with Public to allow system_user1 to log into the database as any database user:

=> CREATE AUTHENTICATION v_ident METHOD 'ident' LOCAL;
=> ALTER AUTHENTICATION v_ident SET system_users='system_user1';
=> GRANT AUTHENTICATION v_ident to Public;
=> ALTER AUTHENTICATION v_ident ENABLE;

Security-and-Authentication: Kerberos authentication

Mon, 01 Jan 0001 00:00:00 +0000

Kerberos authentication uses the following components to perform user authentication.

Client package

The Kerberos 5 client package communicates with the KDC server. This package is not included as part of the OpenText™ Analytics Database installation. Kerberos software is built into Microsoft Windows. If you are using another operating system, you must obtain and install the client package.

If you do not already have the Kerberos 5 client package on your system, download it from the MIT Kerberos Distribution page. Install the package on each database server and client used in Kerberos authentication, except the KDC itself.

Refer to the Kerberos documentation for installation instructions.

Service principals

A service principal consists of a host name, a service name, and a realm to which a set of credentials gets assigned (service/hostname@REALM). These credentials connect to the service, which is a host that you connect to over your network and authenticate using the KDC.

See Specify KDC information and configure realms to create the realm name. The host name must match the value supplied by the operating system. Typically this is the fully qualified host name. If the host name part of your principal does not match the value supplied by the operating system, Kerberos authentication fails.

Some systems use a hosts file (/etc/hosts or /etc/hostnames) to define host names. A hosts file can define more than one name for a host. The operating system supplies the first entry, so use that in your principal. For example, if your hosts file contains:

192.168.1.101 v_vmart_node0001.example.com v_vmart_node0001

then use v_vmart_node0001.example.com as the hostname value.

Note

Depending on your configuration it may be safer to use the fully qualified domain name rather than the hostname.

Configure the following as Kerberos principals:

Each client (users or applications that connects to the database)
The database server

See the following topics for more information:

Keytab files

Principals are stored in encrypted keytab files. The keytab file contains the credentials for the database principal. The keytab allows the database server to authenticate itself to the KDC. You need the keytab so that the database does not have to prompt for a password.

Create one service principal for each node in your cluster. You can then either create individual keytab files (one for each node containing only that node's principal) or create one keytab file containing all the principals.

Create one keytab file with all principals to simplify setup: all nodes have the same file, making initial setup easier. If you add nodes later you either update (and redistribute) the global keytab file or make separate keytabs for the new nodes. If a principal is compromised it is compromised on all nodes where it is present in a keytab file.
Create separate keytab files on each node to simplify maintenance. Initial setup is more involved as you must create a different file on each node, but no principals are shared across nodes. If you add nodes later you create keytabs on the new nodes. Each node's ke ytab contains only one principal, the one to use for that node.

Ticket-granting ticket

The Ticket-Granting Ticket (TGT) retrieves service tickets that authenticates users to servers in the domain. Future login requests use the cached HTTP Service Ticket for authentication, unless it has expired as set in the ticket_lifetime parameter in krb5.conf.

Multi-realm support

Note

When assigning multiple realms to an authentication record, keep in mind that the database cannot distinguish between users from one realm and users from the database realm. This allows the same user to log in to the database from multiple realms at the same time.

The database provides multi-realm support for Kerberos authentication using the SET param=value parameter in ALTER AUTHENTICATION with REALM as the parameter:

=> ALTER AUTHENTICATION krb_auth_users set REALM='USERS.COM';
=> ALTER AUTHENTICATION krb_auth_realmad set REALM='REALM_AD.COM';

This allows you to assign a different realm so that users from another realm can authenticate to the database.

Mutli-realm support applies to GSS authentication types only. You can have one realm per authentication method. If you have multiple authentication methods, each can have its own realm:

=> SELECT * FROM client_auth;
auth_oid | auth_name | is_auth_enabled | auth_host_type | auth_host_address | auth_method | auth_parameters     | auth_priority
---------+-----------+-----------------+----------------+-------------------+-------------+-----------------+-----------------
45035996 | krb001    |   True          |   HOST         |  0.0.0.0/0        |  GSS        | realm=USERS.COM     |  0
45035997 | user_auth |   True          |   LOCAL        |                   |  TRUST      |                     |  1000
45035737 | krb002    |   True          |   HOST         |  0.0.0.0/0        |  GSS        | realm=REALM_AD.COM  |  1

Security-and-Authentication: LDAP authentication

Mon, 01 Jan 0001 00:00:00 +0000

Lightweight Directory Access Protocol (LDAP) is an authentication method that works like password authentication. The main difference is that the LDAP method authenticates clients trying to access your OpenText™ Analytics Database against an LDAP or Active Directory server. Use LDAP authentication when your database needs to authenticate a user with an LDAP or Active Directory server.

Security-and-Authentication: OAuth 2.0 authentication

Mon, 01 Jan 0001 00:00:00 +0000

Rather than with a username and password, users can authenticate to OpenText™ Analytics Database by first verifying their identity with an identity provider, receiving an OAuth token, and then passing the token to the database.

OAuth in the database is tested with Keycloak, Okta, and OTDS but other providers should work if they support the RFC 7662 Token Introspection standard.

Security-and-Authentication: TLS authentication

Mon, 01 Jan 0001 00:00:00 +0000

The tls authentication method authenticates users that can establish a mutual mode client-server TLS connection using a certificate that specifies a valid database username in the Common Name (CN) field.

Before you create and use a tls authentication method, you must configure Vertica for client-server TLS in mutual mode (disabled by default).

OpenText Analytics Database 26.2.x – Client authentication

Security-and-Authentication: Default authentication records

Note

Security-and-Authentication: Configuring client authentication

Basic authentication configuration workflow

IPv4 and IPv6 for client authentication

Supported client authentication methods

Local and host authentication

Authentication for chained users and roles

Security-and-Authentication: Fallthrough authentication

Authentication method compatibility

Logging authentication failures

Examples

Security-and-Authentication: Authentication filtering

Client-side fallthrough authentication

Examples

Security-and-Authentication: Implicit authentication

Security-and-Authentication: Dbadmin authentication access

Authenticating from a local connection

Authenticating from a remote connection

Fallthrough authentication

Custom authentication records

Security-and-Authentication: Creating authentication records

Important

Examples

See also

Security-and-Authentication: Modifying authentication records

Rename an authentication method

Specify a priority for an authentication method

Change a parameter

Change the associated method

Using the administration tools

Note

Deleting authentication records

See also

Security-and-Authentication: Authentication record priority

Determining authentication priority

Note

Setting authentication priority

See also

Security-and-Authentication: Viewing information about client authentication records

Security-and-Authentication: Enabling and disabling authentication methods

See also

Security-and-Authentication: Granting and revoking authentication methods

Grant authentication methods

Revoke authentication methods

Security-and-Authentication: Hiding database usernames

Security-and-Authentication: Hash authentication

Security-and-Authentication: Ident authentication

Caution

Examples

Security-and-Authentication: Kerberos authentication

Client package

Service principals

Note

Keytab files

Ticket-granting ticket

Multi-realm support

Note

Security-and-Authentication: LDAP authentication

Security-and-Authentication: OAuth 2.0 authentication

Security-and-Authentication: TLS authentication