Configure SSO for Confluent Control Center using OIDC on Confluent Platform

You can configure single sign-on (SSO) using OpenID Connect (OIDC), built on top of the OAuth 2.0 protocol, to enable users to use a single security credential, from your identity provider (IdP), to seamlessly authenticate to Confluent Control Center and to Confluent Cloud.

You can configure SSO for Confluent Control Center using OIDC in the following ways:

Prerequisites

Identity provider (IdP)

  • Must be OIDC-compliant. SAML is not supported. Note that OIDC is more robust and easier to set up.
  • An OIDC-compliant identity provider, with optional multi-factor authentication (MFA). Details about following identity providers are included: Okta, Microsoft Entra ID (Azure Active Directory), and Keycloak.

Confluent Platform

  • Confluent Platform 7.5.0 or later. All components should be upgraded.

    Note

    SSO for Confluent Control Center using OIDC cannot be used with both on-premises Confluent Platform clusters, where your Confluent Control Center is self-managed, and Confluent Cloud clusters, which use SAML for SSO.

  • Role-based access control (RBAC) must be enabled.

Configure SSO using OIDC

Step 1 - Establish a trust relationship between Confluent Platform and identity provider

Identity provider checklist

Use the following steps to ensure that your identity provider is configured correctly:

Create a client application

Create an OpenID Connect (OIDC) application configured with authorization code grant type in your identity provider (IdP).

Warning

Microsoft Entra ID (Azure Active Directory) users must create a separate registered application for OAuth. Do not combine OAuth together with SAML in a single application configuration. Such a dual configuration can lead to issues with single sign-on (SSO) and other authentication flows.

Following are some links to help you get started:

Add a redirect URL

Add a redirect (callback) URL to Confluent Control Center on Confluent Platform in the client application

The URL should follow this format:

https://<c3-hostname>:<c3-port>/api/metadata/security/1.0/oidc/authorization-code/callback
Enable identity tokens

Identity tokens are enabled by default when you create an OIDC application in your identity provider. Following is information specific to some common identity providers:

Enable refresh tokens
  • Okta: Check the Refresh Token option in the Grant type section of the Applications page.
  • Microsoft Entra ID (Azure Active Directory)
  • Keycloak: Refresh tokens are enabled by default. For more information, see: Authorization Code Flow.
Include group claims

Include group claims in the ID tokens. Following are some details and links to help you get started.

Assign users to the client application

Assign users to the client application in your identity provider. If you are using groups to control access to Confluent Control Center, assign users to the groups.

Get the identity provider endpoints

You can use the OpenID provider configuration response to get the identity provider endpoints required to fetch, authorize, and verify tokens. Use the OIDC metadata discovery URI listed below for your identity provider to get the following identity provider endpoints and save them for later use:

  • Token endpoint URL (token_endpoint)
  • Authorization endpoint URL (authorization_endpoint)
  • JSON Web Key Set (JWKS) URL (jwks_uri)
  • Issuer URL (issuer)
Microsoft Entra ID (Azure Active Directory)
https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration

For more information, see:

Okta
https://<okta-domain>/oauth2/default/.well-known/openid-configuration

For more information, see /.well-known/openid-configuration [Okta documentation].

Keycloak
https://<keycloak-domain>/realms/<realm-name>/.well-known/openid-configuration

For more information, see Using OpenID Connect to secure applications and services.

Get the client credential details

From the client application created in the identity provider, get the following client credentials and save them for later use:

  • Client ID (client_id)
  • Client secret (client_secret)

Configure identity provider client credentials and endpoints

On each Confluent Server broker and Control Center node, add or update the following parameters in the Confluent Platform broker configuration file using the endpoints obtained in Get the identity provider endpoints above.

confluent.oidc.idp.issuer=<issuer>
confluent.oidc.idp.jwks.endpoint.uri=<jwks_uri>
confluent.oidc.idp.authorize.base.endpoint.uri=<authorization_endpoint>
confluent.oidc.idp.token.base.endpoint.uri=<token_endpoint>
confluent.oidc.idp.client.id=<client-id>
confluent.oidc.idp.client.secret=<client-secret>

Configure group authorization

You can use group authorization to control access of users to any resource, for example, a Confluent Platform cluster or a topic. In the identity provider, make sure that you have created the groups and assigned users to them.

In a Confluent Platform cluster, the DefaultPrincipalBuilder creates a KafkaPrincipal that does not include groups. This becomes evident during interactions between the Confluent Control Center and Confluent Server brokers. For example, when using the KafkaAdminClient to retrieve topics, the DefaultPrincipalBuilder produces the KafkaPrincipal.

In contrast, the OAuthKafkaPrincipalBuilder employs an OAuthBearer token to generate a KafkaPrincipal. This builder also incorporates groups, allowing them to be passed to the authorizer where necessary.

To configure group authorization in a Confluent Platform cluster, you must add the following parameters to the Confluent Platform broker configuration file on each Confluent Server broker.

  • The confluent.oidc.idp.groups.claim.name is required and must match the value of the groups claim configured in your identity provider.
    • The default value is groups, but might need changing it depending on your identity provider setup.
    • If the values do not match, problems occur during authorization.
  • By using the OAuthKafkaPrincipalBuilder, the KafkaPrincipal can include groups.
  • For KRaft clusters, you must add the following parameter to each Confluent Platform controller configuration file for the listener that is used for inter-broker communication. This parameter enables administration requests to process the group extraction logic. Without this parameter, group-based authorization does not work.
confluent.oidc.idp.groups.claim.name=groups
listener.name.${listenerName}.principal.builder.class=io.confluent.kafka.security.authenticator.OAuthKafkaPrincipalBuilder

Step 2 - Enable SSO using OIDC on Confluent Control Center and MDS

To enable SSO for Confluent Control Center using OIDC, you must configure the following parameters:

  1. On each Confluent Server broker, add the following parameter to the Confluent Platform broker configuration file:

    confluent.metadata.server.sso.mode=oidc

  2. On the Control Center node, add the following parameter to the Confluent Control Center properties file (typically, control-center-dev.properties or control-center-production.properties):

    confluent.controlcenter.auth.sso.mode=oidc

Add group and sub claims

To specify your groups and sub claims, add the following parameters:

  1. On each Confluent Server broker, add the following parameters to the Confluent Platform configuration file.

    # Field for groups and sub in JWT
confluent.oidc.idp.groups.claim.name=groups
confluent.oidc.idp.sub.claim.name=sub
    • The groups claim name identifies the groups to which the principal belongs. The default value is groups. Other ccommon values are organization and team.
    • The sub (subject) claim name identifies the principal that is the subject of the JWT. The default value is sub. Other common values are email and employee_id.

Add a JTI or UTI claim

To use a JTI or UTI claim for security, add the following parameter to each Confluent Platform configuration file to specify the claim name.

confluent.oidc.idp.jti.claim.name=jti

* The ``jti`` (JWT ID) claim name identifies the unique identifier for the JWT.
  The default value is ``jti``, but you can also use ``uti`` (User Token Identifier).

Add the identity provider TLS certificates to the MDS truststore

If you have configured the MDS truststore using confluent.metadata.ssl.truststore.* properties, you must add the identity provider TLS certificates to the truststore.

  1. Add the identity provider certificate to the MDS truststore. For example, if you use the keytool command, run the following command:

    keytool -import -alias <alias> -file <idp-certificate> -keystore <mds-truststore> -storepass <mds-truststore-password> -noprompt
    • <alias>: The alias for the certificate in the truststore.
    • <idp-certificate>: The identity provider TLS certificate.
    • <mds-truststore>: The MDS truststore.
    • <mds-truststore-password>: The password for the MDS truststore.

Step 3 - Customize additional security and usability

Depending on your requirements, you can optionally configure the session management experience on Confluent Platform to customize additional security and usability. Customizations to the following two parameters are optional. For the majority of use cases, the default values should work.

Verify that refresh tokens are enabled

Session renewal also refreshes user’s claims by default as refresh tokens are enabled. For RBAC to work as expected, you should allow refresh tokens for OIDC.

Session renewal is enabled by default because refresh tokens are enabled by default using confluent.oidc.idp.refresh.token.enabled=true. For RBAC to work as expected, the default value of true should not be changed to false.

confluent.oidc.idp.refresh.token.enabled=true

The default value is true and should not be changed to false.

Set the expiration period for JWT session tokens

To change the JWT session token expiration period, add the following configuration parameter and set the duration, in milliseconds. The value here impacts the time to enforce reauthentication. The default value is 900000 (15 minutes). This value should be less than the value for the maximum session timeout.

confluent.oidc.session.token.expiry.ms=900000

Set the maximum session timeout period

To change the maximum session timeout, after which the session cannot be extended, add the following configuration parameter and set the duration, in milliseconds. The default value is 21600000 (6 hours).

confluent.oidc.session.max.timeout.ms=21600000

Step 4 - Restart the Confluent Server brokers

After you have configured SSO for Confluent Control Center using OIDC, you need to restart the Confluent Server brokers and Control Center for the changes to take effect.

Ater restarting, you can sign in to Control Center using the SSO credentials from your identity provider.

Note: You might experience downtime on the Confluent Platform cluster while the cluster upgrades to enable SSO for Confluent Control Center.