4. Configure Gateway to accept client connections

Gateway brokers support multiple security schemes for Kafka clients to connect with. Each section has specific details of the available options, how they work and how to configure them. Pick the most suitable option based on the nature of your system’s requirements, design and constraints. The authentication phase on Gateway is part of the initial communication handling by Gateway to handshake, and authenticate, a Kafka client. This phase manages the encryption of the network communication and how to identify a client. All open connections in Gateway result in a Principal that represents the authenticated identity of the Kafka client. We can split this authentication and security configuration into two aspects:

Security protocol: defines how a Kafka client and Gateway broker should communicate and secure the connection.
Authentication mechanism: defines how a client can authenticate itself when opening the connection.

Supported security protocols:

PLAINTEXT: Brokers don’t need client authentication; all communication is exchanged without network security.
SSL: With SSL-only clients don’t need any client authentication but communication between the client and Gateway broker will be encrypted.
mTLS: This security protocol is not originally intended to provide authentication, but you can use the mTLS option below to enable an authentication. mTLS leverages SSL mutual authentication to identify a Kafka client. Principal for mTLS connection can be detected from the subject certificate using the same feature as in Apache Kafka, the SSL principal mapping.
SASL PLAINTEXT: Brokers don’t need any client authentication and all communication is exchanged without any network security.
SASL SSL: Authentication from the client is mandatory against Gateway and communication will be encrypted using TLS.
DELEGATED_SASL_PLAINTEXT: Authentication from the client is mandatory but will be forwarded to Kafka for checking. Gateway will intercept exchanged authentication data to detect authenticated principals:
- All communication between the client and gateway broker is exchanged without any network security.
- All credentials are managed by your backend kafka, we only provide authorization on the Gateway side based on the exchanged principal.

	Clients ⟶ GW transit in plaintext	Clients ⟶ GW transit is encrypted
Anonymous access only	Security protocol: `PLAINTEXT` Authentication mechanism: `None`	Security protocol: `SSL` Authentication mechanism: `None`
Credentials managed by Gateway	Security protocol: `SASL_PLAINTEXT` Authentication mechanism: `PLAIN`	Security protocol: `SASL_SSL` Authentication mechanism: `PLAIN`
Gateway configured with OAuth	Security protocol: `SASL_PLAINTEXT` Authentication mechanism: `OAUTHBEARER`	Security protocol: `SASL_SSL` Authentication mechanism: `OAUTHBEARER`
Clients are identified by certificates (mTLS)	Not possible (mTLS means encryption)	Security protocol: `SSL` Authentication mechanism: `MTLS`
Credentials managed by Kafka	Security protocol: `DELEGATED_SASL_PLAINTEXT` Authentication mechanism: `PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512`, `OAUTHBEARER` or`AWS_MSK_IAM`	Security protocol: `DELEGATED_SASL_SSL` Authentication mechanism: `PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512`, `OAUTHBEARER` or`AWS_MSK_IAM`

Security protocol

The Gateway broker security scheme is defined by the GATEWAY_SECURITY_PROTOCOL configuration. Note that you don’t set an authentication mechanism on the client to Gateway side of the proxy, i.e. GATEWAY_SASL_MECHANISM does not exist and is never configured by the user. Instead, Gateway will try to authenticate the client as it presents itself. For example, if a client is using OAUTHBEARER, Gateway will use the OAuth configuration to try authenticate it. If a client arrives using PLAIN, Gateway will try use either the SSL configuration or validate the token itself, depending on the security protocol. In addition to all the security protocols that Apache Kafka supports, Gateway adds two new protocols:DELEGATED_SASL_PLAINTEXT and DELEGATED_SASL_SSL for delegating to Kafka.

PLAINTEXT

There is no client authentication to Gateway and all communication is exchanged without any network security. Gateway configuration:

GATEWAY_SECURITY_PROTOCOL: PLAINTEXT

Client configuration:

bootstrap.servers=your.gateway.hostname:9092
security.protocol=PLAINTEXT

SSL

With SSL only, there is no client authentication, but communication between the client and Gateway broker will be encrypted. Gateway configuration:

GATEWAY_SECURITY_PROTOCOL: SSL
GATEWAY_SSL_KEY_STORE_PATH: /path/to/your/keystore.jks
GATEWAY_SSL_KEY_STORE_PASSWORD: yourKeystorePassword
GATEWAY_SSL_KEY_PASSWORD: yourKeyPassword

Client configuration:

bootstrap.servers=your.gateway.hostname:9092
security.protocol=SSL
ssl.truststore.location=/path/to/your/truststore.jks
ssl.truststore.password=yourTruststorePassword
ssl.protocol=TLSv1.3

The truststore contains certificates from trusted Certificate Authorities (CAs) used to verify Gateway’s TLS certificate, which is stored in the keystore. Find out more about JKS truststores.

mTLS

Mutual TLS leverages client side certificates to authenticate a Kafka client. Principal for an mTLS connection can be detected from the subject of the certificate using the same feature as Apache Kafka, the SSL principal mapping. Gateway configuration:

GATEWAY_SECURITY_PROTOCOL: SSL
GATEWAY_SSL_CLIENT_AUTH: REQUIRE
GATEWAY_SSL_KEY_STORE_PATH: /path/to/your/keystore.jks
GATEWAY_SSL_KEY_STORE_PASSWORD: yourKeystorePassword
GATEWAY_SSL_KEY_PASSWORD: yourKeyPassword
GATEWAY_SSL_TRUST_STORE_PATH: /path/to/your/truststore.jks
GATEWAY_SSL_TRUST_STORE_PASSWORD: yourTrustStorePassword

Client configuration:

bootstrap.servers=your.gateway.hostname:9093
security.protocol=SSL
ssl.keystore.type=PEM
ssl.keystore.key=/path/to/your/client.key
ssl.keystore.certificate.chain=/path/to/your/client.crt
ssl.truststore.type=PEM
ssl.truststore.certificates=/path/to/your/ca.crt
ssl.protocol=TLSv1.3
ssl.client.auth=required

The server CA certificate here is provided as a PEM file as well as the client’s certificates (ssl.keystore.xx keys). Jks could also be used for both client and server side authentication.

SASL_PLAINTEXT

Authentication from the client is mandatory against Gateway but all communications are exchanged without any network security. Gateway supports Plain and OAuthbearer SASL mechanisms.

Plain

Plain mechanism uses Username/Password credentials to authenticate credentials against Gateway. Plain credentials take the form of a JWT token, these are managed in Gateway using the Admin (HTTP) API. See below for the creation of tokens. Gateway configuration:

GATEWAY_SECURITY_PROTOCOL: SASL_PLAINTEXT
GATEWAY_USER_POOL_SECRET_KEY: yourRandom256bitKeyUsedToSignTokens

TheGATEWAY_USER_POOL_SECRET_KEY has to be set to a random base64 encoded value of 256bits long to ensure that tokens aren’t forged. For example: openssl rand -base64 32. Otherwise, a default value for signing tokens will be used. Client configuration:

bootstrap.servers=your.gateway.hostname:9092
security.protocol=SASL_PLAINTEXT
sasl.mechanism=PLAIN
sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
  username="yourUsername" \
  password="yourToken";

It has to be a token that’s obtained by a Gateway admin via the Admin (HTTP) API, as follows:

Create the service account, the username

Request:

curl \
  --request PUT \
  --url 'http://localhost:8888/gateway/v2/service-account' \
  --user admin:conduktor \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "kind" : "GatewayServiceAccount",
    "apiVersion" : "gateway/v2",
    "metadata" : {
      "name" : "jdoe",
      "vCluster" : "passthrough"
    },
    "spec" : { "type" : "LOCAL" }'

Response:

{
  "resource" : {
    "kind" : "GatewayServiceAccount",
    "apiVersion" : "gateway/v2",
    "metadata" : {
      "name" : "jdoe",
      "vCluster" : "passthrough"
    },
    "spec" : {
      "type" : "LOCAL"
    }
  },
  "upsertResult" : "CREATED"
}

Generate a token for the service account, the password

Request:

curl \
  --silent \
  --request POST \
  --url 'http://localhost:8888/gateway/v2/token' \
  --header 'Authorization: Basic YWRtaW46Y29uZHVrdG9y' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "username": "jdoe",
    "vCluster": "passthrough",
    "lifeTimeSeconds": 3600000
  }'

{"token":"eyJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6Impkb2UiLCJ2Y2x1c3RlciI6InBhc3N0aHJvdWdoIiwiZXhwIjoxNzQ1MzY1OTcxfQ.zPPiD17MiRnXyHJw07Cx4SKPySDi_ErJrXmi5BycR04"}

The token conforms to the JWT token specification. The JWT payload contains the username, the vCluster and the expiration date:

jwt decode eyJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6Impkb2UiLCJ2Y2x1c3RlciI6InBhc3N0aHJvdWdoIiwiZXhwIjoxNzQ1MzY1OTcxfQ.zPPiD17MiRnXyHJw07Cx4SKPySDi_ErJrXmi5BycR04

Token claims
------------
{
  "exp": 1745365971,
  "username": "jdoe",
  "vcluster": "passthrough"
}

OAuthbearer

Oauthbearer uses a OAuth2/OIDC security provider to authenticate a token in Gateway. The Oauth credentials base is managed in the configured provider. This mechanism will also allow you to verify some claims from your OIDC provider ( audience and issuer ). Gateway configuration:

GATEWAY_SECURITY_PROTOCOL: SASL_PLAINTEXT
GATEWAY_OAUTH_JWKS_URL: https://login.microsoftonline.com/common/discovery/keys
GATEWAY_OAUTH_EXPECTED_ISSUER: https://sts.windows.net/xxxxxxxx-df00-48cd-805b-1ebe914e8b11/
GATEWAY_OAUTH_EXPECTED_AUDIENCES: "[00000002-0000-0000-c000-000000000000]"

Client configuration:

bootstrap.servers=your.gateway.hostname:9092
security.protocol=SASL_PLAINTEXT
sasl.mechanism=OAUTHBEARER
sasl.login.callback.handler.class=org.apache.kafka.common.security.oauthbearer.secured.OAuthBearerLoginCallbackHandler
sasl.oauthbearer.token.endpoint.url=https://login.microsoftonline.com/xxxxxxxx-df00-48cd-805b-1ebe914e8b11/oauth2/token
sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
 clientId="yourClientID" \
  clientSecret="yourClientSecret" \
  scope=".default";

SASL_SSL

Authentication from client is mandatory against Gateway and communication will be encrypted using TLS. Supported authentication mechanisms:

PLAIN
OAUTHBEARER

Plain

Plain mechanism use Username/Password credentials to authenticate credentials against Gateway. Plain credentials are managed in Gateway using the HTTP API. Gateway configuration:

GATEWAY_SECURITY_PROTOCOL: SASL_SSL
GATEWAY_USER_POOL_SECRET_KEY: yourRandom256bitKeyUsedToSignTokens
GATEWAY_SSL_KEY_STORE_PATH: /path/to/your/keystore.jks
GATEWAY_SSL_KEY_STORE_PASSWORD: yourKeystorePassword
GATEWAY_SSL_KEY_PASSWORD: yourKeyPassword

You have to set GATEWAY_USER_POOL_SECRET_KEY to a random value to ensure that tokens cannot be forged. Otherwise, a default value for signing tokens will be used. Client configuration:

bootstrap.servers=your.gateway.hostname:9093
security.protocol=SASL_SSL
sasl.mechanism=PLAIN
ssl.truststore.location=/path/to/your/truststore.jks
ssl.truststore.password=yourTruststorePassword
sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
  username="yourUsername" \
  password="yourToken";

See the above section for requirements on how to create tokens using the Admin (HTTP) API.

OAuthbearer

GATEWAY_SECURITY_PROTOCOL: SASL_SSL
GATEWAY_OAUTH_JWKS_URL: https://login.microsoftonline.com/common/discovery/keys
GATEWAY_OAUTH_EXPECTED_ISSUER: https://sts.windows.net/xxxxxxxx-df00-48cd-805b-1ebe914e8b11/
GATEWAY_OAUTH_EXPECTED_AUDIENCES: "[00000002-0000-0000-c000-000000000000]"
GATEWAY_SSL_KEY_STORE_PATH: /path/to/your/keystore.jks
GATEWAY_SSL_KEY_STORE_PASSWORD: yourKeystorePassword
GATEWAY_SSL_KEY_PASSWORD: yourKeyPassword

Client configuration:

bootstrap.servers=your.gateway.hostname:9092
security.protocol=SASL_SSL
sasl.mechanism=OAUTHBEARER
ssl.truststore.location=/path/to/your/truststore.jks
ssl.truststore.password=yourTruststorePassword
sasl.login.callback.handler.class=org.apache.kafka.common.security.oauthbearer.secured.OAuthBearerLoginCallbackHandler
sasl.oauthbearer.token.endpoint.url=https://login.microsoftonline.com/xxxxxxxx-df00-48cd-805b-1ebe914e8b11/oauth2/token
sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
  clientId="yourClientID" \
  clientSecret="yourClientSecret" \
  scope=".default";

DELEGATED_SASL_PLAINTEXT

Authentication from client is mandatory but will be forwarded to Kafka for checking. Gateway will intercept exchanged authentication data to detect an authenticated principal:

All communication between the client and Gateway broker are exchanged without any network security.
All credentials are managed by your backing Kafka, we only provide authorization on the Gateway side based on the exchanged principal.

Supported authentication mechanisms on the backing Kafka are:

PLAIN
SCRAM-SHA-256
SCRAM-SHA-512
OAUTHBEARER
AWS_MSK_IAM

Gateway configuration: using PLAIN, as used for example on Confluent Cloud:

GATEWAY_SECURITY_PROTOCOL: DELEGATED_SASL_PLAINTEXT

Client configuration:

bootstrap.servers=your.gateway.hostname:9092
security.protocol=SASL_PLAINTEXT
sasl.mechanism=PLAIN
sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="yourKafkaUser" password="yourKafkaPassword";

DELEGATED_SASL_SSL

Authentication from the client is mandatory but will be forwarded to Kafka. Gateway will intercept exchanged authentication data to detect an authenticated principal:

All communication between the client and Gateway broker will be encrypted using TLS.
All credentials are managed by your backing Kafka, we only provide Authorization on the Gateway side based on the exchanged principal.

Supported authentication mechanisms on the backing Kafka are:

PLAIN
SCRAM-SHA-256
SCRAM-SHA-512
OAUTHBEARER
AWS_MSK_IAM

Gateway configuration using PLAIN, as used for example on Confluent Cloud:

GATEWAY_SECURITY_PROTOCOL: DELEGATED_SASL_SSL
GATEWAY_SSL_KEY_STORE_PATH: /path/to/your/keystore.jks
GATEWAY_SSL_KEY_STORE_PASSWORD: yourKeystorePassword
GATEWAY_SSL_KEY_PASSWORD: yourKeyPassword

Client configuration:

bootstrap.servers=your.gateway.hostname:9092
security.protocol=SASL_SSL
ssl.truststore.location=/path/to/your/truststore.jks
ssl.truststore.password=yourTruststorePassword
sasl.mechanism=PLAIN
sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="yourKafkaUser" password="yourKafkaPassword";

Principal resolver

When using Confluent Cloud authentication with delegated authentication, Gateway supports automatically resolving API keys to their associated service account. This feature enhances security and improves usability by working with the service account principals instead of raw API keys. See the principal resolver environment variables. Gateway configuration using environment variables:

GATEWAY_PRINCIPAL_RESOLVER: CONFLUENT_CLOUD
GATEWAY_CONFLUENT_CLOUD_API_KEY: your-api-key
GATEWAY_CONFLUENT_CLOUD_API_SECRET: your-api-secret
GATEWAY_CONFLUENT_CLOUD_CACHE_SIZE: 1000 # default
GATEWAY_CONFLUENT_CLOUD_CACHE_EXPIRY_MS: 86400000 # 1 day default

Gateway configuration using a configuration file

authenticationConfig:
  principalResolver: CONFLUENT_CLOUD
  confluentCloud:
    apiKey: ${GATEWAY_CONFLUENT_CLOUD_API_KEY}
    apiSecret: ${GATEWAY_CONFLUENT_CLOUD_API_SECRET}
    cacheConfig:
      maxSize: ${GATEWAY_CONFLUENT_CLOUD_CACHE_SIZE|1000}
      ttlMs: ${GATEWAY_CONFLUENT_CLOUD_CACHE_EXPIRY_MS|86400000} # 1 day

The value of GATEWAY_CONFLUENT_CLOUD_API_KEY has to be a Confluent Cloud API key because it will be used to access the Confluent Cloud API. Find out more about Confluent Cloud API keys.

When the principal resolver is configured, Gateway will automatically resolve Kafka cluster API keys (like XIGMNERQXOUKXDQU) to their associated owner, which will be either the user (e.g. u-12345) or the service account (e.g. sa-72839j).

Authentication flow

Automatic security protocol detection (default behavior)

If you don’t specify a security protocol, Gateway will attempt to detect it on startup based on the Kafka configuration. If there’s also no security protocol on the backing Kafka cluster, then we set the security protocol to PLAINTEXT by default. Here’s our mapping from the Kafka cluster’s defined protocol:

Kafka cluster security protocol	Gateway cluster inferred security protocol
SASL_SSL	DELEGATED_SASL_SSL
SASL_PLAINTEXT	DELEGATED_SASL_PLAINTEXT
SSL	SSL
PLAINTEXT	PLAINTEXT

You can always see the inferred security protocol in the startup logs for Gateway.

2025-03-07T15:40:12.260+0100 [      main] [INFO ] [Bootstrap:70] - Computed configuration :
---
gatewayClusterId: "gateway"
...
authenticationConfig:
  securityProtocol: "SASL_PLAINTEXT"
  sslConfig:
...

Re-authentication support

We support Apache Kafka re-authentication as Kafka brokers. Find out more about KIP-368.

Conduktor in production

Deploy Console

Deploy Gateway

Initial setup

4. Configure Gateway to accept client connections

Security protocol

PLAINTEXT

SSL

mTLS

SASL_PLAINTEXT

Plain

OAuthbearer

SASL_SSL

Plain

OAuthbearer

DELEGATED_SASL_PLAINTEXT

DELEGATED_SASL_SSL

Principal resolver

Authentication flow

Automatic security protocol detection (default behavior)

Re-authentication support

Conduktor in production

Deploy Console

Deploy Gateway

Initial setup

​Security protocol

​PLAINTEXT

​SSL

​mTLS

​SASL_PLAINTEXT

​Plain

​OAuthbearer

​SASL_SSL

​Plain

​OAuthbearer

​DELEGATED_SASL_PLAINTEXT

​DELEGATED_SASL_SSL

​Principal resolver

​Authentication flow

​Automatic security protocol detection (default behavior)

​Re-authentication support

​Related resources

Security protocol

PLAINTEXT

SSL

mTLS

SASL_PLAINTEXT

Plain

OAuthbearer

SASL_SSL

Plain

OAuthbearer

DELEGATED_SASL_PLAINTEXT

DELEGATED_SASL_SSL

Principal resolver

Authentication flow

Automatic security protocol detection (default behavior)

Re-authentication support

Related resources