> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Choose an authentication method

Authentication identifies a Pulsar client and returns a role. Authorization determines what that role can do. Configure both the authentication provider and the permissions for the returned role.

## Choose a provider

| Client credentials | Server configuration | Guide |
| - | - | - |
| JWT signed by a key you manage | JWT authentication | [JWT authentication](/private-cloud/v2/configure-private-cloud/security/authentication/private-cloud-jwt-auth) |
| API key issued by the API key service | API key authentication and authorization with revocation checks | [API key authentication](/private-cloud/v2/configure-private-cloud/security/authentication/private-cloud-api-key-auth) |
| Kubernetes ServiceAccount token or another OIDC JWT | API key provider extended with custom issuer configuration | [OIDC authentication](/private-cloud/v2/configure-private-cloud/security/authentication/private-cloud-oidc-auth) |
| Client certificate and private key | TLS certificate authentication | [mTLS authentication](/private-cloud/v2/configure-private-cloud/security/authentication/private-cloud-mtls-auth) |

For Kubernetes workloads, a projected ServiceAccount token provides a short-lived credential that Kubernetes refreshes. Clients outside Kubernetes need credentials issued through their identity provider or API key service, or a client certificate. Configuring an issuer on a broker does not itself create credentials for clients.

## Separate server and internal client authentication

The Operator exposes three configuration surfaces:

| Configuration | Purpose |
| - | - |
| `spec.config.authentication` | Configures the providers that authenticate incoming connections. |
| `spec.config.clientAuth` | Configures credentials used by the component's own Pulsar client, such as a broker's system-topic client or a proxy's connection to brokers. |
| `spec.config.custom` | Sets Pulsar properties directly, including providers that do not have a typed configuration field. |

Starting with StreamNative Operator **0.20.16**, `clientAuth` is rendered even when you omit `authentication`. Upgrade the Operator and its CRDs before using that combination. See [Upgrade StreamNative Operator](/private-cloud/v2/operate-private-cloud/upgrade/upgrade-sn-operator).

Custom authentication properties override the corresponding properties generated from typed authentication fields. For example, `PULSAR_PREFIX_authenticationProviders` in `custom` determines the effective authentication providers. Keep overrides consistent with the remaining authentication and authorization settings. This precedence does not make generated service URLs suitable for a TLS client; check the actual TLS endpoint separately.

Supported properties in `spec.config.custom` can use names without a prefix, as shown in the [JWT example](/private-cloud/v2/configure-private-cloud/security/authentication/private-cloud-jwt-auth#enable-jwt-authentication-for-the-pulsar-cluster). Use the `PULSAR_PREFIX_` form when a custom value must override a property generated from typed fields. Inspect the generated ConfigMap and effective configuration after changing providers.

## Grant permissions to the authenticated role

For the API key service procedure, the Pulsar role is the token `jti`. For a custom OIDC issuer, configure its role claim separately; Kubernetes ServiceAccount tokens use `sub`. With certificate authentication, the role is the client certificate's common name. Grant permissions to that exact role, and reserve `superUserRoles` for administrative identities. See [Grant permissions](/private-cloud/v2/configure-private-cloud/security/access-control/grant-permissions).

When you trust multiple OIDC issuers, check the [issuer and role boundary](/private-cloud/v2/configure-private-cloud/security/authentication/private-cloud-oidc-auth#trust-multiple-issuers). Audience validation alone does not give identical role names separate permissions for each issuer.

## Validate the configuration

Verify an authorized connection, rejected credentials, message production and consumption, and any broker operation that uses an internal client, such as topic-policy updates. A broker Pod can be Ready while an internal client is misconfigured.

The detector has its own authentication settings and runtime. Configure and validate it separately using [Pulsar Detector](/private-cloud/v2/operate-private-cloud/observability/private-cloud-detector).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.