Conduktor Schema Registry Proxy environment variables reference

Reference for Conduktor Schema Registry Proxy environment variables: license, client authentication, authorization modes, Schema Registry backend, Kafka connection and observability.

Environment variables for configuring Conduktor Schema Registry Proxy (SRP). For ready-to-adapt deployment examples, see Schema Registry Proxy configuration examples.

SRP has three separate connections, each authenticated and secured independently. Keep them apart when configuring the proxy:

1. Clients to SRP: how your applications authenticate to the proxy (client authentication) and whether the proxy endpoint serves HTTPS.
2. SRP to Schema Registry: the proxy’s own credentials for the backend registry (Schema Registry backend connection). Client credentials are never forwarded to the backend.
3. SRP to Kafka: the proxy’s connection to the backing Kafka cluster (Kafka connection), used by the reactive and topic-acl authorization modes.

Core settings

These settings control the identity and clustering behavior of the SRP instance. The SCHEMA_REGISTRY_PROXY_APP_ID is how Console differentiates between multiple SRP deployments in your infrastructure. The clustering settings (CLUSTER_NODE_INDEX, CLUSTER_MAX_NODE_INDEX) enable high-availability deployments where multiple SRP instances work together to handle load and provide failover.

Environment Variable	Description	Default	Required
SCHEMA_REGISTRY_PROXY_APP_ID	Unique identifier for the SRP instance, used by Console for multi-instance differentiation	schema-registry-proxy	No
CLUSTER_NODE_INDEX	Node index in multi-node deployment (0-based)	0	No
CLUSTER_MAX_NODE_INDEX	Maximum node index in cluster deployment	0	No
PORT	HTTP server listening port	8080	No
JAVALIN_DEV_LOGGING_ENABLED	Enable detailed HTTP request logging (WARNING: logs sensitive headers; never enable in production)	false	No

License

SRP requires a Conduktor Scale or Gateway license and refuses to start without a valid one. The license is checked once, at startup — a proxy that is already running keeps serving after its license expires, but the next restart fails. The license expiry date is exported as the license_expiry_timestamp_seconds Prometheus metric (Unix timestamp; not exported for licenses without an expiry date), so you can alert before a restart would fail.

Environment Variable	Description	Default	Required
CDK_LICENSE	Conduktor Scale or Gateway license token	-	Yes

Client authentication (clients to SRP)

Determines how SRP validates the identity of clients making requests. AUTH_PROVIDER is required and has no default: SRP refuses to start until it is set.

Environment Variable	Description	Default	Options
AUTH_PROVIDER	Authentication provider type	-	jwt, basic

JWT authentication

Production-ready authentication that validates JSON Web Tokens (JWT) against an OAuth2/OIDC provider’s JWKS endpoint (for example Keycloak, Auth0 or Okta). The authenticated identity (the configured claim) is the service account name authorization checks run against.

Environment Variable	Description	Default	Required
JWT_JWKS_URL	JWKS endpoint URL for public key retrieval	-	Yes (for JWT)
JWT_VALIDATE_EXPIRATION	Validate token expiration	true	No
JWT_SUBJECT_CLAIM_NAME	JWT claim to extract as the identity (for example sub, client_id, preferred_username)	sub	No

HTTP Basic authentication

File-based username/password authentication, with no dependency on an external identity provider. Credentials are read from a JSON file mounted into the container and hot-reloaded on change, so you can rotate credentials without restarting the proxy. Passwords are bcrypt hashes; plaintext passwords are rejected unless explicitly allowed.

[
  { "user": "[e-mail]", "password": "$2a$12$...bcrypt hash..." },
  { "user": "[e-mail]", "password": "$2a$12$...bcrypt hash..." }
]

Environment Variable	Description	Default	Required
BASIC_AUTH_LOCATION	Path, inside the container, of the mounted credentials file. Has to be an absolute path — a relative one resolves against the process working directory and fails startup.	/etc/srp/basic-auth.json	No
BASIC_AUTH_RELOAD_INTERVAL	How often the credentials file is re-read. 0 reads the file at startup only.	30s	No
BASIC_AUTH_ALLOW_PLAINTEXT	Accept plaintext (non-bcrypt) passwords in the file. When allowed, they are still compared in constant time.	false	No

The file is validated at startup: with AUTH_PROVIDER=basic, the proxy refuses to start on a missing, unreadable or empty file, invalid JSON, a duplicate user, or a malformed hash — each with a message naming the file and the fix. Supported bcrypt variants are 2a, 2b and 2y, with a cost between 4 and 31 (the cost range is checked at load time, not on a live request).

Live reload replaces the credential set atomically: in-flight requests see either the old or the new set, never a half-applied one. A malformed or unreadable file is not applied and does not clear the credential set — the last good snapshot keeps serving and the next tick retries. Reload outcomes are exported as the basic_auth_credentials_reload_total{result="success|failure"} metric; alert on failure, since it means the file on disk and the credentials in force have drifted apart.

Performance: bcrypt verification is deliberately expensive — at cost 12 it would dominate the latency of every proxied call. To keep it out of the hot path, a verified username and password pair is remembered for two minutes (at most 1,024 entries; successes only; the password itself is never stored). Two consequences: a wrong password always pays the full bcrypt cost, so brute-force attempts stay expensive — and so does a workload that sends a different credential on every request. Deleting a user takes effect on the next reload regardless of the cache, because credentials are consulted before it. An unknown username fails in the same time as a wrong password, so response timing doesn’t reveal which usernames exist, and passwords longer than 72 bytes (the bcrypt maximum) are a plain 401, not a server error.

HTTPS for the proxy endpoint

Enables HTTPS between clients and SRP: encrypts schema data in transit, authenticates the server to clients and can optionally authenticate clients to the server (mutual TLS). Both JKS (Java KeyStore) and PEM certificate formats are supported.

Environment Variable	Description	Default	Required for SSL
SSL_SECURE_PORT	HTTPS listening port	-	Yes (if SSL enabled)
SSL_INSECURE_ENABLED	Maintain HTTP alongside HTTPS	-	Yes (if SSL enabled)

JKS keystore mode

Environment Variable	Description	Default	Required
SSL_KEYSTORE_PATH	Path to JKS keystore file	-	Yes (for JKS)
SSL_KEYSTORE_PASSWORD	Keystore password	-	Yes (for JKS)
SSL_KEY_PASSWORD	Private key password (if different from keystore)	-	No

PEM certificate mode

Environment Variable	Description	Default	Required
SSL_PEM_CERT_PATH	Path to PEM certificate file	-	Yes (for PEM)
SSL_PEM_KEY_PATH	Path to PEM private key file	-	Yes (for PEM)

mTLS (client certificates)

Environment Variable	Description	Default	Required
SSL_TRUSTSTORE_PATH	Path to truststore for client certificate validation	-	No
SSL_TRUSTSTORE_PASSWORD	Truststore password	-	No

Authorization

AUTHORIZATION_MODE selects how SRP decides whether an authenticated client may perform a schema operation. Every mode implements the same contract: schema registration requires Write on the subject, every other proxied endpoint requires Read, and a denied request returns HTTP 403. See authorization modes for how each mode works and when to use it.

• reactive (default): permissions managed in Conduktor Console via Self-service and distributed to SRP over Kafka.
• topic-acl (standalone): permissions derived from the Kafka topic ACLs already defined in the backing cluster.
• read-only (standalone): every authenticated read passes through, every write is rejected. No Kafka connection needed.

Environment Variable	Description	Default	Required
AUTHORIZATION_MODE	Authorization mode: reactive, topic-acl or read-only	reactive	No
AUTHORIZATION_SUPER_USERS	Semicolon-separated service account names that bypass all authorization checks, in any mode. Leave empty unless you need a break-glass identity.	(empty)	No
AUTHORIZATION_TOPIC_ACL_LOOKUP_TIMEOUT	topic-acl mode: timeout for ACL lookups against Kafka; a timed-out lookup denies the request	5s	No
AUTHORIZATION_TOPIC_ACL_CACHE_TTL	topic-acl mode: per-topic ACL cache TTL; 0s disables caching	500ms	No
AUTHORIZATION_SCHEMA_ID_SUBJECT_CACHE_TTL	Cache TTL for resolving which subjects hold a schema on GET /schemas/ids/{id}; negative results are never cached; 0s disables caching	5m	No
AUTHORIZATION_GUID_SUBJECT_CACHE_TTL	Cache TTL for GUID-to-subject resolution on GET /schemas/guids/{guid}; negative results are never cached; 0s disables caching	5m	No
AUTH_USE_REACTIVE_CONFIG	Deprecated — use AUTHORIZATION_MODE instead (true maps to reactive; AUTHORIZATION_MODE wins when both are set)	true	No

Schema Registry backend connection (SRP to Schema Registry)

Defines how SRP connects to the Confluent Schema Registry where schemas are stored. These are the proxy’s own credentials: SRP authenticates to the backend itself (Basic Auth, OAuth or mTLS) and never forwards client credentials upstream.

Backend selection

Environment Variable	Description	Default	Options
SCHEMA_REGISTRY_BACKEND_TYPE	Backend implementation type	confluent	confluent

Confluent Schema Registry connection

Environment Variable	Description	Default	Required
CONFLUENT_SCHEMA_REGISTRY_URL	Schema Registry base URL	http://localhost:8081	Yes

Basic authentication to Schema Registry

Environment Variable	Description	Default	Options
SCHEMA_REGISTRY_BASIC_AUTH_CREDENTIALS_SOURCE	Credentials source	NONE	NONE, USER_INFO, URL, SASL_INHERIT
SCHEMA_REGISTRY_BASIC_AUTH_USER_INFO	Username:password for USER_INFO source	-	For USER_INFO

Bearer/OAuth authentication to Schema Registry

Environment Variable	Description	Default	Options
SCHEMA_REGISTRY_BEARER_AUTH_CREDENTIALS_SOURCE	Credentials source	NONE	NONE, STATIC_TOKEN, OAUTHBEARER
SCHEMA_REGISTRY_BEARER_AUTH_TOKEN	Static bearer token	-	For STATIC_TOKEN
SCHEMA_REGISTRY_BEARER_AUTH_ISSUER_ENDPOINT_URL	OAuth token endpoint	-	For OAUTHBEARER
SCHEMA_REGISTRY_BEARER_AUTH_CLIENT_ID	OAuth client ID	-	For OAUTHBEARER
SCHEMA_REGISTRY_BEARER_AUTH_CLIENT_SECRET	OAuth client secret	-	For OAUTHBEARER
SCHEMA_REGISTRY_BEARER_AUTH_SCOPE	OAuth scope	-	No

TLS to Schema Registry

Environment Variable	Description	Default	Required
SCHEMA_REGISTRY_SSL_PROTOCOL	SSL protocol	-	No
SCHEMA_REGISTRY_SSL_TRUSTSTORE_LOCATION	Truststore for server validation	-	For HTTPS
SCHEMA_REGISTRY_SSL_TRUSTSTORE_PASSWORD	Truststore password	-	For HTTPS
SCHEMA_REGISTRY_SSL_TRUSTSTORE_TYPE	Truststore type	-	No
SCHEMA_REGISTRY_SSL_KEYSTORE_LOCATION	Keystore for client authentication (mTLS)	-	For mTLS
SCHEMA_REGISTRY_SSL_KEYSTORE_PASSWORD	Keystore password	-	For mTLS
SCHEMA_REGISTRY_SSL_KEYSTORE_TYPE	Keystore type	-	No
SCHEMA_REGISTRY_SSL_KEY_PASSWORD	Private key password	-	No
SCHEMA_REGISTRY_SSL_KEYSTORE_CERTIFICATE_ALIAS	Certificate alias in keystore	-	No
SCHEMA_REGISTRY_SSL_PROVIDER	Security provider	-	No
SCHEMA_REGISTRY_SSL_ENABLED_PROTOCOLS	Comma-separated enabled protocols	-	No
SCHEMA_REGISTRY_SSL_CIPHER_SUITES	Comma-separated cipher suites	-	No
SCHEMA_REGISTRY_SSL_ENDPOINT_IDENTIFICATION_ALGORITHM	Endpoint identification (https or empty)	-	No

Kafka connection (SRP to Kafka)

The proxy’s own connection to the backing Kafka cluster. Which parts you need depends on the authorization mode:

• reactive mode uses Kafka to receive permission updates from Console (_conduktor_srp_commands), publish heartbeats for Console discovery (_conduktor_srp_events) and keep multiple SRP instances in sync.
• topic-acl mode uses this connection to read topic ACLs through the Kafka Admin API.
• read-only mode needs no Kafka connection at all.

The security settings configure how SRP authenticates to your Kafka cluster (SASL, SSL, OAuth).

Connection

Environment Variable	Description	Default	Required
KAFKA_BOOTSTRAP_SERVERS	Kafka broker addresses (comma-separated)	-	Yes (reactive and topic-acl modes)
KAFKA_CLIENT_ID	Client ID prefix for Kafka connections	_conduktor_srp	No
KAFKA_ADDITIONAL_PROPERTIES	Additional Kafka client properties as JSON, for example {"request.timeout.ms": "30000"}	-	No

Console synchronization topics (reactive mode)

Environment Variable	Description	Default	Required
KAFKA_CONFIG_COMMAND_TOPIC	Topic for receiving permission commands from Console	_conduktor_srp_commands	No
KAFKA_CONFIG_COMMAND_REPLICATION_FACTOR	Replication factor for the command topic	3	No
KAFKA_CONFIG_COMMAND_CONSOLE_ID	Console instance identifier	console	No
KAFKA_CONFIG_APPLIED_TOPIC	Topic for publishing applied configuration events and heartbeats	_conduktor_srp_events	No
KAFKA_HEARTBEAT_ENABLED	Enable periodic heartbeat publishing for Console discovery	true	No
KAFKA_HEARTBEAT_INTERVAL	Heartbeat interval (HOCON duration format: 5m, 30m, 1h)	5m	No

Kafka security protocol

Environment Variable	Description	Default	Options
KAFKA_SECURITY_PROTOCOL	Security protocol for Kafka	PLAINTEXT	PLAINTEXT, SASL_PLAINTEXT, SASL_SSL, SSL

SASL configuration

Environment Variable	Description	Default	Options
KAFKA_SASL_MECHANISM	SASL authentication mechanism	-	PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, OAUTHBEARER, GSSAPI
KAFKA_SASL_JAAS_CONFIG	JAAS configuration string	-	Required for SASL
KAFKA_SASL_KERBEROS_SERVICE_NAME	Kerberos service name	-	Required for GSSAPI
KAFKA_SASL_LOGIN_CALLBACK_HANDLER_CLASS	OAuth login callback handler	-	For OAUTHBEARER. Only org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginCallbackHandler is supported.
KAFKA_SASL_CLIENT_CALLBACK_HANDLER_CLASS	OAuth client callback handler	-	For OAUTHBEARER

SASL/OAUTHBEARER configuration

Environment Variable	Description	Default	Required
KAFKA_SASL_OAUTHBEARER_TOKEN_ENDPOINT_URL	OAuth token endpoint	-	For OAUTHBEARER
KAFKA_SASL_OAUTHBEARER_CLIENT_ID	OAuth client ID	-	For OAUTHBEARER
KAFKA_SASL_OAUTHBEARER_CLIENT_SECRET	OAuth client secret	-	For OAUTHBEARER
KAFKA_SASL_OAUTHBEARER_SCOPE	OAuth scope	-	No
KAFKA_SASL_OAUTHBEARER_ALLOWED_URLS	Allowed OAuth endpoints (Kafka 4.0+)	-	No

Kafka TLS configuration

Environment Variable	Description	Default	Required
KAFKA_SSL_TRUSTSTORE_LOCATION	Truststore file path for server certificate validation	-	For SSL/SASL_SSL
KAFKA_SSL_TRUSTSTORE_PASSWORD	Truststore password	-	For SSL/SASL_SSL
KAFKA_SSL_TRUSTSTORE_TYPE	Truststore type	-	No
KAFKA_SSL_KEYSTORE_LOCATION	Keystore file path for client authentication (mTLS)	-	For mTLS
KAFKA_SSL_KEYSTORE_PASSWORD	Keystore password	-	For mTLS
KAFKA_SSL_KEYSTORE_TYPE	Keystore type	-	No
KAFKA_SSL_KEY_PASSWORD	Private key password	-	No
KAFKA_SSL_PROTOCOL	TLS protocol version	-	No
KAFKA_SSL_PROVIDER	Security provider	-	No
KAFKA_SSL_ENABLED_PROTOCOLS	Comma-separated list of TLS protocols enabled for the connection to the backing Kafka cluster (Kafka client property ssl.enabled.protocols). Only applies with SSL or SASL_SSL.	TLSv1.2,TLSv1.3 (Kafka client default)	No
KAFKA_SSL_CIPHER_SUITES	Comma-separated list of cipher suites	-	No
KAFKA_SSL_ENDPOINT_IDENTIFICATION_ALGORITHM	Endpoint identification algorithm (https or empty)	-	No

Observability

Enables monitoring and troubleshooting capabilities:

• OpenTelemetry: distributed tracing to track requests through the system, helping identify bottlenecks and failures
• Prometheus metrics: operational metrics (request counts, latencies, error rates) for monitoring and alerting
• Logging: structured JSON logs for debugging and audit trails

OpenTelemetry configuration

Environment Variable	Description	Default	Required
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP gRPC endpoint for traces, metrics, logs	-	No
OTEL_TRACES_ENABLED	Enable trace export	true	No
OTEL_METRICS_ENABLED	Enable metrics push to collector	true	No
OTEL_LOGS_ENABLED	Enable log export	true	No
OTEL_PROMETHEUS_PORT	Prometheus metrics scrape endpoint port	9464	No

Logging configuration

Environment Variable	Description	Default	Options
LOG_LEVEL	Application log level	INFO	DEBUG, INFO, WARN, ERROR