<a id="configure-entra-id-for-oauth"></a>

# Configure Microsoft Entra ID as Your Identity Provider for OAuth in Confluent Platform

Set up Microsoft Entra ID as an OAuth 2.0 or OIDC identity provider for Confluent Platform.
Register an application to get a client ID and secret, and then use them
to authenticate with the standard OAuth 2.0 client credentials grant.

#### NOTE
Your Kafka clients might run on Azure compute, such as a VM, Azure
Kubernetes Service, or an Azure Container Instance. If so, and you want
to avoid managing a static client secret, use Azure User-Assigned
Managed Identity (UAMI) instead. UAMI lets Azure supply short-lived
Microsoft Entra ID tokens automatically. For details, see
[Configure Azure User Assigned Managed Identity OAuth for Confluent Platform](../sasl/oauthbearer/uami.md#oauth-uami-share).

## Prerequisites

* Confluent Platform 7.7 or later.
* Required Microsoft Entra ID tenant permissions:
  * To register an application, see [Register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
  * To create and assign app roles for role-based access control (RBAC), see [Add app roles and get them from a token](https://learn.microsoft.com/en-us/entra/identity-platform/howto-add-app-roles-in-apps).

## Step 1: Register an application in Microsoft Entra ID

Register an application to represent your Confluent Platform cluster. This is the
**resource** application. Client applications request tokens scoped to
this resource application to authenticate to Confluent Platform.

1. In the [Microsoft Entra admin center](https://entra.microsoft.com/),
   register a new application, entering a name such as
   `cp-kafka-cluster`. For more information, see
   [Register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
2. On the application’s **Overview** page, record the values of the
   following fields. You need them in [Step 2: Get Microsoft Entra ID endpoint values](#configure-entra-id-values).
   * **Application (client) ID**
   * **Directory (tenant) ID**
3. Enable v2.0 access tokens. Confluent Platform validates tokens issued by the v2.0
   endpoint. Go to the **Manifest** page and set
   `requestedAccessTokenVersion` to `2`:
   ```json
   "requestedAccessTokenVersion": 2,
   ```

   For details, see
   [Configure the application manifest](https://learn.microsoft.com/en-us/entra/identity-platform/reference-app-manifest#configure-the-app-manifest).
4. On the **Expose an API** page, set the **Application ID URI**.
   Accept the default value, for example `<application_client_id>`,
   or enter a custom URI, and record the value. Confluent Platform uses this value as
   the expected audience, the `aud` claim. For instructions, see
   [Configure an application to expose a web API](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-configure-app-expose-web-apis).
5. Create a client secret for the application that authenticates to
   Confluent Platform using the client credentials grant. Go to the **Certificates &
   secrets** page, open the **Client secrets** tab, and click **New
   client secret**. Record the value shown in the **Value** field
   immediately. It isn’t shown again. For instructions, see
   [Add a client secret](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-a-client-secret).
6. (Optional) To authorize with RBAC based on Microsoft Entra ID app
   roles instead of, or in addition to, group membership, add app roles on
   the **App roles** page. Then, go to the **Enterprise applications**
   page, select your application, and assign the roles directly to it on
   the **Users and groups** page.

   #### IMPORTANT
   In the client credentials grant, Microsoft Entra ID doesn’t evaluate
   group-based app role assignments when building the `roles` claim.
   You must assign app roles directly to the service principal. For the
   full group- and role-claim mapping behavior, including a known Microsoft
   Entra ID group overage limitation, see [Use RBAC with OAuth-OIDC in Confluent Platform Clusters](../../authorization/rbac/client-flow-oauth-oidc-and-rbac.md#use-rbac-with-oauth-oidc)
   and [Microsoft Entra ID group claim behavior and overage](configure-oauth-jwt.md#auth-entra-id-group-claims).

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

## Step 2: Get Microsoft Entra ID endpoint values

Using the **Directory (tenant) ID**, **Application (client) ID**, **client
secret**, and **Application ID URI** from step 1, assemble the following
values.

| Value                     | How to derive it                                                                                     |
|---------------------------|------------------------------------------------------------------------------------------------------|
| Issuer (`iss`)            | `https://login.microsoftonline.com/<tenant_id>/v2.0`                                                 |
| JWKS endpoint             | `https://login.microsoftonline.com/<tenant_id>/discovery/v2.0/keys`                                  |
| Token endpoint            | `https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token`                                    |
| Expected audience (`aud`) | The Application ID URI from step 1 (for example,<br/>`<application_client_id>`)                      |
| Scope                     | The Application ID URI followed by `/.default` (for example,<br/>`<application_client_id>/.default`) |

## Step 3: Configure Confluent Server brokers

Configure your Confluent Server broker listener for OAuth authentication, substituting
the values from step 2:

```text
listener.name.external.sasl.enabled.mechanisms=OAUTHBEARER
listener.name.external.sasl.oauthbearer.jwks.endpoint.url=https://login.microsoftonline.com/<tenant_id>/discovery/v2.0/keys
listener.name.external.sasl.oauthbearer.expected.audience=<application_client_id>
listener.name.external.principal.builder.class=io.confluent.kafka.security.authenticator.OAuthKafkaPrincipalBuilder
confluent.oauth.groups.claim.name=groups
```

For the full set of required and optional broker settings, including
interbroker communication and KRaft mode, see [Configure Confluent Server Brokers for OAuth Authentication in Confluent Platform](configure-cs.md#configure-cs-for-oauth).

## Step 4: Configure Kafka clients

Configure your Kafka clients to request a token from Microsoft Entra ID using
the client credentials grant, substituting the **Application (client) ID**
and client secret from step 1 and the token endpoint and scope from step 2:

```properties
sasl.mechanism=OAUTHBEARER
security.protocol=SASL_SSL
sasl.login.callback.handler.class=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginCallbackHandler
sasl.oauthbearer.token.endpoint.url=https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token
sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
   clientId="<application_client_id>" \
   clientSecret="<client_secret>" \
   scope="<application_client_id>/.default";
```

For the complete client configuration reference, including non-Java
clients, see [Configure Kafka clients](configure-cs.md#configure-ak-clients-for-oauth).

## Step 5: Verify your configuration

1. Request a token directly from the token endpoint to confirm the
   application registration is correct, replacing `<tenant_id>`,
   `<application_client_id>`, and `<client_secret>`:
   ```shell
   curl -X POST "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token" \
     -d "grant_type=client_credentials" \
     -d "client_id=<application_client_id>" \
     -d "client_secret=<client_secret>" \
     -d "scope=<application_client_id>/.default"
   ```
2. Decode the returned `access_token` at [jwt.io](https://jwt.io/) and
   confirm that `iss` matches
   `https://login.microsoftonline.com/<tenant_id>/v2.0` and `aud` matches
   the application client ID from step 1.
3. With the client properties from step 4 saved to a file (for example,
   `oauth-client.properties`), test end-to-end connectivity, replacing
   `<host>`. This step assumes [CONFLUENT_HOME](../../../installation/installing_cp/zip-tar.md#configure-confluent-home) is set:
   ```shell
   $CONFLUENT_HOME/bin/kafka-console-producer \
     --bootstrap-server <host>:9095 \
     --topic test-topic \
     --producer.config oauth-client.properties
   ```

## Related content

* [Configure Azure User Assigned Managed Identity OAuth for Confluent Platform](../sasl/oauthbearer/uami.md#oauth-uami-share)
* [Configure Confluent Server Brokers for OAuth Authentication in Confluent Platform](configure-cs.md#configure-cs-for-oauth)
* [Configure Metadata Service (MDS) for OAuth Authentication in Confluent Platform](configure-mds.md#configure-mds-for-oauth)
* [Use RBAC with OAuth-OIDC in Confluent Platform Clusters](../../authorization/rbac/client-flow-oauth-oidc-and-rbac.md#use-rbac-with-oauth-oidc)
* [Microsoft Entra ID group claim behavior and overage](configure-oauth-jwt.md#auth-entra-id-group-claims)
* [Use OAuth/OIDC for Authentication in Confluent Platform](overview.md#oauth-oidc-authentication-overview)