​
Overview

Find out how Conduktor Gateway manages service accounts, client authentication and ACLs (Access Control Lists):
  • where to authenticate clients, Gateway or Kafka
  • which authentication method to use
  • when to use local or external service accounts
  • how and where to manage service account ACLs

​
Client authentication methods

Gateway supports different client authentication methods, depending on both the type of service account(local or external) and the security mode (Gateway managed or Kafka managed). This table shows which service account will need to be provided:
ModeProtocolLocal service accountExternal service account
Anonymous
GATEWAY_MANAGEDPLAINTEXT❌❌
SSL❌❌
SSL with client auth (mTLS)❌✅
SSL❌✅
SASL
SASL_PLAINTEXT✅only if OAUTHBEARER
SASL_SSL✅only if OAUTHBEARER
KAFKA_MANAGEDSASL_PLAINTEXT❌✅
SASL_SSL❌✅
As of Gateway v3.10.0, the DELEGATED_XXX security protocols have been deprecated in favour of the security mode, set by an additional environment variable GATEWAY_SECURITY_MODE. These values remain supported for backward compatibility but will be deprecated in future and are no longer the recommendation for new configurations.If you’re using DELEGATED security protocols, see the security mode migration guide.

​
Anonymous authentication

​
PLAINTEXT

In the case of PLAINTEXT authentication, the client is anonymous and doesn’t need any credentials. Thus, authentication can’t take place and so local and external service accounts are not supported in this mode. Find out how to configure the client > Gateway connection with PLAINTEXT.

​
SSL (encryption only)

If you’re using SSL for transport layer encryption only, Gateway presents a keystore certificate trusted by the client’s truststore, without authenticating the client. Thus, local and external service accounts are not supported in this mode. Find out how to configure the client > Gateway connection with SSL.

​
SSL with client authentication (mTLS)

With mutual TLS (mTLS) authentication, both Kafka clients and Gateway validate each other’s identities using TLS certificates, ensuring secure and trusted bidirectional communication. This means that both the client and Gateway authenticate one another through their respective certificates. As a result, Gateway extracts the user identity from the TLS certificate, which can be mapped to an external service account in Gateway.
The username will be in this format: CN=writeuser,OU=Unknown,O=Unknown,L=Unknown,ST=Unknown,C=Unknown. You can change this by setting the GATEWAY_SSL_PRINCIPAL_MAPPING_RULES environment variable to a customized rule. By default, it extracts the certificate distinguished name.For example, GATEWAY_SSL_PRINCIPAL_MAPPING_RULES=RULE:^CN=([a-zA-Z0-9.-]*).*$$/$$1/ , DEFAULT will extract the CN part of the certificate.
See how to configure the client to Gateway connection with SSL mTLS.

​
SASL authentication

With SASL authentication using OAUTHBEARER, clients authenticate with an identity (the sub in the OIDC JWT token) which can be mapped to an external service account in Gateway.
If you have configured OAUTHBEARER, Gateway expects the client to provide a JWT token and the grant type should be clientcredentials.
Find out how to manage Gateway service accounts using SASL_PLAINTEXT. It’s the same for both SASL_PLAINTEXT and SASL_SSL. The only difference is that SASL_SSL encrypts the communication, while SASL_PLAINTEXT transmits in plain text. Find out how to configure the client to Gateway connection with SASL_SSL.
With Conduktor Gateway, you can decide where you’d like the client authentication and authorization to be made. This means that you can either:
  • allow the backing Kafka cluster to manage them (Kafka Managed SASL authentication) - in this mode Gateway forwards the client credentials to the Kafka cluster to authenticate them and retrieve their ACL rules. Or you can
  • manage them with Gateway (using the supported client authentication methods) - in this mode, Gateway manages the client authentication and authorization, based on their associated ACL rules.

​
Kafka managed SASL authentication

In some cases, you might want to delegate the authentication to the backing Kafka cluster. For example, you want to gradually transition to using the Conduktor Gateway but first want to continue using the ACLs and service accounts defined in your Kafka cluster. In this case, Gateway can forward the client credentials to the backing Kafka cluster, and the Kafka cluster will authenticate the client for Gateway.
Currently, Kafka managed SASL authentication only supports PLAIN, SCRAM, OAUTHBEARER and AWS_MSK_IAM mechanisms. If you have specific requirements, get in touch.
In this mode, the client’s authorization (ACLs) is also handled by the backing Kafka cluster. Any calls to the Kafka ACLs API made on Gateway will be forwarded to the backing Kafka cluster. Therefore, local service Accounts are not available on Gateway but the external service accounts are available and can be mapped to the client principal. This way Gateway will apply its Interceptors on this external service account with a friendly name.
Virtual resources such as virtual clusters, alias topics and concentrated topics are not available in Kafka managed mode.
Find out how to configure the client to Gateway connection with KAFKA_MANAGED.

​
Authorization management (ACLs)

​
In Kafka managed mode

Authorization (ACLs) is handled by the backing Kafka cluster. Any calls to the Kafka ACLs API made on Gateway will be forwarded to the backing Kafka cluster.

​
In Gateway managed mode

Authorization (ACLs) is managed by Gateway, so you have to define the ACLs for your applications in Gateway. This is done using the Kafka ACLs commands or the Conduktor Console UI. The principal attached to the ACLs can either be the local or the external service account name. If the client connects to Gateway using OAUTHBEARER but no external service account is defined, the sub of the JWT client token will be used as the principal.