OAuth authentication parameters

Vertica OAuth authentication records use the following parameters to determine how to validate client OAuth tokens and how to contact the identity provider during the validation process.

Vertica OAuth authentication records use the following 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 optional oauth2_jit_enabled parameter specifies whether to enable just-in-time user provisioning. If set to 'yes', when the user authenticates, Vertica automatically performs the following actions:

  1. Creates the user if they do not already exist in the database. The length of the username in the identity provider cannot be greater than 128 characters.

  2. (Keycloak only) Grants to the user and sets as default the roles associated with the user (as specified by the identity provider), provided the roles already exist in Vertica.

  3. Grants to the user the authentication record used to authenticate them if neither their user nor role has a grant on that record.

If set to 'no' (default), users must be manually created and granted an oauth authentication record to authenticate to Vertica with OAuth tokens.

Validation modes

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

The validate_type parameter takes 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 tables below.

IDP validation parameters

The following table lists the parameters used to configure OAuth authentication records that use the IDP validation mode:

Parameter name Description Required/Optional
client_id 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. Required
client_secret The secret of the confidential client application registered in the identity provider. This value is not shared with other clients. Required
discovery_url (Keycloak only)

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.

 Required for IDP validation if introspect_url is not specified.
introspect_url 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. Required if discovery_url is not specified.
auth_url The authorization endpoint for your identity provider. Required for single-sign on (SSO)
token_url The token endpoint for your identity provider. Required for single-sign on (SSO)
scope 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. Optional
validate_hostname

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.

 Optional

JWT validation parameters

The following table lists the parameters used to configure OAuth authentication records that use the JWT validation mode:

Parameter name Description Required/Optional
jwt_rsa_public_key In PEM format, the 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. Required
jwt_issuer The issuer of the OAuth token. This value is set by the identify provider. Required
jwt_user_mapping The name of the Vertica user. Required
jwt_accepted_audience_list 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. Optional
jwt_accepted_scope_list 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. Optional