Use OAuth Identity Pools with Your OAuth/OIDC Identity Provider on Confluent Cloud

You can use an OAuth identity pool to provide granular control over access of your applications to your Confluent Cloud resources. An OAuth identity pool is a group of external application identities that are assigned a certain level of access based on a claims-based policy. The use of the OAuth identity pool is defined by the pool filter expression. Access is controlled using role-based access control (RBAC) or access control lists (ACLs).

To create an OAuth identity pool to map access to your OAuth/OIDC identity provider, click Add identity pool and follow the steps in Add an OAuth identity pool.

To use the Confluent Cloud APIs to create, read, update, list, and delete OAuth identity pools, see Identity Pools (iam/v2).

Add an OAuth identity pool

Required RBAC roles:

Before you can use the OAuth 2.0 identity provider that you created in Add an identity provider using Confluent Cloud Console, you need to configure an OAuth identity pool to be used with that identity provider.

To create an OAuth identity pool to use with your OAuth/OIDC identity provider:

  1. In Confluent Cloud Console, go to the Workload identities tab under Accounts & access at https://confluent.cloud/settings/org/workload_identities.

    Alternatively, you can open the Confluent Cloud Console at https://confluent.cloud, open the sidebar menu, click Accounts & access, and then click Workload identities.

  2. Click Workload identities and then click the OAuth/OIDC identity provider that you want to use to create the OAuth identity pool.

    The identity provider’s details page appears.

  3. Click Add pool.

    The New identity pool page appears.

  4. Under Create your identity pool, enter the following information:

    • Name – Enter the name for your OAuth identity pool.
    • Description – Enter meaningful information for using and managing your OAuth identity pool.

  5. Under Add identity pool owner, grant the ResourceOwner role to the account that owns the OAuth identity pool. This account can manage, edit, and delete this account.

    • Account type: Select the account type that owns the OAuth identity pool.
    • Account: Select the account that owns the OAuth identity pool. This value appears in the audit log records.

    The account that owns the identity pool can manage, edit, and delete the identity pool. Note that if you do not specify an account, only OrganizationAdmin and AccountAdmin roles can manage the account after creation.

  6. Under Add identity claim, enter the name of the claim from which to extract the identity name.

    The default value is claims.sub (subject). For details about the “claims.sub” claim, see JSON Web Token (JWT) [RFC 7519]: Section 4.1.2.

    If required, you can enter an email claim or your own custom claim.

  7. Under Set filters (required), set filters that require specific certificate metadata values.

    To set up filters, follow the steps in Set OAuth identity pool filters.

    If you are not specifying filters, continue below the following section.

Set OAuth identity pool filters

Use OAuth identity pool filters to specify which identities can authenticate using your OAuth identity pool. You must create at least one filter for each OAuth identity pool.

To create an OAuth identity pool filter, use the Common Expression Language (CEL) (summarized in the following table) to enter the required formulas.

Supported Common Expression Language (CEL) filters

The following table summarizes the supported CEL filters.

  • All token fields used in filter definitions must be prefixed with claims..
_ For development purposes, you can temporarily set the filter to true
to allow all identities with a valid token to authenticate.
Use case CEL expression
Equality claims.iss == "google"
Inclusion claims.appid in ["abc", "xyz"]
  !(claims.appid in ["abc", "xyz"])
  'administrators' in claims.groups
  !('administrators' in claims.groups)
Presence check has(claims.iss)
  !has(claims.iss)
Prefix matching claims.principal.startsWith("user")
Suffix matching claims.principal.endsWith("user")

For more complex rules, use the following operators:

Use case Operator precedence CEL expression
Logical NOT 1 !(claims.iss == "google")
Logical AND 2 claims.iss == "google" && claims.principal == "userA"
Logical OR 3 claims.iss == "google" || claims.principal == "userA"

The rules can be grouped into parentheses, like this: Expression && ( Expression || Expression )

  1. Click Next.

    The Add roles section appears.

  2. To control access to resources using your OAuth identity pool, complete the Add Roles section:

  3. Click Next.

  4. Review your OAuth identity pool settings, access delegation summary, and resource access summary, and then click Create identity pool.

You have successfully added an OAuth identity pool to your Confluent Cloud identity provider and can now use your new OAuth identity pool to control access based on the policies specified.

Use auto pool mapping with OAuth identity pools

Note

OAuth Auto Pool Mapping for Kafka Clients (Limited Availability)

OAuth auto pool mapping is a feature in Limited Availability as a fully-supported offering for customers participating in the Limited Availability program. To participate, reach out to your account team or sign up for OAuth Auto Pool Mapping.

You can simplify Kafka client OAuth configurations with automatic mapping of OAuth identity pools by omitting the identity pool ID extension (extension_identityPoolId) from the client configuration.

  • This results in Kafka mapping the external OAuth token to all OAuth identity pools in the OAuth identity provider where the pool filter evaluates to true for the given token claims.
  • When more than one identity pool is mapped, the Kafka client is granted the union of permissions from all mapped identity pools.

How it works

Here is a high-level overview of how auto pool mapping works:

  1. Create identity pools with appropriate claim filters that match your client application tokens.
  2. Configure Kafka clients without specifying the extension_identityPoolId parameter.
  3. When a client connects, Confluent Cloud performs the following steps:
    • Validates the JWT token.
    • Identifies all identity pools with filters that match the token claims.
    • Combines permissions from all matching pools.
    • Allows access based on the union of permissions.

Configure Kafka clients to use auto pool mapping

Here are examples of how to configure Kafka clients to use auto pool mapping for a Java client.

Java client

sasl.jaas.config= \
  org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
    clientId='<client ID>' \
    scope='<Requested Scope>' \
    clientSecret='<Client Secret>' \
    extension_logicalCluster='<Cluster ID>';
    # extension_identityPoolId is omitted

Replace the placeholder values with your actual values. For clientId and clientSecret, use the values from the OAuth identity provider. For extension_logicalCluster, use the ID of the Kafka cluster that you want to connect to.

Advanced use case: Specifying multiple identity pools

As an alternative, Kafka clients can specify multiple identity pool IDs to map your identity provider OAuth token to, for the benefit of optimizing latency at connection time. Multiple identity pool IDs can be specified using a comma-separated list in the extension_identityPoolId parameter.

Here is an example of how to configure a Kafka client to use auto pool mapping with multiple identity pool IDs.

bootstrap.servers=<bootstrap URL>
security.protocol=SASL_SSL
sasl.oauthbearer.token.endpoint.url=https://myidp.example.com/oauth2/default/v1/token
sasl.login.callback.handler.class=org.apache.kafka.common.security.oauthbearer.secured.OAuthBearerLoginCallbackHandler
sasl.mechanism=OAUTHBEARER
sasl.jaas.config= \
  org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
    clientId='<client ID>' \
    scope='<Requested Scope>' \
    clientSecret='<Client Secret>' \
    extension_logicalCluster='<Cluster ID>' \
    extension_identityPoolId='<Identity Pool ID 1>,<Identity Pool ID 2>';

Use auto pool mapping with identity claims

When using identity pool auto-mapping or listing multiple identity pools, the default identity claim used in audit logs is the sub claim.

You can change the default identity claim used in audit logs by setting the identity_claim parameter in the following HTTP PATCH request:

PATCH https://api.confluent.cloud/iam/v2/identity-providers/{id}

Here is an example of the HTTP PATCH request using a curl command:

curl --request PATCH \
  --url 'https://api.confluent.cloud/iam/v2/identity-providers/{id}' \
  --header 'Authorization: Basic or Bearer Auth' \
  --header 'content-type: application/json' \
  --data '{"identity_claim":"claims.sub"}'

Compatibility notes

  • For backward compatibility, clients can still specify an identity pool ID using extension_identityPoolId.
  • When an identity pool ID is specified, only that identity pool’s permissions are used.

Limitations

Auto pool mapping is available only for Kafka clients, specifically:

  • Java clients that support OAuth
  • Omitting the identity pool ID client parameter is supported for all versions of Kafka clients that support OAuth.
  • When specifying multiple identity pool IDs (as shown in the advanced use case), librdkafka clients version 2.8 or later are required.
  • Authentication latency might increase when a client token matches many identity pools.