Configure OpenID Connect (OIDC) authentication

OpenID Connect (OIDC) authentication enables your Hyper-Converged Database (HCD) database to authenticate clients using JSON Web Token (JWT)-based access tokens. This authentication method enables you to integrate database authentication with organization-wide, modern identity providers (IdPs) such as Keycloak.

Database authentication workflow for OIDC

HCD supports OIDC authentication through the following workflow:

  1. Users authenticate through the Keycloak server using their own credentials.

  2. The Keycloak server issues a JWT access token.

  3. The Keycloak server sends the access token to the client application, such as a driver or cqlsh, and then the application sends the token to the HCD database for authentication.

  4. HCD validates the token and looks for a valid user name and roles.

  5. Upon successful validation, HCD grants access and authorization to the user.

Prerequisites

  • HCD version 1.2.0 or later

  • An OIDC-compliant IdP, such as Keycloak

  • A database configuration naming convention that matches with your Keycloak settings

HCD database server configuration

Configure the following settings in your cassandra.yaml file to enable OIDC authentication:

authenticator:
  class_name: com.datastax.cassandra.auth.AdvancedAuthenticator
  parameters:
    enabled: true
    default_scheme: internal
    additional_schemes: oidc
    oidc_issuer: IDP_URL
    oidc_accepted_audience: ALLOWED_CLIENTS
    oidc_user_name_claim: USER_NAME_CLAIM
    oidc_user_roles_claims: USER_ROLES_CLAIMS
    oidc_use_tls: TLS_VALUE
    oidc_truststore_path: TRUSTSTORE_PATH
    oidc_truststore_password: TRUSTSTORE_PASSWORD
    oidc_truststore_type: TRUSTSTORE_TYPE

Replace the following:

  • IDP_URL: The URL of the OIDC authentication server for your IdP.

  • ALLOWED_CLIENTS: A comma-separated list of your allowed OIDC client IDs. By default, the system accepts all clients. The accepted_audience parameter is a comma-separated list of all OIDC client IDs.

  • USER_NAME_CLAIM: The JWT claim that identifies the user in the database. If you set this option, you must configure this claim at the top-level of the JSON access token. The default value is the preferred_username claim.

  • USER_ROLES_CLAIMS: The JWT claim that contains user roles. Add a comma-separated list of claims. For example, set this to resource_access.CLIENT_ID.roles to use the roles you configured for a Keycloak client named CLIENT_ID. To grant privileges, define the claims in the database before you specify the roles in these claims.

  • TLS_VALUE: Enable or disable TLS encryption for OIDC server connections. The default value is true when you enable the oidc_truststore_path option. If you set oidc_use_tls to false, this value does not change independently when you set the oidc_truststore_path option.

  • TRUSTSTORE_PATH: The path to your truststore. When you configure this option, the oidc_use_tls option defaults to true.

  • TRUSTSTORE_PASSWORD: The password for your truststore.

  • TRUSTSTORE_TYPE: The type of truststore. The system automatically sets the type as jks for .keystore or .jks files and as pkcs12 for PKCS12 files such as .p12, .pkcs12, or .pfx. You can also set this option manually.

Required parameters

Parameter Description

oidc_issuer

The URL of the OIDC endpoint for your IdP.

Optional parameters

Parameter Description

oidc_accepted_audience

A comma-separated list of accepted OIDC client IDs.

The system accepts all clients if you don’t specify this option. DataStax recommends that you configure this option for production environments.

oidc_user_name_claim

The JWT claim that identifies the user in the database.

The system uses preferred_username by default.

oidc_user_roles_claims

A comma-separated list of claims that identify user roles in the database. For example, set this to realm_roles.roles to use OIDC Realm roles. The system ignores roles if the claim doesn’t exist or contains invalid elements. Create all roles in the database before you use them in claims.

oidc_use_tls

Enables TLS encryption for OIDC server connections.

The system sets this to false by default.

oidc_truststore_path

The path to the truststore that contains valid certificates for OIDC server connections.

oidc_truststore_password

The password for the truststore.

oidc_truststore_type

The type of truststore, either JKS or PKCS12. By default, OIDC selects a truststore type based on the keystore extension: * jks is set based on the jks and .keystore extensions * pkcs12 is set based on the .p12 and .pfx extensions

Role configuration

When you enable OIDC authentication, a Keycloak client must inherit permissions from a HCD internal role to access database resources. The role you assign to a client must have the LOGIN privilege to access the database.

There are two ways to match Keycloak clients to HCD roles:

User matching

Authenticate and authorize by matching a user. You can configure either an individual account or a service account as a user. HCD uses the Keycloak client name from the JWT preferred_username claim to map to the specified HCD internal role. The following example matches a service account to a role:

CREATE ROLE service-account-db-m2m-client WITH LOGIN = true;
GRANT ALL PERMISSIONS ON KEYSPACE KEYSPACE_NAME TO service-account-db-m2m-client;

Role-based matching

You can also map Keycloak client roles defined in the JWT claim to HCD internal roles. After you define the Keycloak client role, you must configure the database to recognize the client role and match it to your database internal roles, which provide LOGIN permissions and database privileges. Note that the Keycloak client role name must match the HCD internal role name.

CREATE ROLE db_access WITH LOGIN = true;
GRANT ALL PERMISSIONS ON KEYSPACE KEYSPACE_NAME TO db_access;

Configure user_roles_claims: resource_access.CLIENT_ID.roles in the cassandra.yaml file to map a client identifier to the appropriate roles.

Client configuration

In addition to making server-side changes in the configuration file for your HCD database, you have several options to configure OIDC on the client-side. Options include a Java driver, the CQL shell, the Kafka sink, and the Spark Connector.

Java driver configuration

To complete your database configuration, you must configure a client authentication plugin for the Java language. To configure the Java plug-in, use the following steps:

  1. Get an access token from your IdP.

  2. Download and install the OIDC Authentication Provider plugin for Java from the DataStax Downloads site.

  3. Configure the Java driver to use OIDC authentication:

String accessToken = "ACCESS_TOKEN";
OIDCAuthProvider keycloakAuthProvider = new OIDCAuthProvider(accessToken);

try (CqlSession session = CqlSession.builder()
        .withAuthProvider(keycloakAuthProvider)
        .build()) {
    // Include the rest of your database operations options here
}

As a second option, you can configure the Java driver to perform the Client Credentials flow and re-authenticate automatically after the access token expires:

import com.datastax.db.driver.api.plugin.auth.OIDCClientCredentialsAuthProvider;

...

URI issuer = new URI("IDP_URL");
String clientID = "CLIENT_ID";
String clientSecret = "CLIENT_SECRET"
boolean useTLS = true;  // default
Path truststorePath = new File(TRUSTSTORE_PATH).toPath();  // optional truststore path
String truststorePassword = "TRUSTSTORE_PASSWORD";

OIDCClientCredentialsAuthProvider authProvider = new OIDCClientCredentialsAuthProvider(
                issuer, clientID, clientSecret, useTLS, truststorePath, truststorePassword);
        try (CqlSession session = CqlSession.builder().withAuthProvider(authProvider).build())
        {

Replace the following:

  • IDP_URL: The URL of the OIDC authentication server for your IdP.

  • CLIENT_ID: The client ID for your OIDC client. You must configure this option for all flow types.

  • CLIENT_SECRET: The client secret for your OIDC client. You must include this option when you configure the Client Credentials flow, or Authorization Code flow with private clients.

  • TRUSTSTORE_PATH: The full absolute path to your truststore file.

  • TRUSTSTORE_PASSWORD: Password for your truststore.

CQL shell configuration

For CQL shell, there are two ways to configure OIDC authentication:

  • Authorization Code flow: You must specify a client ID and set the default auth_flow option to code.

  • Client Credentials flow: You must specify both a client ID and a client secret. You must also set the auth_flow option to client.

To configure the CQL shell to use OIDC authentication, select one of the two configuration options and add the following to the ~/.cassandra/cqlshrc file:

[auth_provider]
module = datastax_db_auth.auth
classname = AdvancedAuthProvider
issuer_url = IDP_URL
auth_flow = AUTH_FLOW_VALUE
client_id = CLIENT_ID
client_secret = CLIENT_SECRET
truststore = /TRUSTSTORE_PATH/truststore.pem
ssl_verify = SSL_VALUE
callback_url = CALLBACK_URL
callback_port = CALLBACK_PORT
browser_auto_open = BROWSER_AUTO_OPEN_VALUE

Replace the following:

  • IDP_URL: The URL of the OIDC authentication server for your IdP.

  • AUTH_FLOW_VALUE: Specifies the type of OIDC authorization flow. Supported values:

    • code: Uses the Authorization Code flow (default).

    • client: Uses the Client Credentials flow.

  • CLIENT_ID: The client ID for your OIDC client. You must configure this option for all flow types.

  • CLIENT_SECRET: The client secret for your OIDC client. You must include this option when you configure the Client Credentials flow, or configure the Authorization Code flow with private clients. Omit this option when you configure the Authorization Code flow with public clients.

  • TRUSTSTORE_PATH: The full absolute path to your truststore file.

  • SSL_VALUE: Enables or disables TLS for connections to the IdP server. Supported values:

    • true: Enables TLS (default). DataStax recommends that you enable TLS for production environments.

    • false: Disables TLS.

  • CALLBACK_URL: The callback URL used for the Authorization Code flow, for example /oauth/callback.

  • CALLBACK_PORT: The callback port used for the Authorization Code flow. When you set the port to the default value of zero (0), OIDC uses ephemeral ports.

  • BROWSER_AUTO_OPEN_VALUE: Controls whether a browser window opens automatically when using the Authorization Code flow. Supported values:

    • true: Opens the browser window automatically (default).

    • false: You must open a browser window manually and enter the URL.

Kafka sink configuration

You can configure a Kafka sink to integrate with OIDC. Kafka Sink uses the options you configure in the sink-config.json file and adds them into the Java driver. To configure a Kafka sink with OIDC, use the following steps:

  1. Download and install the OIDC Authentication Provider plugin for Java from the DataStax Downloads site.

  2. Download the latest version of the Kafka sink uber-jar file from the Kafka sink GitHub page.

  3. Add the OIDC Java plug-in and Kafka sink uber-jar file to Kafka Connect.

  4. Set the CLASSPATH environment variable in Kafka Connector.

  5. Configure the Kafka sink client through the sink-config.json file.:

{
 "name": "dse-sink",
 "config": {
   "connector.class": "com.datastax.kafkaconnector.DseSinkConnector",
   "tasks.max": "1",
   "topics": "TOPIC-NAME",
   "contactPoints": "dse",
   "loadBalancing.localDc": "Cassandra",

   "topic.my_topic.testks.messages.mapping": "id=value.id, msg=value.msg",
   "topic.my_topic.testks.messages.consistencyLevel": "LOCAL_ONE",

   "key.converter": "org.apache.kafka.connect.storage.StringConverter",
   "value.converter": "org.apache.kafka.connect.json.JsonConverter",
   "value.converter.schemas.enable": "false",

   "datastax-java-driver.advanced.auth-provider.class": "com.datastax.db.driver.api.plugin.auth.OIDCClientCredentialsAuthProvider",
   "datastax-java-driver.advanced.auth-provider.oidc.issuer": "IDP_URL",
   "datastax-java-driver.advanced.auth-provider.oidc.client-id": "CLIENT_ID",
   "datastax-java-driver.advanced.auth-provider.oidc.client-secret": "CLIENT_SECRET",
   "datastax-java-driver.advanced.auth-provider.oidc.use-tls": "TLS_VALUE",
   "datastax-java-driver.advanced.auth-provider.oidc.truststore-path": "TRUSTSTORE_PATH",
   "datastax-java-driver.advanced.auth-provider.oidc.truststore-password": "TRUSTSTORE_PASSWORD"
 }
}

Replace the following:

  • IDP_URL: The URL of the OIDC authentication server for your IdP.

  • CLIENT_ID: The client ID for your OIDC client. You must configure this option for all flow types.

  • CLIENT_SECRET: The client secret for your OIDC client. You must include this option when you configure the Client Credentials flow, or Authorization Code flow with private clients.

  • TLS_VALUE: Enables or disables TLS encryption for OIDC server connections. Supported values:

    • true: Enables TLS (default). This option loads the OS default truststore containing all certificates installed globally.

    • false: Disables TLS.

  • TRUSTSTORE_PATH: The full absolute path to your truststore file.

  • TRUSTSTORE_PASSWORD: Password for your truststore.

Spark Connector configuration

You can configure a Spark Connector to integrate with OIDC. The Spark Connector loads the configuration from the default application.conf file for the Java driver. To configure a Spark Connector with OIDC, use the following steps:

  1. Use Client Credentials flow for your OIDC environment.

  2. Download and install the OIDC Authentication Provider plugin for Java from the DataStax Downloads site.

  3. Add the OIDC Authentication Provider plugin uber-jar file to your CLASSPATH environment variable of Kafka Connect. For example, if you configure CLASSPATH=/kafka-connectors/* as your environment variable, Spark Connector expects the OIDC Authentication Provider plugin to be available in the /kafka-connectors/ directory.

  4. Configure the application.conf file for your Spark Connector client:

    datastax-java-driver {
    basic.contact-points = ["localhost:9042"]
    advanced.auth-provider {
        class = "com.datastax.db.driver.api.plugin.auth.OIDCClientCredentialsAuthProvider"

        oidc {
            issuer = "IDP_URL"
            client-id = "CLIENT_ID"
            client-secret = "CLIENT_SECRET"
            use-tls = "TLS_VALUE"
            truststore-path = "/TRUSTSTORE_PATH"
            truststore-password = "TRUSTSTORE_PASSWORD"
        }
    }
}

    Replace the following:

    • IDP_URL: The URL of the OIDC authentication server for your IdP.

    • CLIENT_ID: The client ID for your OIDC client. You must configure this option for all flow types.

    • CLIENT_SECRET: The client secret for your OIDC client. You must include this option when you configure the Client Credentials flow, or Authorization Code flow with private clients.

    • TLS_VALUE: Enables or disables TLS encryption for OIDC server connections. Supported values:

      • true: Enables TLS (default). This option loads the OS default truststore containing all certificates installed globally.

      • false: Disables TLS.

    • TRUSTSTORE_PATH: The full absolute path to your truststore file.

    • TRUSTSTORE_PASSWORD: Password for your truststore.

  5. Set the application.conf file in your CLASSPATH environment variable. For more information about the application.conf file and the classpath, see the DataStax Java Driver.

  6. Configure a set of environment variables as substitutions:

    spark-submit --master local \
  --name word-ingest-oss \
  --conf spark.executor.extraJavaOptions=-Dconfig.override_with_env_vars=true \
  --conf spark.driver.extraJavaOptions=-Dconfig.override_with_env_vars=true \
  --driver-java-options -Dconfig.override_with_env_vars=true \
  --class com.datastax.examples.spark.RollupApp \
  local:///Users/USERNAME/src/COMPANY/spark/word-sample-oss/target/scala-2.12/word-spark-oss-assembly-0.1.0-SNAPSHOT.jar

  7. Enter the following environment variables to enable OIDC:

CONFIG_FORCE_datastaxjavadriver_advanced_authprovider_class="com.datastax.db.driver.api.plugin.auth.OIDCClientCredentialsAuthProvider"
CONFIG_FORCE_datastaxjavadriver_advanced_authprovider_oidc_issuer="IDP_URL"
CONFIG_FORCE_datastaxjavadriver_advanced_authprovider_oidc_clientid="CLIENT_ID"
CONFIG_FORCE_datastaxjavadriver_advanced_authprovider_oidc_clientsecret="CLIENT_SECRET"
CONFIG_FORCE_datastaxjavadriver_advanced_authprovider_oidc_usetls="TLS_VALUE"

Replace the following:

  • IDP_URL: The URL of the OIDC authentication server for your IdP.

  • CLIENT_ID: The client ID for your OIDC client. You must configure this option for all flow types.

  • CLIENT_SECRET: The client secret for your OIDC client. You must include this option when you configure the Client Credentials flow, or Authorization Code flow with private clients.

  • TLS_VALUE: Enables or disables TLS encryption for OIDC server connections. Supported values:

    • true: Enables TLS (default). This option loads the OS default truststore containing all certificates installed globally.

    • false: Disables TLS.

Keycloak configuration

The following steps describe how to configure a Keycloak server to provide OIDC authentication for your HCD database. The steps assume that you have installed the Keycloak server, logged in with administrator privileges, and configured realms. Be careful to use the same names for claims and roles in Keycloak as you do in your HCD database.

Configure a machine-to-machine client

You can configure a new client or reuse an existing one. You can also use the same client for either the Client Credentials flow for machine-to-machine authentication, or the Authorization Code flow for application client authentication. If you reuse an existing client, confirm that you enabled the supported authorization flows. If you create a new client, enable the authorization flows that you want to support.

  1. Create a client called db-m2m-client.

  2. Enable Client authentication and Client authorization. This step creates a username of service-account-db-m2m-client.

  3. Go to Credentials and copy the Client Secret used for the Client Credentials flow with this client.

Configure an application client

  1. Create a client called db-app-client.

  2. Enable Standard flow only.

  3. Disable Direct access grants.

  4. For public clients, leave authentication and authorization off. For private clients, enable authentication and authorization and add a client secret.

  5. Click Save.

  6. Optional: To use PKCS:

    1. Edit the client.

    2. Click on the Advanced tab.

    3. Scroll down to Advanced settings.

    4. Optional: Select S256 for the Proof Key for Code Exchange Code Challenge Method option. Do not set this option if you want to use the client for both Standard Auth and Standard Auth with PKCS.

Create a client role

  1. Go to Clients > db_app_client > Roles > Create role.

  2. Create a role called db_access.

Create a group and apply roles

  1. Go to Groups > Create group.

  2. Name the group as db_group.

  3. Click db_group.

  4. Edit the group and apply the db_access role.

In the following example, you create a client named db_app_client and a client role named db_access. You assign the db_access role to all users in a group named db_group. This configuration enables the database to read the JWT access token and match with the db_access internal database role.

{
  "exp": 1749743078,
  "iat": 1749742778,
  ...,
  "resource_access": {
    "db_app_client": {
      "roles": [
        "db_access",
        ...
      ]
    }
  },
  ...,
  "client_id": "db_app_client"
}

In your HCD database, you must match the IdP configuration by configuring the following options:

  • Configure the dse.yaml file with user_roles_claims: resource_access.db-app-client.roles.

  • Configure the db_access role and assign LOGIN permissions and database privileges.

As an alternative to matching on the client role, you can also map roles by defining a direct match with the JWT preferred_username or similar configurable claim.

Create a user

  1. Click Users.

  2. Click Create new user.

  3. Name the user as db_user.

  4. Add db_user to the db_group.

  5. Click the db_user Credentials tab.

  6. Set a password.

  7. Set Temporary to off.

Security considerations

  • Enable TLS encryption in production environments.

  • Configure proper truststore settings with valid certificates.

  • Rotate client secrets and access tokens regularly.

  • Implement proper token validation and expiration handling.

  • Use appropriate role-based access control (RBAC) with your OIDC roles.

  • Remember that Keycloak provides authentication services, but HCD handles authorization by using Cassandra roles.

Limitations

  • Refresh tokens are not supported.

  • The ability to end a client’s access directly from the Keycloak UI is not supported.

Troubleshooting

Common issues

Issue Solution

Authentication failures

Check your OIDC configuration, including issuer URL and client credentials.

TLS connection errors

Verify that your truststore contains valid certificates and the correct password.

Role mapping issues

Ensure that roles in your OIDC tokens match the roles defined in your database.

See also

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax | Privacy policy | Terms of use | Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com