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. While Vertica does not contact the identity provider for JWT validation, the client does for token refresh if either the discovery or token endpoints are set in oauthjsonconfig. This should be used for public clients (set for each client by the identity provider). Additionally, clients can connect if they leave oauthjsonconfig or OAuthJsonConfig empty.

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

IDP validation parameters

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 specify the discovery_url and not the introspect_url, Vertica automatically retrieves the introspect_url from the identity provider.

If you specify both the discovery_url and introspect_url, 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.

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