Configure OpenID Connect (OIDC) / OAuth 2.0 authentication

Configure OpsCenter to authenticate users through an OpenID Connect (OIDC) or OAuth 2.0 identity provider (IdP).

OpsCenter supports any OIDC-compliant identity provider, such as Keycloak, Okta, Microsoft Entra ID (Azure AD), Auth0, and Google.

Prerequisites

  • An active, OIDC-compliant identity provider.

  • An application client registered in your IdP with:

    • Client authentication enabled (Client ID and Client Secret).

    • Redirect URI (callback URL) configured as:

      https://OPSCENTER_HOST:PORT/auth/oidc/callback

      Replace the following:

      • OPSCENTER_HOST: Host name or IP address of the OpsCenter server.

      • PORT: HTTPS port for client connections to OpsCenter.

  • The OIDC issuer URL from your identity provider. For example, https://keycloak.example.com/realms/myrealm or https://dev-12345.okta.com/oauth2/default.

  • Manage OpsCenter users and roles that correspond to your IdP groups.

    OpsCenter requires at least one matching role for a user to log in. If no IdP groups or roles match a role in OpsCenter, authentication fails and users (including administrators) will be locked out.

Configure OIDC in opscenterd.conf

To enable and configure OIDC authentication in OpsCenter, edit opscenterd.conf:

  1. Locate the opscenterd.conf file:

    • Package installations: /etc/opscenter/opscenterd.conf

    • Tarball installations: INSTALL_DIRECTORY/conf/opscenterd.conf

  2. Open opscenterd.conf in an editor.

  3. In the [authentication] section, enable authentication and specify the OIDC authentication method:

    [authentication]
password_db = ./passwd.db
enabled = True
authentication_method = com.datastax.opscenter.auth.http.impl.OIDCStrategyProvider

  4. Add an [authentication_provider] section to configure the connection to your IdP.

    The following example uses OIDC auto-discovery. For provider-specific examples and parameter descriptions, see Configure identity providers and Configuration values.

    [authentication_provider]
issuer = https://IDP_HOST/REALM_OR_TENANT
client_id = CLIENT_ID
client_secret = CLIENT_SECRET
redirect_uri = https://OPSCENTER_HOST:PORT/auth/oidc/callback
roles_claim = ROLES_CLAIM
admin_group_name = ADMIN_GROUP_NAME

    Replace the following:

    • IDP_HOST: Host name of the identity provider.

    • REALM_OR_TENANT: Realm or tenant path for your identity provider. OpsCenter appends /.well-known/openid-configuration to the issuer URL to discover endpoint URLs automatically.

    • CLIENT_ID: Client ID registered in the identity provider.

    • CLIENT_SECRET: Client secret generated by the identity provider.

      In production environments, protect the client secret with configuration encryption.

    • OPSCENTER_HOST: Host name or IP address of the OpsCenter server.

    • PORT: HTTPS port of the OpsCenter server. Ensure that this matches the redirect URI registered in the IdP.

    • ROLES_CLAIM: Token claim containing user roles or group memberships. The default is groups.

    • ADMIN_GROUP_NAME: Comma-separated list of group or role names from the IdP that map to the OpsCenter admin role.

  5. Configure group and role mappings so IdP users receive the correct permissions in OpsCenter:

    • Map administrator groups by setting admin_group_name to the IdP group or role names that should receive the built-in OpsCenter admin role.

    • (Optional) Use groups_to_roles to define explicit mappings between IdP groups and OpsCenter roles (for example, /opscenter-admin → admin, /opscenter-dev → dev).

    • If groups_to_roles is not specified, OpsCenter automatically searches for an existing OpsCenter role whose name matches the group or role name in the token claim.

      For more information about how OpsCenter resolves roles, see Role and permission mapping.

  6. Specify the endpoint URLs explicitly if the IdP does not support automatic discovery, or if you need to override default endpoints.

    The issuer property is required even when you specify endpoints explicitly because OpsCenter validates the iss claim in all tokens against this value.

    [authentication_provider]
issuer = https://IDP_HOST
authorization_endpoint = https://IDP_HOST/oauth2/authorize
token_endpoint = https://IDP_HOST/oauth2/token
jwks_uri = https://IDP_HOST/.well-known/jwks.json
userinfo_endpoint = https://IDP_HOST/oauth2/userinfo
end_session_endpoint = https://IDP_HOST/oauth2/logout
client_id = CLIENT_ID
client_secret = CLIENT_SECRET
redirect_uri = https://OPSCENTER_HOST:PORT/auth/oidc/callback

  7. Save and close opscenterd.conf.

  8. Restart OpsCenter to apply the configuration changes.

  9. Connect to OpsCenter in a web browser at http://opscenter-host:8888/. OpsCenter redirects you to your identity provider login page.

Configure identity providers

The following sections provide configuration examples for common identity providers.

Configure Keycloak

To configure Keycloak:

  1. In Keycloak, create a client with Client authentication set to ON.

  2. Set Valid redirect URIs to https://**OPSCENTER_HOST**:**PORT**/auth/oidc/callback.

  3. In the client scopes or mappers, add a mapper to include realm or client roles in the token under the groups or roles claim.

  4. Add the following configuration to opscenterd.conf:

    [authentication]
password_db = ./passwd.db
enabled = True
authentication_method = com.datastax.opscenter.auth.http.impl.OIDCStrategyProvider

[authentication_provider]
issuer = https://KEYCLOAK_HOST/realms/REALM_NAME
client_id = CLIENT_ID
client_secret = KEYCLOAK_CLIENT_SECRET
redirect_uri = https://OPSCENTER_HOST:PORT/auth/oidc/callback
roles_claim = groups
admin_group_name = ADMIN_GROUP_NAME
groups_to_roles = KEYCLOAK_GROUP -> OPSCENTER_ROLE

    Replace the following:

    • KEYCLOAK_HOST: Host name of the Keycloak server.

    • REALM_NAME: Keycloak realm name.

    • CLIENT_ID: Keycloak client ID.

    • KEYCLOAK_CLIENT_SECRET: Client secret from Keycloak.

    • OPSCENTER_HOST: Host name or IP address of the OpsCenter server.

    • PORT: HTTPS port of the OpsCenter server.

    • ADMIN_GROUP_NAME: Keycloak group or role that maps to the OpsCenter admin role.

    • KEYCLOAK_GROUP → OPSCENTER_ROLE: (Optional) Explicit mapping from Keycloak groups to OpsCenter roles.

Configure Okta

To configure Okta:

  1. In Okta, create an App Integration with sign-in method OIDC - OpenID Connect and application type Web Application.

  2. Set Sign-in redirect URIs to https://**OPSCENTER_HOST**:**PORT**/auth/oidc/callback.

  3. Configure the token claims to include a groups claim containing the user’s group assignments.

  4. Add the following configuration to opscenterd.conf:

    [authentication]
password_db = ./passwd.db
enabled = True
authentication_method = com.datastax.opscenter.auth.http.impl.OIDCStrategyProvider

[authentication_provider]
issuer = https://OKTA_DOMAIN/oauth2/default
client_id = OKTA_CLIENT_ID
client_secret = OKTA_CLIENT_SECRET
redirect_uri = https://OPSCENTER_HOST:PORT/auth/oidc/callback
groups_claim = groups
admin_group_name = ADMIN_GROUP_NAME
groups_to_roles = OKTA_GROUP -> OPSCENTER_ROLE

    Replace the following:

    • OKTA_DOMAIN: Okta domain (for example, dev-12345.okta.com).

    • OKTA_CLIENT_ID: Okta client ID.

    • OKTA_CLIENT_SECRET: Okta client secret.

    • OPSCENTER_HOST: Host name or IP address of the OpsCenter server.

    • PORT: HTTPS port of the OpsCenter server.

    • ADMIN_GROUP_NAME: Okta group that maps to the OpsCenter admin role.

    • OKTA_GROUP → OPSCENTER_ROLE: (Optional) Explicit mapping from Okta groups to OpsCenter roles.

Configure Microsoft Entra ID (Azure AD)

To configure Microsoft Entra ID:

  1. In the Microsoft Entra admin center, register a new application.

  2. Under Authentication, add a Web platform and set the redirect URI to https://**OPSCENTER_HOST**:**PORT**/auth/oidc/callback.

  3. Under Certificates & secrets, generate a new client secret.

  4. Under Token configuration, add a group claim or role claim.

  5. Add the following configuration to opscenterd.conf:

    [authentication]
enabled = True
authentication_method = com.datastax.opscenter.auth.http.impl.OIDCStrategyProvider

[authentication_provider]
issuer = https://login.microsoftonline.com/TENANT_ID/v2.0
client_id = AZURE_CLIENT_ID
client_secret = AZURE_CLIENT_SECRET
redirect_uri = https://OPSCENTER_HOST:PORT/auth/oidc/callback
roles_claim = roles
admin_group_name = ADMIN_ROLE_NAME
groups_to_roles = ENTRA_GROUP -> OPSCENTER_ROLE

    Replace the following:

    • TENANT_ID: Microsoft Entra directory (tenant) ID.

    • AZURE_CLIENT_ID: Application (client) ID.

    • AZURE_CLIENT_SECRET: Client secret value.

    • OPSCENTER_HOST: Host name or IP address of the OpsCenter server.

    • PORT: HTTPS port of the OpsCenter server.

    • ADMIN_ROLE_NAME: Microsoft Entra role or group that maps to the OpsCenter admin role.

    • ENTRA_GROUP → OPSCENTER_ROLE: (Optional) Explicit mapping from Microsoft Entra groups or roles to OpsCenter roles.

Configuration values

The following table describes configuration options available under the [authentication_provider] section when authentication_method is set to com.datastax.opscenter.auth.http.impl.OIDCStrategyProvider.

Option Required / Default Description

issuer

Required

Base OIDC discovery URL of the identity provider. OpsCenter queries <issuer>/.well-known/openid-configuration for discovery and validates the iss claim in all JWT tokens against this value.

client_id

Required

OAuth 2.0 client identifier registered with the identity provider.

client_secret

Required

OAuth 2.0 client secret. In production environments, encrypt this value using configuration encryption.

redirect_uri

Required

Redirect callback URL (https://<opscenter-host>:<port>/auth/oidc/callback). Must match the redirect URI registered in the IdP.

roles_claim

groups

JWT token claim containing user roles or group memberships.

admin_group_name

None

Comma-separated list of IdP group or role names mapped to the OpsCenter admin role.

groups_to_roles

None

Maps IdP groups to OpsCenter roles. Specify one mapping per line using the format IDP_GROUP → OPSCENTER_ROLE. When specified, OpsCenter uses these explicit mappings instead of matching group names directly to role names. For example, groups_to_roles = /opscenter-admin → admin.

authorization_endpoint

Auto-discovered

IdP authorization endpoint URL for browser login redirects.

token_endpoint

Auto-discovered

IdP token endpoint URL for authorization code and token exchanges.

jwks_uri

Auto-discovered

IdP JSON Web Key Set (JWKS) URL for public key retrieval and signature verification.

userinfo_endpoint

Auto-discovered

IdP userinfo endpoint URL for supplementary user claims.

end_session_endpoint

Auto-discovered

IdP logout endpoint URL for single logout.

Access the REST API with bearer tokens

When OIDC authentication is enabled, applications and scripts can access the OpsCenter REST API using JWT bearer tokens:

  1. A client or user requests a JWT access token directly from the identity provider using the OAuth 2.0 Client Credentials or the Resource Owner Password flow.

  2. Include the access token in the Authorization header of API requests.

    For example:

    curl -H "Authorization: Bearer JWT_ACCESS_TOKEN" https://OPSCENTER_HOST:PORT/cluster-configs

    Replace the following:

    • JWT_ACCESS_TOKEN: JSON Web Token access token obtained from the identity provider.

    • OPSCENTER_HOST: Host name or IP address of the OpsCenter server.

    • PORT: HTTPS port of the OpsCenter server.

OpsCenter validates the bearer token signature and claims against the IdP JWKS keys without creating a session cookie or requiring an interactive web session.

Troubleshooting

Follow these troubleshooting steps to diagnose and resolve common OIDC configuration issues.

Verify OIDC discovery from the OpsCenter server

Run curl from the OpsCenter host to confirm network connectivity and discovery metadata accessibility:

curl -s https://IDP_HOST/REALM_OR_TENANT/.well-known/openid-configuration | grep jwks_uri
Inspect authentication log output

Check opscenterd.log for authentication and claim extraction errors:

grep -i oidc /var/log/opscenter/opscenterd.log
User cannot log in or receives unauthorized error

  • Verify that the user belongs to at least one group in the IdP that matches a defined role in OpsCenter.

  • Verify that the system clock on the OpsCenter server synchronizes with an NTP server. Large time discrepancies cause token expiration and validation failures.

Redirect URI mismatch

Ensure that the redirect_uri configured in opscenterd.conf matches the redirect URI registered in the IdP, including protocol (https), host name, port, and the path /auth/oidc/callback.

TLS or certificate validation failures

If your identity provider uses certificates signed by an internal or custom Certificate Authority (CA), import the CA certificate into the Java truststore used by OpsCenter:

keytool -importcert -alias idp-ca \
  -file /path/to/ca-cert.pem \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit -noprompt

See also

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | 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: Contact IBM