OpenText Analytics Database 26.2.x – OAuth 2.0 authentication

Security-and-Authentication: Configuring OAuth authentication

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

The following procedure performs the following actions:

Configures an identity provider for OAuth integration with Vertica (either Okta or Keycloak).
Creates an OAuth authentication record.
Retrieves an access token from the identity provider with a POST request.
Passes the access token to a sample application, which then authenticates to Vertica.

Configure the identity provider

Vertica officially tests and supports OAuth integration with Keycloak and Okta. Other identity providers should also work as long as they implement the RFC 7662 Token Introspection standard. The following example configurations are provided for reference:

Create an authentication record

In Vertica, create an authentication record for OAuth. This uses the client ID, client secret, and either the discovery (Keycloak) or introspect (Okta) endpoint used by your identity provider.

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';

Setting the required parameters automatically enables the authentication record. To manually enable the authentication record:

=> ALTER AUTHENTICATION v_oauth ENABLE;

For a full list of OAuth authentication parameters, see OAuth authentication parameters.

Create a Vertica user

Vertica users map to the identity provider's users with the same username. You can either create the user manually or enable just-in-time (JIT) user provisioning in the authentication record to automatically create users with valid tokens.

To manually create the user:

To map to the user oauth_user in the identity provider, create a Vertica user with the same name. You do not need to specify a password because authentication is performed by the identity provider:
```
=> CREATE USER oauth_user;
```

Grant the OAuth authentication record to the user (or their role):

=> GRANT AUTHENTICATION v_oauth TO oauth_user;
=> GRANT ALL ON SCHEMA PUBLIC TO oauth_user;

To enable JIT user provisioning:

=> ALTER AUTHENTICATION v_oauth SET oauth2_jit_enabled = 'yes';

If the user already exists and JIT user provisioning is enabled and you use Keycloak as your IDP, Vertica automatically assigns the roles associated with the user as specified by the IDP if the roles also exist in Vertica. For details, see Just-in-time user provisioning.

Retrieve an access token

To authenticate to Vertica, you must retrieve an access token from the identity provider.

Programmatic method

A simple way to get an OAuth access token and refresh token is to send a POST request to the token endpoint, providing the credentials of the user. You can then use the returned access token, refresh token, and scope with the connection properties for your client. For details, see JDBC connection properties and ODBC DSN connection properties.

For example, to get an access token for oauth_user from Keycloak:

$ curl --location --request POST 'http://203.0.113.1:8080/realms/master/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=oauth_user' \
--data-urlencode 'password=oauth_user_password' \
--data-urlencode 'client_id=vertica' \
--data-urlencode 'client_secret=client_secret' \
--data-urlencode 'grant_type=password'

Keycloak responds with a JSON string containing the access_token and refresh_token if you authenticated correctly:

{
   "access_token":"access_token",
   "expires_in":60,
   "refresh_expires_in":1800,
   "refresh_token":"refresh_token",
   "token_type":"Bearer",
   "not-before-policy":0,
   "session_state":"6745892a-aa74-452f-b6b9-c45637193859",
   "scope":"profile email"
}

Similarly, to retrieve an access token for oauth_user from Okta:

$ curl --insecure -d "client_id=0oa5cgdga1fb812rW697" -d "client_secret=aq22wRl3Z3mmtuoB13omRo6Ql03Ltafet4xYi77p" \
-d "username=oauth_user" -d "password=oauth_user_password" \
-d "grant_type=password" -d "scope=offline_access%20openid" https://example.okta.com/oauth2/default/v1/introspect

{"token_type":"Bearer","expires_in":3600,"access_token":"access_token","id_token":"id_token"}

Single-sign on (SSO)

An alternative to manually retrieving the access token is using SSO through the ODBC client driver. With this method, the ODBC driver opens the default web browser to the IDP's authentication endpoint where the user can enter their credentials. If the user successfully authenticates to the IDP, the ODBC driver automatically retrieves the token and authenticates to Vertica.

To configure and use the ODBC driver for SSO:

For clients that use the confidential access type, set the oauthclientsecret.
In the authentication record, set the following parameters:
- The discovery_url (Keycloak only) or the following:
  - auth_url
  - token_url
- client_id
Connect to Vertica with the ODBC driver. The default web browser opens to your IDP's sign-in page.
Enter your credentials to authenticate to the IDP.

Run the sample applications

The OAuth sample applications, at a minimum, take an access token as an argument to authenticate to the database until the token expires. This token is retrieved by the client application and then set as a connection property in the driver.

ODBC

Follow the instructions in the README.
Run the sample application, passing the OAuth parameters as arguments:
- To authenticate until the token expires:
```
$ ./a.out --access-token OAuthAccessToken
```
- To authenticate and silently refresh the access token when it expires:
```
$ ./a.out --access-token OAuthAccessToken
    --refresh-token OAuthRefreshToken
    --client-secret OAuthClientSecret
```

For a list of all ODBC OAuth parameters, see ODBC DSN connection properties.

JDBC

Follow the instructions in the README.

Run the sample application, passing the OAuth parameters as arguments:

To authenticate until the token expires:

$ mvn compile exec:java -Dexec.mainClass=OAuthSampleApp -Dexec.args="vertica_host database_name --access-token oauthaccesstoken"

To authenticate and silently refresh the access token when it expires:

$ mvn compile exec:java -Dexec.mainClass=OAuthSampleApp -Dexec.args="vertica_host database_name --access-token oauthaccesstoken
    --refresh_token oauthrefreshtoken
    --client-secret oauthclientsecret

ADO.NET

The ADO.NET driver uses a simplified configuration scheme with a single connection property: OAuthAccessToken. Other flows like token refresh should be handled externally by the driver. The sample application in the following example demonstrates how to pass an access token to the ADO.NET driver and how to handle token refresh:

Follow the instructions in the README.
Run the sample application.

VSQL

Connect to VSQL client using OAuth authentication

Before connecting to the VSQL client using OAuth authentication, ensure the following:

The user should be associated with an IDP provider (such as Keycloak, OKta, and so on) and granted the necessary privileges.
The user should be mapped to OpenText™ Analytics Database or the administrator needs to enable JIT (Just In-time) for auto-mapping the user.

Do one of the following:

Provide the access token as the parameter from the CLI. Do one of the following:
```
 -bash-4.4$ $VSQL -L 
```
<--Or-->
```
 -bash-4.4$ $VSQL --access-token 
```
<--Or-->
Store the access token in the environment variable VSQL_OAUTH_ACCESS_TOKEN. Optionally, provide the authentication method as OAuth.

The client retrieves the access token from the environment variable and does the authentication. VSQL successfully authenticates using OAuth authentication if the environment variable of the access token is not null.

Example
```
-bash-4.4$ $VSQL
Type:  \h or \? for help with vsql commands
\g or terminate with semicolon to execute query
\q to quit
verticadb21496=>
```
<--Or-->
To specify user IDP (Identity Provider) credentials, provide the authentication method as OAuth. Provide the username and the database name.

The user generates the public and private keys as shown below.
```
openssl genpkey -algorithm RSA -out $HOME/.ssh/user_private.pem -pkeyopt rsa_keygen_bits:2048 > /dev/null 2>&1

openssl rsa -pubout -in $HOME/.ssh/user_private.pem -out $HOME/.ssh/user_public.pem > /dev/null 2>&1
```
The administrator:
- has access to client information such as the client ID, client secret, the token URL, and stores the client information in a text file (oauth_config.txt by default).
```
  ClientId=<ClientId>LF
  TokenURL=http://<ip>:<port>/realms/master/protocol/openid-connect/tokenLF
  ClientSecret=<ClientSecret>
```
- collects the user's public key and stores it in the ssh folder of the administrator's home path ($HOME/.ssh).
- encrypts the configuration file through the VSQL utility using --oauth_encrypt.
```
 -bash-4.4$ $VSQL --oauth_encrypt --config_input:<filepath>/<filename> --config_output:<filepath>/<filename>
```
  where <--config_input:> and <--config_output:> are optional parameters. If these parameters are not specified, the <--config_input:> is set to $HOME/oauth_config.txt and <--config_output:> is set to $HOME/dbname_config.enc by default.
- shares the encrypted configuration file with the user.

VSQL reads the encrypted configuration file from the home path of the user. Users need to set the Home path to $HOME, if it is not already defined. Users provide the IDP username and password for authentication using OAuth authentication.

The user:

copies the encrypted client configuration file in the home path ($HOME) and ensures that the file name is <dbname>_conf.enc.
ensures that the generated user_private.pem file is available in the $HOME/.ssh folder.

(VSQL) provides the DBName, auth method, username, and password. It is mandatory to provide the DBName, auth method, and username. The user either enters the IDP password as a parameter or VSQL prompts for it.

-bash-4.4$ $VSQL -U <username> -d <DBName> -M OAuth
 idpPassword:
 Type:  \h or \? for help with vsql commands
   \g or terminate with semicolon to execute query
   \q to quit
 verticadb=>

<--Or-->

-bash-4.4$ $VSQL -U <username> -d <DBName> -M OAuth -I "$pass$"
Type:  \h or \? for help with vsql commands
   \g or terminate with semicolon to execute query
   \q to quit
 verticadb=>

Troubleshooting

To get debugging information for TLS, use the -Djavax.net.debug=ssl flag.

Custom CA certificates

A truststore is a container for trusted certificate authority (CA) certificates. These CA certificates are used to verify the identities of other systems when establishing a TLS connection. When your JDBC client connects to the identity provider through an HTTPS endpoint, the JDBC client verifies the identity provider's certificate by making sure that it was issued by a CA in the truststore.

If you configure your identity provider with TLS (that is, if you use HTTPS endpoints for your token or refresh URLs) and its certificate is not issued by a well-known CA, you must either specify a custom truststore or import the issuer's CA certificate into the system truststore with keytool.

To specify a custom truststore, set the JDBC connection properties oauthtruststorepath and oauthtruststorepassword:

connProps = new Properties(connProps);
connProps.setProperty("oauthtruststorepath", "/path/to/truststore/customoauth.truststore");
connProps.setProperty("oauthtruststorepassword", "password");

To add the certificate keycloak/cert.crt to the Java truststore:

$ keytool -trustcacerts -keystore /usr/lib/jvm/java-1.7.0-openjdk-1.7.0.261-2.6.22.2.el7_8.x86_64/jre/lib/security/cacerts -storepass changeit -importcert -alias keycloak -file /keycloak/cert.crt

Security-and-Authentication: Just-in-time user provisioning

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

Just-in-time (JIT) user provisioning is the act of automatically configuring an authenticated user and their roles based on information provided by the identity provider (IdP).

When a client uses an OAuth authentication record that enables JIT user provisioning, OpenText™ Analytics Database automatically performs the following actions:

Creates the user if they do not exist in the database. The username must conform to conventions described in Identifiers.
If you configure automatic role assignment, OpenText™ Analytics Database identifies roles that exist in both the user or group identity and the database and grants each role to the database user as a default role.
Grants to the user the authentication record that is associated with the IdP if the user or role does not already have a grant on that authentication record.

You can view all JIT-provisioned users and their authentication record with the USERS system table. If the user was JIT-provisioned, then the managed_by_oauth2_auth_id column lists the JIT-enabled authentication record:

=> SELECT user_name, managed_by_oauth2_auth_id FROM users;
 user_name |  managed_by_oauth2_auth_id
-----------+-----------------------------
 dbadmin   |
 Bob       | 45035996273853300
 Margie    |
 Alice     | 45035996273866484
(4 rows)

Enable JIT provisioning

When the database authenticates a JIT-provisioned user, it loops through all existing OAuth authentication records for a record that can authenticate the OAuth token in the client request. If the database locates the authentication record, it assigns the record to the JIT-provisioned user.

After you create an OAuth authentication record, you must alter its authentication record to enable JIT. To enable JIT, set the jit_enabled OAuth authentication parameter to yes:

=> ALTER AUTHENTICATION v_oauth SET jit_enabled = 'yes';
ALTER AUTHENTICATION

To confirm that JIT authentication is enabled on the authentication record, query the CLIENT_AUTH_PARAMS table:

=> SELECT * FROM CLIENT_AUTH_PARAMS WHERE auth_name = 'v_oauth' AND auth_parameter_name = 'jit_enabled';
     auth_oid      | auth_name | auth_parameter_name | auth_parameter_value
-------------------+-----------+---------------------+----------------------
 45035996273859012 | v_oauth   | jit_enabled  | yes
(1 row)

Automatic role assignment

The database can automatically assign a role to a JIT-provisioned user if the OAuth token contains the following:

Client identity role that exactly matches the database role
Group identity role that exactly matches the database role
Group identity name that exactly matches the database role

The database updates the role assignment each time a JIT-provisioned user authenticates with the OAuth token. For example, if the database automatically assigned a role using the group identity name and then that group identity is removed from the IdP, that role is revoked the next time that JIT-provisioned user authenticates to the database. In addition, you can add a role to a blocklist that prevents the database from automatically granting that role during JIT provisioning. These features ensure that the database reflects up-to-date role assignments so that you can manage your database user identities from a single, secure location.

Prerequisites

Create an OAuth authentication record.
Enable JIT provisioning.
Create database roles that you want to automatically assign to JIT-provisioned users.

Configure role assignment

An IdP manages the database as a client identity. An IdP client can have zero or more roles, where each role has specific privileges in the client environment. IdPs also manage group identities, where each group identity is a collection of user identities that share attributes and roles.

During automatic role assignment, the database treats each IdP client role, group role, and group name the same. If the JIT-provisioned user has a client role, group role, or group name that maps to a database role, the database automatically assigns that role to the JIT-provisioned user. A single OAuth token can contain both client and group identities.

To associate a database with an IdP client or group identity, set the corresponding security parameter:

OAuth2JITRolesClaimName identifies the database client identity in an IdP that contains the role mappings:
```
=> ALTER DATABASE DEFAULT SET OAuth2JITRolesClaimName = 'resource_access.IdPClientName.roles';
```
OAuth2JITGroupsClaimName identifies a group identity that contains the client role mappings:
```
=> ALTER DATABASE DEFAULT SET OAuth2JITGroupsClaimName = 'IdPGroupClaimName';
```

The database automatically assigns a role only if the database security parameter setting exactly matches an IdP client or group claim name. If there is a match, then the databasea looks at the match in the IdP. If there is a client role, group name, or group role that exactly matches an existing database role, then the database grants the database role to the JIT-provisioned user. The database ignores any roles or groups that do not have exact matches in the database.

Restrict role assignment

The database can assign any role to a JIT-provisioned user, including DBADMIN and PSEUDOSUPERUSER. Because granting unrestricted privileges might raise security concerns, you can restrict the database role assignments with the OAuth2JITForbiddenRoles security parameter:

=> ALTER DATABASE DEFAULT SET OAuth2JITForbiddenRoles = 'dbadmin,pseudosuperuser'

When an IdP user has a role or group mapping that matches a role in OAuth2JITForbiddenRoles, the database does not grant the JIT-provisioned user that role.

Verify role assignments

To verify which roles were automatically assigned to JIT-provisioned users, you can query the vs_users table. The num_jit_roles column lists the number of roles that were assigned with JIT provisioning, and oauth2_jit_roles list the names of each role:

=> \x
Expanded display is on.
=> SELECT num_default_roles, default_roles, num_jit_roles, oauth2_jit_roles, managed_by_oauth2_auth_id
   FROM vs_users 
   WHERE name = 'username';
-[ RECORD 1 ]-------------+----------------------------------------------------------
num_default_roles         | 2
default_roles             | vertica-admin, vertica-user
num_jit_roles             | 2
oauth2_jit_roles          | vertica-admin, vertica-user
managed_by_oauth2_auth_id | 45035996273851314

Example

In this example scenario, an organization uses the Keycloak IdP to manage user identities across their organization. The Keycloak implementation has a client identity named vertica and a group identity named groups. The following table lists the client roles, IdP groups, and group roles:

vertica client roles groups name groups roles

`vertica` client roles	`groups` name	`groups` roles
dbadmin orders_user view_realm	realm_admin	user_admin

dbadmin

orders_user

view_realm

realm_admin

user_admin

Database configuration

There is a database named orders with the following security parameter settings that define the roles claim, group claim, and restricted roles:

=> SELECT parameter_name, current_value FROM configuration_parameters
   WHERE parameter_name = 'OAuth2JITRolesClaimName'
   OR parameter_name = 'OAuth2JITGroupsClaimName'
   OR parameter_name = 'OAuth2JITForbiddenRoles';
      parameter_name      |            current_value
--------------------------+-------------------------------------
 OAuth2JITForbiddenRoles  | dbadmin,pseudosuperuser
 OAuth2JITGroupsClaimName | groups
 OAuth2JITRolesClaimName  | resource_access.vertica.roles
(3 rows)

The database has the following users:

=> SELECT USER_NAME FROM USERS;
 USER_NAME
-----------
 dbadmin
(1 row)

The database has the following assigned roles:

=> SELECT NAME, ASSIGNED_ROLES FROM ROLES;
      NAME       | ASSIGNED_ROLES
-----------------+----------------
 public          |
 dbduser         |
 dbadmin         | dbduser*
 pseudosuperuser | dbadmin*
 ...
 orders_user     |
 user_admin      |

Role assignment process

A client authenticates to the orders database as a user named Alice, but the Alice user does not exist in the database. The authentication record associated with the orders database uses IDP validation and has jit_enabled set to yes, so the database can JIT provision the Alice user and then assign roles that exist in both the IdP and the database.

When Alice authenticates to the orders database, the database performs the following steps:

Provisions the Alice user.
Sends a request to the IdP to retrieve roles using the OAuth2JITRolesClaimName and OAuth2JITGroupsClaimName security parameter settings. In this case, the database requests roles for a client identity named vertica and a group identity named groups.
Compares all client and group roles in the IdP response to the roles in the database and performs the following:
- Grants the orders_user role to the JIT-provisioned Alice user, and sets it as a default role.
- Grants the user_admin role to the JIT-provisioned Alice user, and sets it as a default role.
- Does not grant the dbadmin role to Alice because it is specified by the OAuth2JITForbiddenRoles security parameter.
- Ignores the realm_admin group name and view_admin group role because there is no corresponding role in the database.

After the automatic role assignment process completes, Alice has default roles that reflect the IdP configuration:

=> SELECT user_name, default_roles FROM users 
   WHERE user_name = 'Alice';
 user_name |      default_roles
-----------+-------------------------
 Alice     | orders_user, user_admin
(1 row)

The automatic role assignment workflow occurs each time a client authenticates as the Alice user. This ensures that the database role assignments reflect the current role assignments in the IdP.

Automatic user pruning

You can enable automatic user pruning to periodically drop users created by JIT user provisioning if they do not log in after a certain period of time. This cleanup service is managed by the following database-level configuration parameters:

EnableOAuthJITCleanup: Whether to enable cleanup (disabled by default).

=> ALTER DATABASE DEFAULT SET EnableOAuthJITCleanup = 1; --enables the pruning service
=> ALTER DATABASE DEFAULT SET EnableOAuthJITCleanup = 0; --disables the pruning service

OAuth2UserExpiredInterval: The number of days a user must be inactive before it is dropped (14 by default). This is calculated based on the current date and the LAST_LOGIN_TIME in the USERS system table.
Note

The LAST_LOGIN_TIME as recorded by the USERS system table is not persistent; if the database is restarted, the LAST_LOGIN_TIME for users created by just-in-time user provisioning is set to the database start time (this appears as an empty value in LAST_LOGIN_TIME).

You can view the database start time by querying the DATABASES system table:
```
=> SELECT database_name, start_time FROM databases;
 database_name |          start_time
---------------+-------------------------------
 VMart         | 2023-02-06 14:26:50.630054-05
(1 row)
```
```
=> ALTER DATABASE DEFAULT SET OAuth2UserExpiredInterval = 20;
```
GlobalHeirUsername: The user to reassign objects to if the owner is a JIT-provisioned (or LDAP) user that got dropped by the pruning service. If set to <auto>, objects are reassigned to the dbadmin.
```
=> ALTER DATABASE DEFAULT SET GlobalHeirUsername = <auto>
```

The cleanup service runs daily and there can be a delay of up to 24 hours for dropping an expired user.

Security-and-Authentication: OAuth authentication parameters

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

Vertica OAuth authentication records uses parameters to determine how to validate client OAuth tokens and how to contact the identity provider during the validation process. These parameters should be set with ALTER AUTHENTICATION.

Just-in-time provisioning parameters

The following parameters configure just-in-time user provisioning (JIT):

groups_claim_name

Sets the group claim name for the authentication record. This setting overrides the OAuth2JITGroupsClaimName security parameter.

jit_enabled

Whether to enable just-in-time user provisioning. This parameter accepts the following values:

'yes': Vertica uses automatic role assignment.
'no' or unset: You must manually create each user and grant the user an oauth authentication record before they can authenticate to Vertica with OAuth tokens.

oauth2_jit_authorized_roles

When set, the OAuth user specifies roles that can use JIT user provisioning. When omitted, any OAuth user can use JIT provisioning.

This parameter accepts one or more roles as a comma-separated list.

role_group_suffix

OpenText Directory Service (OTDS) only.

Appends a value to the role or group name associated with the OAuth record. Vertica uses this value to identify users during authorization. Vertica recommends that you append your subscription ID in the following format: @subscriptionID.

roles_claim_name

Sets the roles claim name for the authentication record. This setting overrides the OAuth2JITRolesClaimName security parameter.

Validation modes

OAuth authentication records have two modes for validating OAuth tokens, each specified with the authentication parameter validate_type.

validate_type accepts one of the following values:

IDP (default): Validate OAuth tokens by contacting the identity provider. This validation type requires the client to specify their client secret. This should be used with confidential clients (set for each client by the identity provider).
JWT: Validate OAuth tokens by verifying that it was signed by the identity provider's private key. This does not require Vertica to contact the identity provider for validation and should be used for public clients (set for each client by the identity provider).

Each validation mode uses a different set of parameters, which are detailed in the sections below.

IDP validation parameters

The following parameters configure OAuth authentication records that use the IDP validation mode:

client_id

Required. The ID of the confidential client application registered in the identity provider. Vertica uses this ID to call the introspection API to retrieve user grants.

client_secret

Required. The secret of the confidential client application registered in the identity provider. This value is not shared with other clients.

discovery_url

Required for IDP validation if introspect_url is not specified.

Also known as the OpenID Provider Configuration Document or the well-known configuration endpoint, this endpoint contains information about the configuration and endpoints of the identity provider.

If you set the discovery_url, you do not have to set any other endpoint parameters. If you specify discovery_url and other endpoints, the discovery_url takes precedence.

introspect_url

Required if discovery_url is not specified. Used by Vertica to introspect (validate) access tokens. You must specify this parameter if you do not specify the discovery_url. For examples, see the Keycloak and Okta documentation.

auth_url

Required for single-sign on (SSO). The authorization endpoint for your identity provider.

token_url

Required for single-sign on (SSO). The token endpoint for your identity provider.

scope

Optional. The requested OAuth scopes, delimited with spaces. These scopes define the extent of access to the resource server (in this case, Vertica) granted to the client by the access token. For details, see the OAuth documentation.

validate_hostname

Optional. Boolean, whether Vertica verifies the subjectAltName of the identity provider host when establishing a connection. If enabled, the IP address or hostname of the identity provider must be set as the subjectAltName in its certificate. This parameter only applies to connections made by JDBC clients.

Hostname verification is enabled by default.

JWT validation parameters

The following parameters configure OAuth authentication records that use the JWT validation mode.

At least one of jwt_rsa_public_key, jwt_ec_public_key, or jwt_jwks_url must be set for the authentication record to be active. You can configure any combination of these parameters.

jwt_rsa_public_key: Optional. In PEM format, the RSA public key that corresponds to the private key used to sign the client's OAuth token. Vertica 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: Optional. In PEM format, the EC (Elliptic Curve) public key that corresponds to the private key used to sign the client's OAuth token. This is the EC key equivalent of jwt_rsa_public_key.
jwt_jwks_url: Optional. URL to retrieve JSON Web Keys (JWKs) from the identity provider. All keys returned by this endpoint are used when validating a user logging in with a JWT. Using this parameter allows Vertica to automatically fetch signing keys, which 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
jwt_issuer: Required. The issuer of the OAuth token. This value is set by the identify provider.
jwt_user_mapping: Required. The name of the Vertica user.
jwt_accepted_audience_list: Optional. A comma-delimited list of values to accept from the client OAuth token'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 OAuth token's scope field. If set, tokens must include in scope at least one of the accepted scopes to authenticate.

Security-and-Authentication: Multi-factor authentication with TOTP

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

OpenText™ Analytics Database now supports Multi-Factor Authentication (MFA) using Time-Based One-Time Passwords (Totp) when the client connects with the server. MFA adds an additional layer of security. Users need to verify their identity using a Totp in addition to their database login credentials.

OpenText Analytics Database 26.2.x – OAuth 2.0 authentication

Security-and-Authentication: Configuring OAuth authentication

Configure the identity provider

Create an authentication record

Create a Vertica user

Retrieve an access token

Programmatic method

Single-sign on (SSO)

Run the sample applications

ODBC

JDBC

ADO.NET

VSQL

Connect to VSQL client using OAuth authentication

Troubleshooting

Custom CA certificates

Security-and-Authentication: Just-in-time user provisioning

Enable JIT provisioning

Automatic role assignment

Prerequisites

Configure role assignment

Restrict role assignment

Verify role assignments

Example

Database configuration

Role assignment process

Automatic user pruning

Note

Security-and-Authentication: OAuth authentication parameters

Just-in-time provisioning parameters

Validation modes

IDP validation parameters

JWT validation parameters

Security-and-Authentication: Multi-factor authentication with TOTP