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

oauth2_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:

jwt_rsa_public_key: Required. 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.
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.