<a id="configure-sso-entra-id"></a>

# 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](configure-sso-using-oidc.md#configure-sso-using-oidc) 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](../oauth-oidc/configure-entra-id.md#configure-entra-id-for-oauth).

## 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](#configure-sso-entra-id-register) through
[Get the Microsoft Entra ID endpoints](#configure-sso-entra-id-endpoints)
to get the Microsoft Entra ID values, and then see
[Deploy the configuration with Ansible](#configure-sso-entra-id-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](https://docs.confluent.io/operator/current/co-authenticate-cp.html#co-authenticate-c3-sso).

<a id="configure-sso-entra-id-register"></a>

## 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](https://entra.microsoft.com/), 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.
   ```text
   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**

<a id="configure-sso-entra-id-secret"></a>

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

<a id="configure-sso-entra-id-groups"></a>

## 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](../oauth-oidc/configure-oauth-jwt.md#auth-entra-id-group-claims).

<a id="configure-sso-entra-id-endpoints"></a>

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

```text
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` |

<a id="configure-sso-entra-id-configure"></a>

## 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.
   ```properties
   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:
   ```properties
   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:
   ```properties
   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.
   ```properties
   listener.name.<listener_name>.principal.builder.class=io.confluent.kafka.security.authenticator.OAuthKafkaPrincipalBuilder
   ```

<a id="configure-sso-entra-id-truststore"></a>

## 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](https://learn.microsoft.com/en-us/azure/security/fundamentals/azure-CA-details?tabs=root-and-subordinate-cas-list#what-changed)
in the Microsoft documentation.

For each root CA certificate, run the following command:

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

<a id="configure-sso-entra-id-restart"></a>

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

<a id="configure-sso-entra-id-role-bindings"></a>

## 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:

```bash
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](../../authorization/rbac/rbac-cli-quickstart.md#rbac-rolebinding-sysadmin-role).

<a id="configure-sso-entra-id-ansible"></a>

## 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:

```yaml
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](https://docs.confluent.io/ansible/current/ansible-authenticate.html).

## 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](#configure-sso-entra-id-register).
* 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](../oauth-oidc/configure-oauth-jwt.md#auth-entra-id-group-claims).

For other issues, see [Troubleshoot SSO for Control Center using OIDC on Confluent Platform](troubleshoot.md#troubleshoot-sso-for-c3).

## Related content

* [Configure SSO for Confluent Control Center using OIDC on Confluent Platform](configure-sso-using-oidc.md#configure-sso-using-oidc)
* [Configure OIDC SSO for the Confluent CLI on Confluent Platform](configure-sso-for-cli.md#configure-sso-for-cli-using-oidc)
* [Configure Microsoft Entra ID as Your Identity Provider for OAuth in Confluent Platform](../oauth-oidc/configure-entra-id.md#configure-entra-id-for-oauth)
* [Microsoft Entra ID group claim behavior and overage](../oauth-oidc/configure-oauth-jwt.md#auth-entra-id-group-claims)
* [Troubleshoot SSO for Control Center using OIDC on Confluent Platform](troubleshoot.md#troubleshoot-sso-for-c3)
