Configure OpenID Connect (OIDC)/OAuth 2.0 authentication in OpsCenter

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

When you enable OIDC authentication, OpsCenter delegates identity verification to your IdP. OpsCenter receives cryptographically signed tokens from the IdP and maps user claims and group memberships to OpsCenter roles.

OpsCenter OIDC authentication flow

The OpsCenter OIDC authentication flow applies to OpsCenter web UI access and API requests.

Web UI authentication occurs through your IdP using the standard OAuth 2.0 Authorization Code flow with Proof Key for Code Exchange (PKCE):

  1. A user navigates to the OpsCenter web UI.

  2. OpsCenter creates a cryptographically random code verifier, generates a code challenge, and redirects the browser to the IdP authorization endpoint.

  3. The user enters their credentials at the IdP login page.

  4. The IdP redirects the browser back to OpsCenter at /auth/oidc/callback with an authorization code.

  5. OpsCenter sends the authorization code and the original code verifier to the IdP token endpoint.

  6. The IdP verifies the code challenge and returns an ID token and access token.

  7. OpsCenter validates the token signatures against the IdP JWKS keys, resolves user roles from the token claims, and creates an encrypted session cookie.

OpsCenter REST API authentication for scripts, CI/CD pipelines, and automated tools uses standard JSON Web Token (JWT) bearer tokens sent in the HTTP Authorization: Bearer JWT_ACCESS_TOKEN header. For an explanation of this process, see Access the REST API with bearer tokens.

Prepare your IdP

  • An active, OIDC-compliant IdP.

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

  • An application client registered in your IdP with the following:

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

    • Redirect URI (callback URL) configured to the following URL:

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

      Replace OPSCENTER_HOST and PORT with your OpsCenter server connection details. The port must accept client connections over HTTPS.

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

Map OpsCenter roles to IdP groups

Before you enable OIDC authentication, create, at minimum, an administrator role in OpsCenter that maps to an administrator group in your IdP.

A user in your IdP must belong to at least one group that maps to a role in OpsCenter. If a match cannot be found, authentication fails.

If no roles are mapped to IdP groups, all users, including administrators, are locked out of OpsCenter.

  1. Identify the groups in your IdP that you want to map to OpsCenter roles.

  2. Create roles in OpsCenter that correspond to your IdP groups, and assign the appropriate permissions to each role.

  3. If your roles and groups have different names, make note of the corresponding role for each group.

In the next steps, you will specify the group-to-role mappings as part of your OIDC configuration. Based on the OIDC configuration, OpsCenter extracts user group memberships from configured token claims and maps them to OpsCenter roles with corresponding permissions. When a user logs in, OpsCenter resolves user permissions by evaluating claims in the token:

  • OpsCenter inspects the claim specified in roles_claim. The default is groups.

  • If explicit mappings are configured in groups_to_roles (for example, /opscenter-admin → admin), OpsCenter maps matching IdP groups to the specified OpsCenter roles.

  • If any value in the user’s role claim matches a name listed in admin_group_name, OpsCenter grants the user the built-in OpsCenter admin role.

  • For all other values in the role claim, OpsCenter searches for an existing OpsCenter role with the same name and grants that role to the user.

  • If a user belongs to multiple groups mapped to different roles, OpsCenter grants the user all permissions assigned to all of their mapped roles.

Configure OIDC in opscenterd.conf

  1. Edit the opscenterd.conf file:

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

    • Tarball installations: INSTALL_DIRECTORY/conf/opscenterd.conf

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

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

    The following example uses OIDC auto-discovery. For provider-specific examples, see Configure identity providers. For all options, see OIDC configuration options.

    [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

    For the OIDC auto-discovery configuration, replace the following:

    • IDP_HOST: Host name of the IdP.

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

    • CLIENT_ID: Client ID registered in the IdP.

    • CLIENT_SECRET: Client secret generated by the IdP.

      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.

  4. 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, see Map OpsCenter roles to IdP groups.

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

  6. Save and close opscenterd.conf.

  7. Restart OpsCenter to apply the configuration changes.

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

Configure identity providers

The following sections provide configuration examples for common IdPs.

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.

OIDC configuration options

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 IdP. OpsCenter queries the standard OIDC discovery document at <issuer>/.well-known/openid-configuration, and it validates the iss claim in all JWT tokens against this value.

client_id

Required

OAuth 2.0 client identifier registered with the IdP.

client_secret

Required

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

redirect_uri

Required

Redirect callback URL in the form of 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.

OpsCenter fetches the provider JSON Web Key Set (JWKS) at startup, caches keys in memory, and validates token signatures, expiration timestamps, audience, and issuer on every request.

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

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

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