Streaming

Configure Authentication for Redpanda in Kubernetes

Authentication verifies the identity of users and applications that connect to Redpanda clusters.

Different Redpanda APIs support different authentication methods. You can configure multiple listeners for each API, and you can configure each listener with an authentication method. Redpanda APIs support these authentication methods:

API Supported Authentication Methods

Kafka API

  • SASL

    • SASL/SCRAM

    • SASL/PLAIN

    • SASL/OAUTHBEARER (OIDC)

Admin API

  • Basic authentication

  • OIDC

HTTP Proxy (PandaProxy)

  • Basic authentication

  • OIDC

Schema Registry

  • Basic authentication

  • OIDC

Users, principals, and superusers

When you configure authentication and authorization in Redpanda, it’s important to understand the distinction between users, principals, and superusers:

  • A user refers to a stored credential within Redpanda, typically a username and password stored in the internal SASL credential store. These are created using commands such as rpk security user create.

  • A principal is the authenticated identity string associated with a client session. It’s what Redpanda uses for access control, ACLs, and superuser assignment.

  • A superuser is a privileged principal who has unrestricted access to all operations in a Redpanda cluster.

Superusers can:

  • Grant or revoke permissions to other users through ACLs.

  • Access all Admin API endpoints.

  • Create, modify, or delete topics and consumer groups.

  • View and manage the cluster’s internal state.

Depending on how a client authenticates, the principal might be:

  • The SCRAM username

  • A claim from a JWT

  • A certificate DN

  • A Kerberos identity

You assign ACLs and superuser roles to principals, not users. Even if a user exists, they have no access unless its associated principal is granted permissions.

For example, with OIDC:

Configure superusers and ACL rules using the exact value from your OIDC token’s sub (subject) claim. For example, if your token’s sub claim is example@company.com, use that exact value in your configuration.

OIDC principals use the value extracted from the token’s claims according to your configured principal mapping. SASL users require the User: prefix, but OIDC principals do not use any prefix.

Prerequisites

You must have the following:

  • Kubernetes cluster. Ensure you have a running Kubernetes cluster, either locally, such as with minikube or kind, or remotely.

  • Kubectl. Ensure you have the kubectl command-line tool installed and configured to communicate with your cluster.

Enable authentication

When you enable authentication in the Redpanda Helm chart:

  • SASL authentication is enabled for the Kafka API listeners

  • Basic authentication is enabled for the HTTP Proxy and Schema Registry listeners

  • Authorization is enabled

When enabling authentication, you must create at least one superuser. Without a superuser, you can create other users, but you can’t grant them permissions to the cluster.

Do not enable authorization without a superuser. Without a superuser, you may be locked out of the cluster and lose the ability to manage cluster settings or users.

Create superusers

To create one or more superusers, you must define a username and password. You can also set the SASL/SCRAM authentication mechanism for each superuser. Redpanda supports the following SASL/SCRAM authentication mechanisms for the Kafka API:

  • SCRAM-SHA-256

  • SCRAM-SHA-512

You can use the following to store superuser credentials:

For default values and documentation for configuration options, see the values.yaml file.

Use a Secret resource

To use a Secret resource to store superuser credentials:

  1. Create a file in which to store the credentials.

    echo '<superuser-name>:<superuser-password>:<superuser-authentication-mechanism>' >> superusers.txt

    Replace the following placeholders with your own values for the superuser:

    • <superuser-name>: The name of the superuser.

    • <superuser-password>: The superuser’s password.

    • <superuser-authentication-mechanism>: The authentication mechanism. Valid values are SCRAM-SHA-256 or SCRAM-SHA-512.

      Or, leave this placeholder empty to set it to the default authentication mechanism. The default is SCRAM-SHA-512. This default is applied to all superusers that don’t include an explicit authentication mechanism.

  2. Use the file to create a Secret resource in the same namespace as your Redpanda cluster.

    kubectl --namespace <namespace> create secret generic redpanda-superusers --from-file=superusers.txt

  3. Enable SASL and create the superuser using your Secret:

    • Operator

    • Helm

    redpanda-cluster.yaml
    apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    auth:
      sasl:
        enabled: true
        secretRef: "redpanda-superusers"
        users: []
    kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

    • --values

    • --set

    enable-sasl.yaml
    auth:
  sasl:
    enabled: true
    secretRef: "redpanda-superusers"
    users: []
    helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values enable-sasl.yaml --reuse-values
    helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set auth.sasl.enabled=true \
  --set auth.sasl.secretRef=redpanda-superusers \
  --set "auth.sasl.users=null"

    • auth.sasl.enabled: Enable authentication.

    • auth.sasl.secretRef: The name of the Secret that contains the superuser credentials. The Secret must be in the same namespace as the Redpanda cluster.

    • auth.sasl.users: Make sure that this list is empty. Otherwise, the chart will try to create a new Secret with the same name as the one set in auth.sasl.secretRef and fail because it already exists.

Use a YAML list

You can use a YAML list item to store superuser credentials in configuration settings.

Replace the following placeholders with your own values for the superuser:

  • <superuser-name>: The name of the superuser.

  • <superuser-password>: The superuser’s password.

  • <superuser-authentication-mechanism>: The authentication mechanism. Valid values are SCRAM-SHA-256 or SCRAM-SHA-512.

    If you leave this placeholder empty, the Helm chart uses the default authentication mechanism. The default is SCRAM-SHA-512. This default is applied to all superusers that don’t include an explicit authentication mechanism.

  • Operator

  • Helm

redpanda-cluster.yaml
apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    auth:
      sasl:
        enabled: true
        secretRef: redpanda-superusers
        users:
          - name: <superuser-name>
            password: <superuser-password>
            mechanism: <superuser-authentication-mechanism>
kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

  • --values

  • --set

enable-sasl.yaml
auth:
  sasl:
    enabled: true
    secretRef: redpanda-superusers
    users:
      - name: <superuser-name>
        password: <superuser-password>
        mechanism: <superuser-authentication-mechanism>
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values sasl-enable.yaml --reuse-values
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set auth.sasl.enabled=true \
  --set auth.sasl.secretRef=redpanda-superusers \
  --set "auth.sasl.users[0].name=<superuser-name>" \
  --set "auth.sasl.users[0].password=<superuser-password>" \
  --set "auth.sasl.users[0].mechanism=<superuser-authentication-mechanism>"

  • auth.sasl.enabled: Enable authentication.

  • auth.sasl.secretRef: The name of the Secret that the Redpanda Helm chart will create and use to store the superuser credentials listed in auth.sasl.users. This Secret must not already exist in the cluster.

  • auth.sasl.users: A list of superusers.

As a security best practice:

  • Don’t use the superuser to interact with the cluster.

  • Don’t delete the superuser (in case you need to grant permissions to new users later).

    When you create the superuser, you specify a password, which adds a level of security. If you delete the user, someone else could re-create the user with a different password.

Edit superusers

You can add new superusers to the cluster or update existing users. For example, if you wanted to rotate credentials for superusers, you could update the username or password of an existing superuser.

You cannot delete superusers by changing the Helm values or updating the Secret.

  • If you created superusers using a Secret, you can edit the superusers.txt file and reapply the Secret resource:

    kubectl create secret generic redpanda-superusers \
  --namespace <namespace> \
  --from-file=superusers.txt \
  --save-config \
  --dry-run=client -o yaml | kubectl apply -f -

    The config-watcher sidecar in the Pod watches the superusers Secret for changes. When changes are observed, it creates and updates users accordingly.

  • If you created superusers using a YAML list, you can update the list:

    • Operator

    • Helm

    redpanda-cluster.yaml
    apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    auth:
      sasl:
        enabled: true
        secretRef: redpanda-superusers
        users:
          - name: <superuser-name>
            password: <new-superuser-password>
            mechanism: <superuser-authentication-mechanism>
    kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

    • --values

    • --set

    enable-sasl.yaml
    auth:
  sasl:
    enabled: true
    secretRef: redpanda-superusers
    users:
      - name: <superuser-name>
        password: <new-superuser-password>
        mechanism: <superuser-authentication-mechanism>
    helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values sasl-enable.yaml --reuse-values
    helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set auth.sasl.enabled=true \
  --set auth.sasl.secretRef=redpanda-superusers \
  --set "auth.sasl.users[0].name=<superuser-name>" \
  --set "auth.sasl.users[0].password=<new-superuser-password>" \
  --set "auth.sasl.users[0].mechanism=<superuser-authentication-mechanism>"

Authentication for the Kafka API

Redpanda supports the following authentication methods for the Kafka API:

  • SASL (Simple Authentication and Security Layer)

SASL

SASL provides a flexible and adaptable framework for implementing various authentication mechanisms. Redpanda supports these SASL mechanisms:

Redpanda provides an option to configure different SASL authentication mechanisms for specific listeners. For example, you could specify SCRAM for internal traffic and OAUTHBEARER for external clients. For details, see sasl_mechanisms_overrides.

Enable SASL

The Redpanda Helm chart sets the authentication_method broker property to sasl for all Kafka listeners by default when you enable authentication.

Enable SASL with TLS encryption

SASL provides authentication, but not encryption. To provide encryption, you can enable TLS in addition to SASL. See TLS for Redpanda in Kubernetes.

TLS is enabled in the Helm chart by default.

SASL/SCRAM

SASL/SCRAM does not require sending passwords over the network, even in an encrypted form. It uses a challenge-response mechanism, ensuring that the password is not directly accessible to the server. It works with hashed passwords, providing additional security against dictionary attacks.

Create SCRAM users

When you have SASL authentication enabled for your Redpanda cluster, you can create SCRAM users. Redpanda supports the following SASL/SCRAM authentication mechanisms for the Kafka API:

  • SCRAM-SHA-256

  • SCRAM-SHA-512

By default, SCRAM users don’t have any permissions in the cluster. Only superusers can grant permissions to new users through ACLs.

  1. To create the SCRAM user <my-user> with a password <change-this-password>, run rpk security user create:

    rpk security user create <my-user> \
  -p '<change-this-password>' \
  --mechanism SCRAM-SHA-256
    Enclose passwords in single quotes to avoid conflicts with special characters. Enclosing characters in single quotes preserves the literal value of each character.

  2. Use the rpk security acl create command to grant create and describe permissions to myuser in the cluster:

    rpk security acl create --allow-principal User:myuser \
  --operation create,describe \
  --cluster \
  -X user=<superuser-name> \
  -X pass='<superuser-password>' \
  -X sasl.mechanism=<superuser-authentication-mechanism>

  3. Grant the new user describe privileges for a topic called myfirsttopic:

    rpk security acl create --allow-principal User:myuser \
  --operation describe \
  --topic myfirsttopic \
  -X user=<superuser-name> \
  -X pass='<superuser-password>' \
  -X sasl.mechanism=<superuser-authentication-mechanism>
    You must grant privileges for specific topics. Even if a user has describe privileges for a cluster, it does not mean that the user is granted describe privileges for topics.

See also: User create.

Connect to Redpanda

This section provides examples of connecting to Redpanda as a SCRAM user when SASL/SCRAM authentication is enabled.

Create a topic as the myuser user by running rpk topic create:

rpk topic create myfirsttopic \
  -X user=myuser \
  -X pass='changethispassword' \
  -X sasl.mechanism=SCRAM-SHA-256

To describe the topic, run rpk topic describe:

rpk topic describe myfirsttopic \
  -X user=myuser \
  -X pass='changethispassword' \
  -X sasl.mechanism=SCRAM-SHA-256

For more details on connecting to Redpanda, see Connect to Redpanda in Kubernetes.

Configure Schema Registry and HTTP Proxy to connect to Redpanda with SASL

Schema Registry and HTTP Proxy connect to Redpanda over the Kafka API.

Breaking change in Redpanda 25.2: Ephemeral credentials for HTTP Proxy are removed. If your HTTP Proxy API listeners use authentication_method: none, you must configure explicit SASL credentials (scram_username, scram_password, and sasl_mechanism) for HTTP Proxy to authenticate with the Kafka API.

This allows any HTTP API user to access Kafka using shared credentials. Redpanda Data recommends enabling HTTP Proxy authentication instead.

For details about this breaking change, see What’s new.

Schema Registry and HTTP Proxy support only the SASL/SCRAM mechanism.

SASL/PLAIN

You can configure Kafka clients to authenticate using either SASL/SCRAM or SASL/PLAIN with a single account using the same username and password. Unlike SASL/SCRAM, which uses a challenge response with hashed credentials, SASL/PLAIN transmits plaintext passwords. While not required, it is recommended that you use TLS for external encryption when using SASL/PLAIN authentication.

If you have existing PLAIN Kafka clients and applications, you can migrate to Redpanda without updating your application by creating local Redpanda SCRAM accounts and enabling PLAIN as an authentication mechanism.

Clusters configured with only a SASL/PLAIN mechanism are not supported.
Enable SASL/PLAIN

You must enable SASL/PLAIN explicitly by appending PLAIN to the list of SASL mechanisms:

  • Helm + Operator

  • Helm

redpanda-cluster.yaml
apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    auth:
      sasl:
        enabled: true
        secretRef: redpanda-superusers
    config:
      cluster:
        sasl_mechanisms:
          - "SCRAM"
          - "PLAIN"
kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

  • --values

  • --set

enable-sasl.yaml
auth:
  sasl:
    enabled: true
    secretRef: redpanda-superusers
config:
  cluster:
    sasl_mechanisms:
      - "SCRAM"
      - "PLAIN"
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values sasl-enable.yaml --reuse-values
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set auth.sasl.enabled=true \
  --set auth.sasl.secretRef=redpanda-superusers \
  --set "config.cluster.sasl_mechanisms[0]=SCRAM" \
  --set "config.cluster.sasl_mechanisms[1]=PLAIN" \

OAUTHBEARER (OIDC)

OpenID Connect (OIDC) authentication requires an enterprise license. To upgrade, contact Redpanda sales.

When you enable OIDC, Redpanda and Redpanda Console can delegate the authentication process to an external identity provider (IdP) such as Okta, Microsoft Entra ID, or on-premise Active Directory Federation Service (AD FS).

With OIDC enabled, Redpanda does not need to manage user credentials directly, but can instead rely on the trusted authentication capabilities of established IdPs.

Redpanda’s implementation of OIDC provides SASL/OAUTHBEARER support for the Kafka API, and supports standard OIDC authentication across all other HTTP APIs, including Schema Registry, HTTP Proxy, and the Admin API.

With OIDC enabled, you can also use group-based access control (GBAC) to assign Redpanda permissions to OIDC groups instead of individual users. To use GBAC, configure your IdP to include group claims in the access token (for example, a groups claim). See your IdP’s documentation for how to add group claims to tokens.
OIDC limitations

  • Redpanda requires JWT-formatted access tokens (not ID tokens) for Kafka API authentication using SASL/OAUTHBEARER. Access tokens issued by some IdPs, such as Google, are opaque and not supported.

  • The rpk CLI does not support OIDC login.

  • Redpanda requires OIDC principals to be set as superusers to access the Admin API. Granular authorization is not supported.

  • The rpk CLI does not support the SASL/OAUTHBEARER mechanism for deploying data transforms. Use SASL/SCRAM instead.

OIDC credentials flow and access token validation

Before configuring OIDC, you should understand the credentials flow, and in particular, the validation claims included in the access token, as you will need to provide them in the OIDC configuration.

Redpanda’s implementation of OIDC adheres to the client credentials flow defined in OAuth 2.0 RFC 6749, section 4.4 in which a client obtains an access token from the authorization server, and provides this access token to Redpanda, either using SASL/OAUTHBEARER for the Kafka API, or an HTTP Authorization (Bearer) header.

The access token is a bearer token. A bearer token is used for authentication and authorization in web applications and APIs, and holds user credentials, usually in the form of random strings of characters. Bearer tokens are generated based on protocols and specifications such as JWT (JSON Web Token), which has a header, payload, and signature. The signature must be verified according to the JWK. Claims inside the token and the token signature must both be validated. After validation, a configurable claim from the token payload is extracted as the principal and attached to the connection, as with any other authentication method.

Following is an example JWT header:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "tMQzailSAdaW4nojXxES9"
}

Following is an example JWT payload:

{
  "iss": "https://dev-ltxchcls4igzho78.us.auth0.com/",
  "sub": "3JJeI4tmMC6v8mCVCSDnAGVf2vrnJ0BT@clients",
  "aud": "localhost",
  "iat": 1694430088,
  "exp": 1694516488,
  "azp": "3JJeI4tmMC6v8mCVCSDnAGVf2vrnJ0BT",
  "scope": "email2",
  "gty": "client-credentials"
}

Following are additional validation claims (JWT properties) that are included in the access token:

  • alg: The signature algorithm. The extension point in the JWT header is the signature algorithm used to sign the token, and cannot contain the value none.

  • aud: Audience. Must match the configuration specified in oidc_token_audience. Cannot contain the value none.

  • kid: Key identifier. Must match any of the public JWK listed in the jwks_uri endpoint.

  • exp: Expiration. The timestamp listed is greater than current time. Must validate within acceptable bounds of the value specified in oidc_clock_skew_tolerance. A clock skew tolerance period may be configured by an Admin to account for clock drift between Redpanda and the OIDC Identity Provider (IdP).

  • iss: Issuer. Must exactly match the issuer property of the JSON returned from the URL specified in oidc_discovery_url.

  • scope: Scope. Must include the value openid.

  • sub: Subject. This default claim identifies the principal subject. While sub is the default mapping ($.sub) in Redpanda, any claim within the JWT can be mapped to a Redpanda principal.

Enable OIDC

  1. Register a client application with your IdP.

    A client application, in this context, refers to any application or service that will authenticate against the Redpanda cluster using OIDC. This registration process involves creating a new entry in the IdP’s management console for the application, sometimes called a client. During this process, you’ll specify details about your application, such as the type of application, the callback URLs, and any other required information as per your IdP’s requirements. In an enterprise environment, OIDC integration typically requires coordination with your organization’s security team.

  2. Enable SASL authentication if it’s not already enabled.

  3. Configure ACLs for your users so they can access Redpanda resources.

  4. Configure OIDC:

    • Operator

    • Helm

    redpanda-cluster.yaml
    apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    auth:
      sasl:
        enabled: true
        secretRef: redpanda-superusers
    config:
      cluster:
        sasl_mechanisms:
          - "SCRAM"
          - "OAUTHBEARER"
        oidc_discovery_url: "<discovery-url>"
        oidc_token_audience: "<token-audience>"
        oidc_principal_mapping: "<json-path>"
        oidc_clock_skew_tolerance: <tolerance>
        oidc_token_expire_disconnect: <true-or-false>
        oidc_keys_refresh_interval: <interval>
    kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

    • --values

    • --set

    enable-sasl.yaml
    auth:
  sasl:
    enabled: true
    secretRef: redpanda-superusers
config:
  cluster:
    sasl_mechanisms:
      - "SCRAM"
      - "OAUTHBEARER"
    oidc_discovery_url: "<discovery-url>"
    oidc_token_audience: "<token-audience>"
    oidc_principal_mapping: "<json-path>"
    oidc_clock_skew_tolerance: <tolerance>
    oidc_token_expire_disconnect: <true-or-false>
    oidc_keys_refresh_interval: <interval>
    helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values sasl-enable.yaml --reuse-values
    helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set auth.sasl.enabled=true \
  --set auth.sasl.secretRef=redpanda-superusers \
  --set "config.cluster.sasl_mechanisms[0]=SCRAM" \
  --set "config.cluster.sasl_mechanisms[1]=OAUTHBEARER" \
  --set config.cluster.oidc_discovery_url="<discovery-url>" \
  --set config.cluster.oidc_token_audience="<token-audience>" \
  --set config.cluster.oidc_principal_mapping="<json-path>" \
  --set config.cluster.oidc_clock_skew_tolerance=<tolerance> \
  --set config.cluster.oidc_token_expire_disconnect=<true-or-false> \
  --set config.cluster.oidc_keys_refresh_interval=<interval>

    • config.cluster.sasl_mechanisms: Enable SCRAM and OIDC SASL mechanisms.

    • config.cluster.oidc_discovery_url: The discovery URL of your identity provider (IdP). The default is https://auth.prd.cloud.redpanda.com/.well-known/openid-configuration.

    • config.cluster.oidc_token_audience: The intended audience of the token. The default is redpanda.

    • config.cluster.oidc_principal_mapping: The principal mapping, which is a JSON path that extracts a principal from any claim in the access token payload. The default is $.sub.

    • config.cluster.oidc_clock_skew_tolerance: The amount of time (in seconds) to allow for when validating the expiration claim in the token.

    • config.cluster.oidc_token_expire_disconnect: Whether to enable OIDC to disconnect clients when their token expires.

    • config.cluster.oidc_keys_refresh_interval: The amount of time keys from the jwks_uri are cached.

Connect to Redpanda with OIDC using rpk

Starting with rpk v26.1.7 (also available in v25.3.x and v25.2.x patches), rpk supports the OAUTHBEARER SASL mechanism for Kafka API authentication. After you enable OIDC on a Kafka listener, you can authenticate rpk to Kafka with an OIDC access token issued by your IdP instead of a SASL/SCRAM username and password.

Confirm your rpk version with rpk version. Earlier versions reject -X sasl.mechanism=OAUTHBEARER as an unknown mechanism.

Before you connect, make sure that:

Pass the token using -X options. Set sasl.mechanism=OAUTHBEARER and supply the token through pass, either as a raw value or in token:<TOKEN> form:

export OIDC_TOKEN="<access-token>"

rpk topic list \
  -X brokers=<broker-host>:<oidc-listener-port> \
  -X tls.enabled=true \
  -X tls.ca=<path-to-ca-cert> \
  -X sasl.mechanism=OAUTHBEARER \
  -X pass="token:$OIDC_TOKEN"

The same -X sasl.mechanism and -X pass options work for any rpk command that talks to the Kafka API (for example, rpk topic create, rpk topic produce, rpk topic consume, rpk group list, rpk cluster info, and rpk security acl list).

To avoid repeating connection flags, store them in an rpk profile:

rpk profile create oidc \
  --set kafka_api.brokers=<broker-host>:<oidc-listener-port> \
  --set kafka_api.tls.ca_file=<path-to-ca-cert> \
  --set kafka_api.sasl.mechanism=OAUTHBEARER \
  --set kafka_api.sasl.password="token:$OIDC_TOKEN"

rpk topic list

If rpk returns OAUTHBEARER requires a token, the password is empty or contains only the token: prefix with no value.

If the broker rejects the token, verify that:

  • The aud claim matches oidc_token_audience

  • The iss claim matches the issuer at oidc_discovery_url

  • exp is in the future within oidc_clock_skew_tolerance

  • The signature is valid against the JWK set published at the discovery URL

See OIDC credentials flow and access token validation for the full list of validated claims.

Authentication for the HTTP APIs

Redpanda provides the following HTTP APIs that support authentication:

  • Admin API: Management and monitoring of the Redpanda cluster

  • Schema Registry API: Management of schemas and schema evolution

  • HTTP Proxy API: RESTful interface for Kafka clients

Permission models

Each of the HTTP APIs implements its own permission model with different levels of access control. This section lists what permissions are available to different user types, and how to enable authentication.

Admin API permissions

The Admin API primarily requires superuser privileges, with a few exceptions for read-only status endpoints.

For a complete list of all Admin API endpoints, see the Admin API reference.

Schema Registry API permissions

The Schema Registry implements a granular permission model.

Most read operations require only user-level authentication, while write operations that affect the global state or mode typically require superuser privileges.

HTTP Proxy permissions

The HTTP Proxy API impersonates the authenticated user when making Kafka API calls:

Regular users are subject to the same ACL restrictions as they would be when using the Kafka API directly.

Enable authentication

Redpanda supports authentication for the HTTP APIs using either basic authentication or OIDC (OpenID Connect).

Prerequisites

Before enabling authentication for the HTTP APIs, you must enable SASL authentication for the Kafka API. This creates the credential store that HTTP authentication will use.

Basic authentication

Redpanda Data recommends that you use TLS when enabling HTTP Basic Auth.

Basic authentication provides a method for securing HTTP endpoints. With basic authentication enabled, HTTP user agents, such as web browsers, must provide a username and password when making a request.

To add users to the Redpanda credential store that HTTP basic authentication uses, create users with rpk security user create.

The HTTP Proxy API and the Schema Registry API use the same credential store as the Kafka API, so you can use the same credentials for all three APIs. The Admin API uses the same credential store as the Kafka API, but it requires superuser credentials to access it.

When you enable authentication in the Redpanda Helm chart, the Schema Registry API and the HTTP Proxy API are configured with basic authentication by default.

To enable basic authentication for the Admin API:

  • Operator

  • Helm

redpanda-cluster.yaml
apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    auth:
      sasl:
        enabled: true
        secretRef: redpanda-superusers
    config:
      cluster:
        admin_api_require_auth: true
kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

  • --values

  • --set

enable-sasl.yaml
auth:
  sasl:
    enabled: true
    secretRef: redpanda-superusers
config:
  cluster:
    admin_api_require_auth: true
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values sasl-enable.yaml --reuse-values
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set auth.sasl.enabled=true \
  --set auth.sasl.secretRef=redpanda-superusers \
  --set config.cluster.admin_api_require_auth=true
Connect to the HTTP API

By default, the Redpanda Helm chart configures an internal and external listener for the HTTP Proxy API.

To access the internal listener:

kubectl exec <pod-name> --namespace <namespace> -- curl http://redpanda-0.redpanda.redpanda.svc.cluster.local:8082/topics -u <username>:<password> -sS

If TLS is enabled, specify the HTTPS protocol and pass the path to the ca.crt file:

kubectl exec <pod-name> --namespace <namespace> -- curl https://redpanda-0.redpanda.redpanda.svc.cluster.local:8082/topics --cacert /etc/tls/certs/default/ca.crt -u <username>:<password> -sS
If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the --cacert flag.

For all available endpoints, see the HTTP Proxy API reference.

Connect to the Schema Registry API

By default, the Redpanda Helm chart configures an internal and external listener for the Schema Registry API.

To access the internal listener:

kubectl exec <pod-name> --namespace <namespace> -- curl http://redpanda-0.redpanda.redpanda.svc.cluster.local:8081/subjects -u <username>:<password> -sS

If TLS is enabled, specify the HTTPS protocol and pass the path to the ca.crt file:

kubectl exec <pod-name> --namespace <namespace> -- curl https://redpanda-0.redpanda.redpanda.svc.cluster.local:8081/subjects --cacert /etc/tls/certs/default/ca.crt -u <username>:<password> -sS
If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the --cacert flag.

For all available endpoints, see the Schema Registry API.

OIDC

You can configure the HTTP APIs to authenticate users with the OIDC bearer token. By using OIDC, you can centralize credentials and provide a password-free SSO experience.

See Enable OIDC to configure the required OIDC cluster configuration properties before enabling OIDC for the HTTP APIs. You can configure OIDC without enabling it for the Kafka API.

If you enable OIDC authentication for the Admin API, you must also create a SCRAM superuser so that you can use rpk to create ACLs. rpk supports only basic authentication for the Admin API. See Authentication for the HTTP APIs.

To enable OIDC for the HTTP API listeners as well as basic authentication, include OIDC in the http_authentication cluster property list:

Valid values for the cluster configuration property http_authentication (cluster-wide) are BASIC and OIDC. The value BASIC here is different from the per-listener setting http_basic, which enables authentication on a listener using the broker property authentication_method (see authentication_method for the Schema Registry listener and authentication_method for the HTTP Proxy listener).

  • Operator

  • Helm

redpanda-cluster.yaml
apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    auth:
      sasl:
        enabled: true
    config:
      cluster:
        sasl_mechanisms:
          - "SCRAM"
          - "OAUTHBEARER"
        http_authentication:
          - "BASIC"
          - "OIDC"
kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

  • --values

  • --set

enable-sasl.yaml
auth:
  sasl:
    enabled: true
config:
  cluster:
    sasl_mechanisms:
      - "SCRAM"
      - "OAUTHBEARER"
    http_authentication:
      - "BASIC"
      - "OIDC"
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values sasl-enable.yaml --reuse-values
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set auth.sasl.enabled=true \
  --set "config.cluster.sasl_mechanisms[0]=SCRAM" \
  --set "config.cluster.sasl_mechanisms[1]=OAUTHBEARER" \
  --set "config.cluster.http_authentication[0]=BASIC" \
  --set "config.cluster.http_authentication[1]=OIDC"
Connect to the HTTP API

By default, the Redpanda Helm chart configures an internal and external listener for the HTTP Proxy API.

To access the internal listener:

kubectl exec <pod-name> --namespace <namespace> -- curl http://redpanda-0.redpanda.redpanda.svc.cluster.local:8082/topics -H "Authorization: Bearer <bearer-token>" -sS

If TLS is enabled, specify the HTTPS protocol and pass the path to the ca.crt file:

kubectl exec <pod-name> --namespace <namespace> -- curl https://redpanda-0.redpanda.redpanda.svc.cluster.local:8082/topics --cacert /etc/tls/certs/default/ca.crt -H "Authorization: Bearer <bearer-token>" -sS
If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the --cacert flag.

For all available endpoints, see the HTTP Proxy API reference.

Connect to the Schema Registry API

By default, the Redpanda Helm chart configures an internal and external listener for the Schema Registry API.

To access the internal listener:

kubectl exec <pod-name> --namespace <namespace> -- curl http://redpanda-0.redpanda.redpanda.svc.cluster.local:8081/subjects -H "Authorization: Bearer <bearer-token>" -sS

If TLS is enabled, specify the HTTPS protocol and pass the path to the ca.crt file:

kubectl exec <pod-name> --namespace <namespace> -- curl https://redpanda-0.redpanda.redpanda.svc.cluster.local:8081/subjects --cacert /etc/tls/certs/default/ca.crt -H "Authorization: Bearer <bearer-token>" -sS
If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the --cacert flag.

For all available endpoints, see the Schema Registry API.

Disable authentication

To disable authentication for a listener, set authentication_method broker property to none:

Breaking change in Redpanda 25.2: Ephemeral credentials for HTTP Proxy are removed. If your HTTP Proxy API listeners use authentication_method: none, you must configure explicit SASL credentials (scram_username, scram_password, and sasl_mechanism) for HTTP Proxy to authenticate with the Kafka API.

This allows any HTTP API user to access Kafka using shared credentials. Redpanda Data recommends enabling HTTP Proxy authentication instead.

For details about this breaking change, see What’s new.

  • Operator

  • Helm

redpanda-cluster.yaml
apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    auth:
      sasl:
        enabled: true
    listeners:
      http:
        authentication_method: "none"
      schemaRegistry:
        authentication_method: "none"
      kafka:
        authentication_method: "none"
kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

  • --values

  • --set

enable-sasl.yaml
auth:
  sasl:
    enabled: true
listeners:
  http:
    authentication_method: "none"
  schemaRegistry:
    authentication_method: "none"
  kafka:
    authentication_method: "none"
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values sasl-enable.yaml --reuse-values
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set auth.sasl.enabled=true \
  --set listeners.http.authentication_method=none \
  --set listeners.schemaRegistry.authentication_method=none \
  --set listeners.kafka.authentication_method=none

Generate security report

Use the /v1/security/report endpoint to generate a comprehensive security report for your cluster. This endpoint provides detailed information about current TLS configuration, authentication methods, authorization status, and security alerts across all Redpanda interfaces (Kafka, RPC, Admin, Schema Registry, HTTP Proxy).

To generate a security report for your Redpanda cluster, run:

Input
curl 'http://localhost:9644/v1/security/report'
View output 
{
  "interfaces": {
    "kafka": [
      {
        "name": "test_kafka_listener",
        "host": "0.0.0.0",
        "port": 9092,
        "advertised_host": "0.0.0.0",
        "advertised_port": 9092,
        "tls_enabled": false,
        "mutual_tls_enabled": false,
        "authentication_method": "None",
        "authorization_enabled": false
      }
    ],
    "rpc": {
      "host": "0.0.0.0",
      "port": 33145,
      "advertised_host": "127.0.0.1",
      "advertised_port": 33145,
      "tls_enabled": false,
      "mutual_tls_enabled": false
    },
    "admin": [
      {
        "name": "test_admin_listener",
        "host": "0.0.0.0",
        "port": 9644,
        "tls_enabled": false,
        "mutual_tls_enabled": false,
        "authentication_methods": [],
        "authorization_enabled": false
      }
    ]
  },
  "alerts": [
    {
      "affected_interface": "kafka",
      "listener_name": "test_kafka_listener",
      "issue": "NO_TLS",
      "description": "\"kafka\" interface \"test_kafka_listener\" is not using TLS. This is insecure and not recommended."
    },
    {
      "affected_interface": "kafka",
      "listener_name": "test_kafka_listener",
      "issue": "NO_AUTHN",
      "description": "\"kafka\" interface \"test_kafka_listener\" is not using authentication. This is insecure and not recommended."
    },
    {
      "affected_interface": "kafka",
      "listener_name": "test_kafka_listener",
      "issue": "NO_AUTHZ",
      "description": "\"kafka\" interface \"test_kafka_listener\" is not using authorization. This is insecure and not recommended."
    },
    {
      "affected_interface": "rpc",
      "issue": "NO_TLS",
      "description": "\"rpc\" interface is not using TLS. This is insecure and not recommended."
    },
    {
      "affected_interface": "admin",
      "listener_name": "test_admin_listener",
      "issue": "NO_TLS",
      "description": "\"admin\" interface \"test_admin_listener\" is not using TLS. This is insecure and not recommended."
    },
    {
      "affected_interface": "admin",
      "listener_name": "test_admin_listener",
      "issue": "NO_AUTHZ",
      "description": "\"admin\" interface \"test_admin_listener\" is not using authorization. This is insecure and not recommended."
    },
    {
      "affected_interface": "admin",
      "listener_name": "test_admin_listener",
      "issue": "NO_AUTHN",
      "description": "\"admin\" interface \"test_admin_listener\" is not using authentication. This is insecure and not recommended."
    }
  ]
}

Troubleshoot

This section lists error messages and provides ways to diagnose and solve issues. For more troubleshooting steps, see Troubleshoot Redpanda in Kubernetes.

Unable to continue with update: Secret

When you use a YAML list to specify superusers, the Helm chart creates a Secret using the value of auth.sasl.secretRef as the Secret’s name, and stores those superusers in the Secret. If the Secret already exists in the namespace when you deploy Redpanda, the following error is displayed:

Error: UPGRADE FAILED: rendered manifests contain a resource that already exists. Unable to continue with update: Secret

To fix this error, ensure that you use only one of the following methods to create superusers:

  • auth.sasl.secretRef

  • auth.sasl.users

Is SASL missing?

This error appears when you try to interact with a cluster that has SASL enabled without passing a user’s credentials.

unable to request metadata: broker closed the connection immediately after a request was issued, which happens when SASL is required but not provided: is SASL missing?

If you’re using rpk, ensure to specify the -X user, -X pass, and -X sasl.mechanism flags.

For all available flags, see the rpk options reference.

Next steps

Suggested reading

Suggested labs

Search all labs