Configure Confluent Control Center SSO with Microsoft Entra ID

Use this walkthrough to configure single sign-on (SSO) for Confluent Control Center and the Confluent CLI with Microsoft Entra ID as your OpenID Connect (OIDC) identity provider.

This walkthrough follows the general procedure in Configure SSO for Confluent Control Center using OIDC on Confluent Platform and gives the Microsoft Entra ID values and portal steps for each part. To set up OAuth for brokers, services, and clients, see Configure Microsoft Entra ID as Your Identity Provider for OAuth in Confluent Platform.

Prerequisites

  • Confluent Platform with role-based access control (RBAC) enabled

  • A Microsoft Entra ID tenant and permission to register applications and create client secrets in it

  • Security groups in Microsoft Entra ID that contain the users who sign in to Control Center

  • Access to the Confluent Server broker configuration files and the Control Center properties file

If you use Ansible Playbooks for Confluent Platform to configure SSO, complete the sections from Register an application in Microsoft Entra ID through Get the Microsoft Entra ID endpoints to get the Microsoft Entra ID values, and then see Deploy the configuration with Ansible. If you use Confluent for Kubernetes (CFK), complete the same sections, and then set the values as described in Configure Authentication for Confluent Platform Components Using Confluent for Kubernetes.

1 - Register an application in Microsoft Entra ID

Register an application that represents Control Center.

Warning

Create a separate application for OIDC. Don’t combine OIDC with Security Assertion Markup Language (SAML) in one application, because the combination can cause issues with SSO.

  1. In the Microsoft Entra admin center, go to App registrations and click New registration.

  2. Enter a name for the application, such as c3-sso.

  3. Under Supported account types, select the option that matches your tenant policy. For most deployments, select Single tenant only.

  4. Under Redirect URI, select Web and enter the Control Center callback URL. If you do not know the Control Center hostname yet, you can add the URL after you deploy Control Center.

    https://<c3_hostname>:<c3_port>/api/metadata/security/1.0/oidc/authorization-code/callback
    
  5. Click Register.

  6. On the Overview page, record the following values. You use them when you get the endpoints and configure the brokers:

    • Application (client) ID

    • Directory (tenant) ID

2 - Create a client secret

  1. On the application page, go to Certificates & secrets and click New client secret.

  2. Enter a description and an expiration period, and then click Add.

  3. Copy the secret Value right away. Microsoft Entra ID doesn’t show it again. Don’t copy the Secret ID, which is a different value and doesn’t work as a client secret.

Client secrets expire, and Microsoft Entra ID limits a secret’s lifetime to 24 months. Set a reminder to rotate the secret before it expires, and update confluent.oidc.idp.client.secret when you do.

3 - Add the groups claim to the ID token

Control Center reads the groups claim from the ID token to apply RBAC to Microsoft Entra ID groups.

  1. On the application page, go to Token configuration and click Add groups claim.

  2. Select the group types to include, such as Security groups.

  3. Under Customize token properties by type, expand ID and select Group ID. Microsoft Entra ID then emits the object ID of each group in the groups claim.

  4. Click Add.

  5. Add each user who signs in to Control Center to at least one of these groups.

If a user belongs to more groups than Microsoft Entra ID can include in a token, or if the groups claim is empty, Control Center receives no groups for that user. For more information about this limit and your options, see Microsoft Entra ID group claim behavior and overage.

4 - Get the Microsoft Entra ID endpoints

You can get the endpoints from the OpenID Connect metadata document for your tenant. Replace <tenant_id> with the Directory (tenant) ID that you recorded when you registered the application.

https://login.microsoftonline.com/<tenant_id>/v2.0/.well-known/openid-configuration

The endpoints follow this pattern:

Metadata field

Value

issuer

https://login.microsoftonline.com/<tenant_id>/v2.0

authorization_endpoint

https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/authorize

token_endpoint

https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token

jwks_uri

https://login.microsoftonline.com/<tenant_id>/discovery/v2.0/keys

device_authorization_endpoint (Confluent CLI sign-in only)

https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/devicecode

5 - Configure Confluent Platform for SSO

  1. On each Confluent Server broker, add or update the following properties in the broker configuration file. Replace the placeholders with the values that you recorded and the endpoints that you collected.

    confluent.metadata.server.sso.mode=oidc
    confluent.oidc.idp.issuer=https://login.microsoftonline.com/<tenant_id>/v2.0
    confluent.oidc.idp.jwks.endpoint.uri=https://login.microsoftonline.com/<tenant_id>/discovery/v2.0/keys
    confluent.oidc.idp.authorize.base.endpoint.uri=https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/authorize
    confluent.oidc.idp.token.base.endpoint.uri=https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token
    confluent.oidc.idp.client.id=<client_id>
    confluent.oidc.idp.client.secret=<client_secret>
    confluent.oidc.idp.groups.claim.name=groups
    confluent.oidc.idp.sub.claim.name=sub
    confluent.oidc.idp.refresh.token.enabled=true
    

    When confluent.oidc.idp.refresh.token.enabled is true, which is the default, Confluent Platform requests the offline_access scope in addition to openid. With refresh tokens, a user’s session can continue after the ID token expires, up to the maximum session timeout.

  2. (Optional) To enable Confluent CLI sign-in, add the device authorization endpoint to the same broker configuration file:

    confluent.oidc.idp.device.authorization.endpoint.uri=https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/devicecode
    
  3. On the Control Center node, add the following property to the Control Center properties file:

    confluent.controlcenter.auth.sso.mode=oidc
    
  4. For KRaft clusters, add the following property to each controller configuration file, using the name of the controller listener from controller.listener.names. Without it, group-based authorization doesn’t work.

    listener.name.<listener_name>.principal.builder.class=io.confluent.kafka.security.authenticator.OAuthKafkaPrincipalBuilder
    

6 - Add the Microsoft root certificates to the Metadata Service (MDS) truststore

If you configured a truststore for MDS with the confluent.metadata.server.ssl.truststore.* properties, add the Microsoft root certificate authority (CA) certificates to it. If you didn’t configure a truststore, MDS uses the default Java truststore, and you can skip this step. Microsoft Entra ID can use more than one root CA. For the current list, see Azure Certificate Authority details in the Microsoft documentation.

For each root CA certificate, run the following command:

keytool -import -alias <alias> -file <idp_certificate> \
-keystore <mds_truststore> -storepass <mds_truststore_password> -noprompt

7 - Restart and sign in

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

  2. Open Control Center in a browser. Control Center redirects you to the Microsoft sign-in page.

  3. Sign in with a Microsoft Entra ID user.

At this point, you can sign in but have no permissions, because no role bindings exist yet.

8 - Grant access with role bindings

Assign roles to the Microsoft Entra ID groups that you added the users to. Because the groups claim holds the group object ID, use the object ID of the group as the principal. You can find the object ID on the group’s Overview page in the Microsoft Entra admin center.

For example, to grant the SystemAdmin role to a group:

confluent iam rbac role-binding create \
--principal Group:<group_object_id> \
--role SystemAdmin \
--kafka-cluster <kafka_cluster_id>

For the full procedure and other roles, see Grant the SystemAdmin role.

Deploy the configuration with Ansible

If you deploy with Ansible Playbooks for Confluent Platform, add the following variables to your inventory file, alongside your existing RBAC configuration, instead of editing the properties files. Use the values that you recorded and the endpoints that you collected:

all:
  vars:
    rbac_enabled: true

    sso_mode: oidc
    sso_groups_claim: groups
    sso_sub_claim: sub
    sso_issuer_url: https://login.microsoftonline.com/<tenant_id>/v2.0
    sso_jwks_uri: https://login.microsoftonline.com/<tenant_id>/discovery/v2.0/keys
    sso_authorize_uri: https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/authorize
    sso_token_uri: https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token
    sso_client_id: <client_id>
    sso_client_password: <client_secret>

    # Required for Confluent CLI sign-in.
    sso_cli: true
    sso_device_authorization_uri: https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/devicecode

    # Optional. Required only if the identity provider uses a custom
    # certificate.
    sso_idp_cert_path: <path_to_idp_certificate>

You don’t need sso_groups_scope, because the groups claim comes from the application’s token configuration.

For the complete list of authentication variables, see Configure Authentication for Confluent Platform with Ansible Playbooks.

Troubleshoot

If the sign-in fails or users see no resources after they sign in, review the following:

  • Microsoft Entra ID reports AADSTS50011 when the redirect URI in the application registration doesn’t match the Control Center callback URL. Check the redirect URI that you entered in Register an application in Microsoft Entra ID.

  • Microsoft Entra ID reports AADSTS7000215 when the client secret is not valid. A common cause is copying the Secret ID instead of the secret Value.

  • If users sign in but see no resources, check that the groups claim is present in the ID token. For more information, see Microsoft Entra ID group claim behavior and overage.

For other issues, see Troubleshoot SSO for Control Center using OIDC on Confluent Platform.