Manage Authentication for Confluent Platform Using Confluent for Kubernetes

This topic describes post-deployment tasks for managing authentication in Confluent Platform, specifically updating user credentials for Kafka, KRaft, and the Metadata Service (MDS).

The process to rotate a user credential differs based on the types of users: internal client users and external client users.

Internal users for authenticating between brokers and controllers
1. Create secret for existing user to ensure old credentials remain valid for brokers not yet updated.
2. Add new user/credentials to allow a gradual transition. Both credentials work during rolling update.
3. Remove old user/secret only after all brokers can successfully use the new credentials.
External client users for authenticating to Kafka

Add new user/credentials.

This topic covers several common use cases for updating user credentials, but you can apply the same high-level workflow for other authentication types and use cases based on whether the user is an internal user or an external client user.

For the steps to configure credentials, see Configure authentication to access Kafka and KRaft.

Update Kafka or KRaft SASL/PLAIN external client users

To update the external client-facing SASL/PLAIN user credentials for Kafka or KRaft, follow the steps described in this section based on the method you use to provide required credentials, namely jaasConfig or jaasConfigPassThrough.

Starting with CFK 3.2.0, CFK hot-reloads SASL/PLAIN credential changes so that broker restarts are no longer required for user management.

Hot-reload scope and limitations

Applies only to external SASL/PLAIN credentials on the server side. Do not use hot-reload for inter-broker SASL/PLAIN credentials or Confluent component authentication.
Not supported for SASL/PLAIN with LDAP or when using configOverrides.
Requires FileBasedLoginModule. This module is automatic with jaasConfig. You must configure it explicitly when using jaasConfigPassThrough.

Update server-side SASL/PLAIN users

Update users using jaasConfig

To add users to the authenticated users list, you need to update the list in the text file and update the secret.

Fetch the user credentials defined under the key plain-users.json from the clusters secret using the following command:
```
kubectl get secret -n <namespace> <NAME_OF_SECRET_FROM_JAAS_CONFIG> \
  --template="{{index .data \"plain-users.json\" | base64decode }}"
```
- <NAME_OF_SECRET_FROM_JAAS_CONFIG> is the value corresponding to the secret referenced in the affected listener spec.listeners.<listener-type>.authentication.jaasConfig.secretRef
- <listener-type> can be external or custom based on the listener type you use for the external client users. For a custom listener, locate the entry in the custom array by its name. The custom field is a list, not a map keyed by listener name.
Copy the contents of the output and save it in a new file called creds-kafka-sasl-users.json.

In the creds-kafka-sasl-users.json file, add the new user and its password.

For example:

{
"kafka_client": "kafka_client-secret",
"c3": "c3-secret",
"kafka": "kafka-secret",
"new_user": "password"
}

Update the Kubernetes secret.

In the following command, you generate the YAML for the secret and apply it as an update to the existing secret, credential.

For --from-file, you must use the plain-users.json key, as --from-file=plain-users.json.
```
kubectl create secret generic credential \
  --from-file=plain-users.json=creds-kafka-sasl-users.json \
  --save-config --dry-run=client -oyaml | \
  kubectl apply -f -
```

You do not need to restart the Kafka brokers. The updated users list is picked up by the services.

Update users using jaasConfigPassThrough

To add users to the authenticated users list, you need to update the configuration file in the secret and perform a rolling update of Kafka.

In plain-jaas.conf, add the new user and its password.

For example:

sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
   username="admin" \
   password="admin-secret" \
   user_admin="admin-secret" \
   user_alice="alice-secret" \
   user_newuser="password";

Update the secret with the new file contents as described in Update users using jaasConfig, substituting plain-jaas.conf for plain-users.json.
Update the Kubernetes secret.

In the following command, you generate the YAML for the secret and apply it as an update to the existing secret, credential.

For --from-file, you must use the plain-jaas.conf key, as --from-file=plain-jaas.conf.
```
kubectl create secret generic credential \
  --from-file=plain-jaas.conf=plain-jaas.conf \
  --save-config --dry-run=client -oyaml | \
  kubectl apply -f -
```

You do not need to restart the Kafka brokers. The updated users list is picked up by the services.

Update client-side SASL/PLAIN users using JAAS configuration

To update the user credentials, update the credentials in the text file and update the secret:

In a text file, named creds-kafka-sasl-users.txt, update the following content:
```
username=<username>
password=<password>
```
Create a Kubernetes secret.

In the following command, you generate the YAML for the secret and apply it as an update to the existing secret, credential.

For --from-file, you must use the plain.txt key, as --from-file=plain.txt.
```
kubectl create secret generic credential \
  --from-file=plain.txt=creds-kafka-sasl-users.txt \
  --save-config --dry-run=client -oyaml | \
  kubectl apply -f -
```
Restart the Confluent Platform components that depend on the plain.txt key so that the updated user is picked up by the services.

Update Kafka or KRaft OAuth/OIDC users

Update the external-facing OAuth/OpenID Connect (OIDC) client user credentials for Kafka or KRaft by following the steps described in this section.

Update server-side OAuth/OIDC users

Create a secret that contains the new OIDC client ID and the client secret for authorization and token request to the identity provider (IdP).

The secret must contain two keys with their respective values, clientId and clientSecret as follows:
```
clientId=<client-id>
clientSecret=<client-secret>
```

Update the Kafka or KRaft custom resource (CR) to use the new secret and apply the changes.

kind: <Kafka or KRaftController>
spec:
  listeners:
    internal / external:
      authentication:
        type: oauth
        jaasConfig/jaasConfigPassThrough:
          secretRef:

Update client-side OAuth/OIDC users

Important

The current/older OIDC client credential must remain valid until the rotation is completed and the component is rolled.

Create a secret that contains the new OIDC client ID and the client secret for authorization and token request to the identity provider (IdP).

The secret must contain two keys with their respective values, clientId and clientSecret as follows:
```
clientId=<client-id>
clientSecret=<client-secret>
```

Update the client component CR to use the new secret and apply the changes.

kind: <Confluent component>
spec:
  dependencies:
    kafka:
      authentication:
        type: oauth
        jaasConfig/jaasConfigPassThrough:
          secretRef:

Update MDS user

MDS uses a dedicated LDAP bind user, configured in spec.services.mds.provider.ldap, to authenticate and search your LDAP server. To rotate this credential, add a standby user and swap to it. Do not change the password of the existing MDS bind user in place.

Important

The current or older MDS user must remain valid until the new user is confirmed working end-to-end. Changing the password of the existing MDS bind user in place, instead of swapping to a new user, can leave brokers unable to re-authenticate against MDS during the resulting rolling restart.

To update the MDS user credentials:

Add a standby user (for example, mds2) to your LDAP server with a new password. Grant it the same bind and search access control lists (ACLs) as the existing MDS bind user.

Note

LDAP treats bind (authenticate) and search (query directory entries) as separate permissions. If the standby user has only bind rights, it authenticates successfully but fails when MDS searches the directory, with an error similar to LDAP: error code 32 - No Such Object. Confirm that the standby user has both bind and search ACLs before you continue.
Set the platform.confluent.io/roll-delay-interval-seconds annotation on the Kafka CR to increase the pacing between broker restarts, for example, to 300 seconds:
```
kind: Kafka
metadata:
  annotations:
    platform.confluent.io/roll-delay-interval-seconds: "300"
```
This gives the _confluent-metadata-auth topic and each broker’s authorizer time to stabilize before the next broker restarts. The default pacing is 60 seconds when roll-delay-interval-seconds is not set.
Update the .txt file that contains the LDAP credentials with the standby user’s credentials, in the following format:
```
username=<bindDn_value>
password=<bindPassword_value>
```
For the password for bindDn, escape any restricted LDAP characters. For best results, avoid characters that require escaping.
Create a new secret with the expected key (ldap.txt) and the value file you created in the previous step, then update spec.services.mds.provider.ldap.authentication.simple.secretRef on the Kafka CR to point to the new secret. Don’t patch the existing secret’s content in place.
```
kubectl create secret generic credential-mds2 \
  --from-file=ldap.txt=./ldap.txt
```
```
kind: Kafka
spec:
  services:
    mds:
      provider:
        ldap:
          authentication:
            simple:
              secretRef: credential-mds2
```
Important

Patching an existing secret’s content in place only gets CFK’s safe, paced rolling restart starting in CFK 3.2. On older operators, an in-place content edit can trigger a less-controlled restart, the exact behavior this procedure exists to avoid. Changing which secret the CR’s secretRef field points to is a Kafka CR specification change, which has always gone through CFK’s paced, operator-controlled rolling restart, on every CFK version this procedure supports. For this reason, keep the MDS LDAP bind credential in its own dedicated secret, separate from the secret used for the Kafka/KRaft SASL/PLAIN listener authentication.

For details on CFK’s secret-update behavior, see Secret updates and safe rolling restarts.
Before you decommission the old user, verify that the rotation succeeded:
1. Confirm that all brokers reach the Ready state.
2. Confirm that the _confluent-metadata-auth topic remains healthy and that port 8090 (the MDS REST/token endpoint, confluent.metadata.server.listeners) opens on each broker.
3. Confirm that a produce or consume operation gated by a role binding succeeds for the standby user. Do not rely on pod status alone.
After verification succeeds, remove the old LDAP user from the LDAP server.

Note

Only the MDS bind user requires this standby-user swap. You can rotate other server account passwords in place, using the same username, after the MDS user rotation completes and the roll settles.