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. This configuration enables users to sign-on with a single credential from an identity provider (IdP) and to authenticate seamlessly to Confluent Control Center and to Confluent Cloud.

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.

Prerequisites

• An OIDC-compliant identity provider (IdP), with optional multi-factor authentication (MFA). SAML is not supported.
• Confluent Platform version 7.5.0 or later. All components should be upgraded.
• role-based access control (RBAC) must be enabled.

Decide between manual or automated configuration

You can configure SSO for Confluent Control Center using OIDC manually by completing the procedures on this page. These procedures provide detailed configurations for the Okta, Keycloak, and Microsoft Entra ID (Azure) IdPs.

You can also automate the configuration of SSO. Confluent recommends using Confluent Ansible and Confluent for Kubernetes (CFK) to automate the configuration of SSO for Confluent Control Center on Confluent Platform. For more information, see Confluent Ansible documentation here: Configure single sign-on authentication for Control Center or the CFK documentation here: Configure single sign-on authentication for Confluent Control Center

1 - Establish trust between the IdP and Confluent Platform

Use the procedure below to ensure that you configure your IdP correctly. Under each step, select the tab that corresponds to your IdP for details.

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

   The following tabs contain provider-specific configuration instructions:

   OktaKeycloakMicrosoft Entra ID

   In the Okta documentation, complete Create OIDC app integrations.

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

3. Enable identity tokens.

   Identity tokens are enabled by default when you create an OIDC application in your IdP.

   OktaKeycloakMicrosoft Entra ID

   Creating the authorization server by default enables identity (ID) tokens. For more information, see ID tokens.

4. Enable refresh tokens.

   OktaKeycloakMicrosoft Entra ID

   Check the Refresh Token option in the Grant type section of the Applications page.

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

   OktaKeycloakMicrosoft Entra ID

   1. Navigate to your authorization server under Security > API.
   2. Go to Claims and configure a claim for groups.
   3. Add a Groups claim for the org authorization server.

6. Assign users to the client application in your IdP.

   If you are using groups to control access to Confluent Control Center, you will assign users to the groups in the group configuration steps below.

7. Get the IdP endpoints.

   You can use the OpenID provider configuration response to get the identity provider endpoints required to fetch, authorize, and verify tokens.

   • Token endpoint URL (token_endpoint)
   • Authorization endpoint URL (authorization_endpoint)
   • JSON Web Key Set (JWKS) URL (jwks_uri)
   • Issuer URL (issuer)

   Use the OIDC metadata discovery URI listed below for your IdP to get the following IdP endpoints and save them for later use:

   OktaKeycloakMicrosoft Entra ID

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

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

8. Get the client credential details

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

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

9. Configure IdP 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 step 7 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>
   

10. Configure groups in your IdP.

    In Confluent Platform you can use group authorization to control user access to any resource, for example, a Confluent Platform cluster or a topic. To support this behavior, you must create groups and assign users to them in your IdP.

11. Add the following confluent.oidc.idp.groups.claim.name parameter to the Confluent Platform broker configuration file on each Confluent Server broker.

    confluent.oidc.idp.groups.claim.name=groups
    

    The confluent.oidc.idp.groups.claim.name is required and must match the value of the groups claim configured in your IdP. The default value is groups, but it should match the claim value on your IdP setup. If the values do not match, problems occur during authorization.

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

    listener.name.${listenerName}.principal.builder.class=io.confluent.kafka.security.authenticator.OAuthKafkaPrincipalBuilder
    

    The io.confluent.kafka.security.authenticator.OAuthKafkaPrincipalBuilder parameter enables administration requests to process the group extraction logic. Without this parameter, group-based authorization does not work.

    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. By using the OAuthKafkaPrincipalBuilder the KafkaPrincipal can include groups.

2 - Enable SSO using OIDC on Confluent Control Center and Metadata Service (MDS)

Use this procedure to enable SSO for Confluent Control Center using OIDC.

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
   

3. Specify the groups and sub claims on each Confluent Server broker 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 common 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.

4. 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).

5. Add the IdP 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.

6. Add the IdP 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
   

   • The alias for the certificate in the truststore (<alias>)
   • The IdP TLS certificate (<idp-certificate>)
   • The MDS truststore (<mds-truststore>)
   • The password for the MDS truststore (<mds-truststore-password>)

3 - Customize 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.

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

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

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

4 - Restart the Confluent Server brokers

After you have configured SSO for Confluent Control Center using OIDC, do the following:

1. Restart the Confluent Server brokers and Control Center for the changes to take effect.

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

2. Sign in to Control Center using the SSO credentials from your IdP.