Authentication filtering

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:

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 + ";OAuthJsonConfig=" + jsonConfig).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)

1. 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)
   

2. Bob notices the failure. The steps involved in detecting this programmatically depend on your client.

3. 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)