OIDC Authentication

VeloDB Enterprise can act as an OAuth 2.0 resource server. It validates access tokens issued by an identity provider (IdP) for VeloDB Enterprise and maps external identities to database users and roles.

Note:

Supported since VeloDB Enterprise 4.1.4.

OIDC authentication follows these steps:

1. Validate the JWT signature and claims, including iss, aud, exp, and nbf.
2. Map the external identity to a VeloDB Enterprise principal.
3. Grant roles to the current session according to role mapping rules.

Use an access token issued for the VeloDB Enterprise resource server. Do not use the ID token returned by a browser login flow for database authentication.

Prerequisites

Enable SSL

OIDC login requires SSL on the frontend (FE). Set the following in fe.conf:

enable_ssl = true

If you also need to validate client certificates, set:

ssl_force_client_auth = true

Restart the FE after changing the configuration. Clients must use SSL. MySQL Shell requires at least --ssl-mode=REQUIRED, and Connector/J requires at least sslMode=REQUIRED. For production connections, also validate the server certificate and hostname, as shown below.

Install an OIDC-capable client

Use one of the following clients:

• MySQL Shell 9.x (mysqlsh).
• MySQL Connector/J 9.1.0 or later.

The standard mysql command-line client and earlier versions of MySQL Shell and Connector/J do not support this OIDC login method.

Check your MySQL Shell version:

mysqlsh --version

Prepare an access token

The token issued by your IdP must meet these requirements:

• It is signed with a supported asymmetric algorithm.
• It contains the iss, aud, and exp claims.
• If it contains nbf, the token is already valid.
• The claims specified by oidc.username_claim and oidc.subject_claim exist.
• The value of oidc.username_claim matches the database username used by the client.
• If oidc.required_scopes is configured, the token contains every required scope.
• If oidc.allowed_client_ids is configured, the token's azp or client_id matches the allowlist. If both exist, azp takes precedence.

Supported signature algorithms are:

• RS256, RS384, and RS512.
• PS256, PS384, and PS512.
• ES256, ES384, and ES512.

Configure an OIDC integration

Use CREATE AUTHENTICATION INTEGRATION to create the integration. You need ADMIN_PRIV to manage integrations and role mappings.

Properties

Property	Required	Description
type	Yes	Authentication plugin type. Set to oidc.
oidc.issuer	Yes	Expected token issuer. Must exactly match the iss claim.
oidc.jwks_uri	Yes	IdP JSON Web Key Set (JWKS) endpoint used to verify token signatures.
oidc.allowed_audiences	Yes	Comma-separated allowed audiences. The token's aud must match at least one.
enable_jit_user	No	Enables just-in-time (JIT) access for users that do not exist locally. This is a general authentication integration property.
oidc.required_scopes	No	Comma-separated scopes that the token must contain.
oidc.allowed_client_ids	No	Comma-separated allowed client IDs.
oidc.username_claim	No	Claim used as the database login name.
oidc.subject_claim	No	Claim used as the external principal identifier.
oidc.groups_claim	No	Claim containing external groups. Can be a string or an array of strings.
oidc.extra_claims	No	Comma-separated additional claims available to role mapping rules.
oidc.allowed_algorithms	No	Comma-separated allowed JWT signature algorithms.
oidc.clock_skew_seconds	No	Allowed clock skew, in seconds, when validating time claims.

The scope and scp claims can be strings or arrays. String values are split on whitespace into individual scopes.

Create the integration

A minimal configuration is:

CREATE AUTHENTICATION INTEGRATION partner_oidc
PROPERTIES (
    'type' = 'oidc',
    'oidc.issuer' = 'https://idp.example.com/realms/doris',
    'oidc.jwks_uri' = 'https://idp.example.com/realms/doris/protocol/openid-connect/certs',
    'oidc.allowed_audiences' = 'doris-prod'
);

Replace the issuer, JWKS URI, and audience with values from your IdP. The realm, audience, scope, and group names in these examples are illustrative identifiers.

For production, also restrict scopes, client IDs, and signature algorithms, and configure identity claims. Use the following configuration instead of the minimal example:

CREATE AUTHENTICATION INTEGRATION partner_oidc
PROPERTIES (
    'type' = 'oidc',
    'enable_jit_user' = 'true',
    'oidc.issuer' = 'https://idp.example.com/realms/doris',
    'oidc.jwks_uri' = 'https://idp.example.com/realms/doris/protocol/openid-connect/certs',
    'oidc.allowed_audiences' = 'doris-prod',
    'oidc.required_scopes' = 'doris.query',
    'oidc.allowed_client_ids' = 'grafana-doris-plugin',
    'oidc.username_claim' = 'preferred_username',
    'oidc.subject_claim' = 'sub',
    'oidc.groups_claim' = 'doris_groups',
    'oidc.extra_claims' = 'tenant,email',
    'oidc.allowed_algorithms' = 'RS256',
    'oidc.clock_skew_seconds' = '60'
);

If the integration already exists, update its properties with ALTER AUTHENTICATION INTEGRATION.

Verify that the configuration is saved:

SELECT name, type, properties, comment
FROM information_schema.authentication_integrations
WHERE name = 'partner_oidc';

Configure the authentication chain

Add the integration to the FE authentication chain in fe.conf:

authentication_chain = partner_oidc

Restart the FE after changing fe.conf. If you also use password authentication, LDAP, or other methods, retain their entries in the chain in the required authentication order.

To reuse an existing local user, ensure that:

• The user exists in VeloDB Enterprise.
• The username claim in the token matches the local username.
• The OIDC integration is included in authentication_chain.

Configure role mappings

The integration determines whether a token can authenticate. Role mappings determine which VeloDB Enterprise roles the authenticated session receives.

Create roles and grant the required object privileges to them. Then create the mapping with CREATE ROLE MAPPING:

CREATE ROLE analyst;
CREATE ROLE finance_reader;

CREATE ROLE MAPPING partner_oidc_roles
ON AUTHENTICATION INTEGRATION partner_oidc
RULE (
    USING CEL 'attr("oauth.client_id") == "grafana-doris-plugin"'
    GRANT ROLE analyst
),
RULE (
    USING CEL 'has_group("doris_finance_reader")'
    GRANT ROLE finance_reader
);

Use stable groups, client IDs, or business claims, such as tenant or environment, in authorization rules. If a scope only controls whether a user can access VeloDB Enterprise, validate it during authentication with oidc.required_scopes.

Connect with MySQL Shell

Save the access token

Save the raw access token in a local file. The file must contain only the token text, without a JSON wrapper or an ID token. For example:

eyJraWQiOiJrZXktMSIsImFsZyI6IlJTMjU2In0...

Restrict access to the file and replace or delete it when the token expires.

Establish the connection

Replace <fe-host> with your FE hostname. Replace the example file paths with the paths to your token and CA certificate. The username must match the token's username claim.

Validate the server certificate and hostname:

mysqlsh --sql --sqlc --ssl-mode=VERIFY_IDENTITY \
  --ssl-ca=/path/to/ca.pem \
  -h <fe-host> -P 9030 -u alice \
  --authentication-openid-connect-client-id-token-file=/path/to/alice.access_token \
  -e "SELECT CURRENT_USER();"

For a test environment without certificate validation, the minimum SSL mode is REQUIRED:

mysqlsh --sql --sqlc --ssl-mode=REQUIRED \
  -h <fe-host> -P 9030 -u alice \
  --authentication-openid-connect-client-id-token-file=/path/to/alice.access_token \
  -e "SELECT CURRENT_USER();"

REQUIRED encrypts the connection but does not validate the server certificate. VERIFY_CA validates the certificate's CA, and VERIFY_IDENTITY also validates the hostname.

After connecting, verify the user and privileges:

SELECT CURRENT_USER();
SHOW GRANTS;

Connect with JDBC

MySQL Connector/J 9.1.0 and later support OIDC authentication. The connection must use SSL, and idTokenFile must specify the token file's absolute path.

Note:

idTokenFile is the Connector/J property name. For VeloDB Enterprise authentication, the file must contain an access token issued for the resource server, rather than an ID token from a browser login flow.

The token file must:

• Use an absolute path.
• Exist and be readable when the application runs.
• Be no larger than 10 KiB.
• Contain only the raw access token, without a JSON wrapper.

Configure connection properties

Replace fe.example.com with your FE hostname, test with your database name, and the token file path with your local absolute path. With VERIFY_IDENTITY, the server certificate must be trusted by Java and match the hostname. For a private CA, configure a truststore as described in Configure certificate verification.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;
import java.util.Properties;

String url = "jdbc:mysql://fe.example.com:9030/test";

Properties props = new Properties();
props.setProperty("user", "alice");
props.setProperty(
        "defaultAuthenticationPlugin",
        "authentication_openid_connect_client");
props.setProperty("idTokenFile", "/absolute/path/to/alice.access_token");
props.setProperty("sslMode", "VERIFY_IDENTITY");

try (Connection connection = DriverManager.getConnection(url, props);
        Statement statement = connection.createStatement();
        ResultSet resultSet = statement.executeQuery("SELECT CURRENT_USER()")) {
    while (resultSet.next()) {
        System.out.println(resultSet.getString(1));
    }
}

Property	Description
user	Database login name. Must match the token claim specified by oidc.username_claim.
defaultAuthenticationPlugin	Explicitly selects authentication_openid_connect_client.
idTokenFile	Absolute path to the access token file.
sslMode	Controls SSL and certificate verification. VERIFY_IDENTITY validates both the certificate and hostname. REQUIRED encrypts the connection without validating the certificate.

Configure a JDBC URL

You can also put the same properties in the JDBC URL. Some connection pools or configuration systems call this field the Driver URL or Driver URI:

import java.sql.Connection;
import java.sql.DriverManager;

String url = "jdbc:mysql://fe.example.com:9030/test"
        + "?user=alice"
        + "&defaultAuthenticationPlugin=authentication_openid_connect_client"
        + "&idTokenFile=/absolute/path/to/alice.access_token"
        + "&sslMode=VERIFY_IDENTITY";

try (Connection connection = DriverManager.getConnection(url)) {
    // Use the connection to execute queries.
}

URL-encode property values that contain spaces, &, or other URL special characters.

Configure certificate verification

For production, import the CA that issued the FE certificate into a Java truststore and use VERIFY_CA or VERIFY_IDENTITY:

props.setProperty("sslMode", "VERIFY_IDENTITY");
props.setProperty(
        "trustCertificateKeyStoreUrl",
        "file:/absolute/path/to/truststore.p12");
props.setProperty("trustCertificateKeyStoreType", "PKCS12");
props.setProperty("trustCertificateKeyStorePassword", "<truststore-password>");

Replace the truststore path and <truststore-password> with your values. Set these properties before calling DriverManager.getConnection.

• VERIFY_CA validates that a trusted CA issued the server certificate.
• VERIFY_IDENTITY also validates the hostname in the certificate.

For a test environment with self-signed certificates, sslMode=REQUIRED encrypts the connection without validating the server certificate. No additional allowCustomHostnameVerification or trustServerCertificate setting is needed.

For complete client details, see the Connector/J OpenID Connect documentation and Connector/J SSL documentation.

Common errors

Cannot establish an OIDC connection

Verify that:

• fe.conf contains enable_ssl = true, and the FE has been restarted.
• MySQL Shell uses --ssl-mode=REQUIRED or a stricter mode, or Connector/J uses sslMode=REQUIRED or a stricter mode.
• The client is MySQL Shell 9.x or Connector/J 9.1.0 or later.

Token validation fails

Confirm that you are using an access token issued for VeloDB Enterprise, and check that:

• iss and aud match the integration configuration.
• The token has not expired and is already valid.
• scope, azp, or client_id meets the configured restrictions.
• The JWT signature algorithm is allowed.

Username does not match

Check the claim specified by oidc.username_claim. Its value must match MySQL Shell's -u argument or Connector/J's user property. If you reuse a local user, a user with the same name must exist in VeloDB Enterprise.

Login succeeds but privileges differ from expectations

Check that:

• Mapping rules match the token's groups, client ID, or extra claims.
• oidc.groups_claim and oidc.extra_claims are configured correctly.
• The roles granted by the mapping have privileges on the target objects.

Query information_schema.role_mappings to inspect saved rules, and use SHOW GRANTS to inspect the current session's roles.

See also

• CREATE AUTHENTICATION INTEGRATION
• ALTER AUTHENTICATION INTEGRATION
• CREATE ROLE MAPPING
• authentication_integrations
• role_mappings
• REST Catalog User Identity