Configure Schema Registry Proxy - Conduktor Documentation

Core settings

These settings control the identity and clustering behavior of the SRP instance. The SCHEMA_REGISTRY_PROXY_APP_ID is crucial for Console to differentiate 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

Server Configuration

Defines the basic HTTP server settings. The PORT determines where SRP listens for incoming schema registry API requests from Kafka clients. The dev logging setting is primarily for troubleshooting but should never be enabled in production as it logs sensitive authentication headers.

Environment Variable	Description	Default	Required
`PORT`	HTTP server listening port	`8080`	No
`JAVALIN_DEV_LOGGING_ENABLED`	Enable detailed HTTP request logging (WARNING: logs sensitive headers)	`false`	No

SSL/TLS Configuration

Enables secure HTTPS communication between Kafka clients and SRP. This is critical in production environments to:

Encrypt schema data in transit
Authenticate the server to clients (via server certificates)
Optionally authenticate clients to the server (mTLS) for additional security

Condunkor SRP supports both JKS (Java KeyStore) and PEM certificate formats for flexibility

Server SSL Configuration

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 Configuration

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

Kafka Backend Configuration

Required for SRP’s reactive authorization model. SRP uses Kafka as its configuration backbone to synchronize with Conduktor Console. The security settings here configure how SRP authenticates to your Kafka cluster (SASL, SSL, OAuth, etc.).

Connection Settings

Environment Variable	Description	Default	Required
`KAFKA_BOOTSTRAP_SERVERS`	Kafka broker addresses (comma-separated)	`-`	Yes
`KAFKA_CLIENT_ID`	Client ID prefix for Kafka connections	`_conduktor_srp`	No

Kafka Security Configuration

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’ supported for RC release.
`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 SSL/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 enabled protocols	-	No
`KAFKA_SSL_CIPHER_SUITES`	Comma-separated list of cipher suites	-	No
`KAFKA_SSL_ENDPOINT_IDENTIFICATION_ALGORITHM`	Endpoint identification algorithm (`https` or empty)	-	No

Schema Registry Backend Configuration

Defines how SRP connects to the actual Confluent Schema Registry where schemas are stored. SRP acts as a proxy, so it needs to:

Know the Schema Registry URL to forward requests
Authenticate to the Schema Registry if it requires authentication (Basic Auth, OAuth, or mTLS)
Handle SSL/TLS connections if the Schema Registry uses HTTPS
Pass through the appropriate credentials while maintaining security

Backend Selection

Environment Variable	Description	Default	Options
`SCHEMA_REGISTRY_BACKEND_TYPE`	Backend implementation type	`confluent`	`confluent`

Confluent Schema Registry Configuration

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

Basic Authentication

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

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

Schema Registry SSL/TLS Configuration

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

Authentication Configuration

Determines how SRP validates the identity of users making requests. Two modes are supported:

In-memory: Simple token-based auth for development/testing
JWT: Production-ready authentication that validates JWT tokens against an OAuth provider’s JWKS endpoint

This ensures only authenticated users can access the schema registry through SRP.

Provider Selection

Environment Variable	Description	Default	Options
`AUTH_PROVIDER`	Authentication provider type	`in-memory`	`in-memory`, `jwt`

JWT Authentication Configuration

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 for subject extraction	`sub`	No

Authorization Configuration

Controls whether SRP uses static or dynamic permissions. When AUTH_USE_REACTIVE_CONFIG=true, SRP:

Consumes permission updates from Kafka in real-time
Stores permissions in memory for fast authorization checks
Integrates with Console’s self-service permission management

This is what enables the fine-grained access control that SRP provides on top of the schema registry.

Environment Variable	Description	Default	Required
`AUTH_USE_REACTIVE_CONFIG`	Enable Kafka-backed dynamic authorization	`true`	No

Observability Configuration

Enables monitoring and troubleshooting capabilities:

OpenTelemetry: Provides distributed tracing to track requests through the system, helping identify bottlenecks and failures
Prometheus metrics: Exposes 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`

Deployment Examples

Production Deployment with Full Security

version: "3.8"
services:
  schema-registry-proxy:
    image: conduktor/conduktor-schema-registry-proxy:0.1.0-rc1
    hostname: srp-prod-1
    environment:
      # Core Configuration
      SCHEMA_REGISTRY_PROXY_APP_ID: srp-prod-cluster
      PORT: "8080"

      # SSL/TLS Server Configuration
      SSL_KEYSTORE_PATH: /opt/srp/certs/server.jks
      SSL_KEYSTORE_PASSWORD: ${SSL_KEYSTORE_PASSWORD}
      SSL_TRUSTSTORE_PATH: /opt/srp/certs/truststore.jks
      SSL_TRUSTSTORE_PASSWORD: ${SSL_TRUSTSTORE_PASSWORD}
      SSL_SECURE_PORT: "8443"
      SSL_INSECURE_ENABLED: "false"

      # Kafka Configuration with SASL/SSL
      KAFKA_BOOTSTRAP_SERVERS: kafka1:9093,kafka2:9093,kafka3:9093
      KAFKA_SECURITY_PROTOCOL: SASL_SSL
      KAFKA_SASL_MECHANISM: SCRAM-SHA-512
      KAFKA_SASL_JAAS_CONFIG: 'org.apache.kafka.common.security.scram.ScramLoginModule required username="${KAFKA_USER}" password="${KAFKA_PASSWORD}";'
      KAFKA_SSL_TRUSTSTORE_LOCATION: /opt/srp/certs/kafka-truststore.jks
      KAFKA_SSL_TRUSTSTORE_PASSWORD: ${KAFKA_TRUSTSTORE_PASSWORD}

      # Schema Registry Backend with mTLS
      CONFLUENT_SCHEMA_REGISTRY_URL: <https://schema-registry:8082>
      SCHEMA_REGISTRY_SSL_TRUSTSTORE_LOCATION: /opt/srp/certs/sr-truststore.jks
      SCHEMA_REGISTRY_SSL_TRUSTSTORE_PASSWORD: ${SR_TRUSTSTORE_PASSWORD}
      SCHEMA_REGISTRY_SSL_KEYSTORE_LOCATION: /opt/srp/certs/sr-client.jks
      SCHEMA_REGISTRY_SSL_KEYSTORE_PASSWORD: ${SR_KEYSTORE_PASSWORD}

      # JWT Authentication
      AUTH_PROVIDER: jwt
      JWT_JWKS_URL: <https://auth.company.com/realms/production/protocol/openid-connect/certs>
      JWT_VALIDATE_EXPIRATION: "true"
      JWT_SUBJECT_CLAIM_NAME: preferred_username

      # Observability
      OTEL_EXPORTER_OTLP_ENDPOINT: <http://otel-collector:4317>
      OTEL_TRACES_ENABLED: "true"
      OTEL_METRICS_ENABLED: "true"
      LOG_LEVEL: INFO
    volumes:
      - ./certs:/opt/srp/certs:ro
    ports:
      - "8443:8443"
      - "9464:9464"
    deploy:
      replicas: 3
      resources:
        limits:
          memory: 2G
          cpus: "2"
        reservations:
          memory: 1G
          cpus: "1"

Multi-Node Deployment Configuration

For high availability deployments with multiple SRP instances:

version: "3.8"
services:
  schema-registry-proxy-1:
    image: conduktor/conduktor-schema-registry-proxy:0.1.0-rc1
    environment:
      SCHEMA_REGISTRY_PROXY_APP_ID: srp-cluster
      CLUSTER_NODE_INDEX: "0"
      CLUSTER_MAX_NODE_INDEX: "2"
      # ... other configuration ...

  schema-registry-proxy-2:
    image: conduktor/conduktor-schema-registry-proxy:0.1.0-rc1
    environment:
      SCHEMA_REGISTRY_PROXY_APP_ID: srp-cluster
      CLUSTER_NODE_INDEX: "1"
      CLUSTER_MAX_NODE_INDEX: "2"
      # ... other configuration ...

  schema-registry-proxy-3:
    image: conduktor/conduktor-schema-registry-proxy:0.1.0-rc1
    environment:
      SCHEMA_REGISTRY_PROXY_APP_ID: srp-cluster
      CLUSTER_NODE_INDEX: "2"
      CLUSTER_MAX_NODE_INDEX: "2"
      # ... other configuration ...

Security Configurations

Example: Confluent Cloud Integration

environment:
  # Kafka connection to Confluent Cloud
  KAFKA_BOOTSTRAP_SERVERS: <pkc-xxxxx.region.provider.confluent.cloud:9092>
  KAFKA_SECURITY_PROTOCOL: SASL_SSL
  KAFKA_SASL_MECHANISM: PLAIN
  KAFKA_SASL_JAAS_CONFIG: 'org.apache.kafka.common.security.plain.PlainLoginModule required username="${CONFLUENT_API_KEY}" password="${CONFLUENT_API_SECRET}";'

  # Schema Registry connection
  CONFLUENT_SCHEMA_REGISTRY_URL: <https://psrc-xxxxx.region.provider.confluent.cloud>
  SCHEMA_REGISTRY_BASIC_AUTH_CREDENTIALS_SOURCE: USER_INFO
  SCHEMA_REGISTRY_BASIC_AUTH_USER_INFO: "${SR_API_KEY}:${SR_API_SECRET}"

Example: Keycloak Integration

environment:
  AUTH_PROVIDER: jwt
  JWT_JWKS_URL: <https://keycloak.company.com/realms/production/protocol/openid-connect/certs>
  JWT_VALIDATE_EXPIRATION: "true"
  JWT_SUBJECT_CLAIM_NAME: preferred_username

Monitoring and Operations

Health Checks

The service exposes health endpoints for monitoring:

Health Check: GET https://host:PORT/health
Prometheus Metrics: GET https://host:PORT/metrics

Metrics

Key metrics exposed via Prometheus:

http_server_requests_total: Total HTTP requests
http_server_request_duration_seconds: Request latency histogram
kafka_consumer_lag: Consumer lag for configuration topics
schema_registry_backend_requests_total: Backend request counts
schema_registry_backend_request_duration_seconds: Backend request latency
srp_heartbeat_published_total: Count of published heartbeats
srp_permissions_updated_total: Count of permission updates received

Logging

Structured JSON logging with configurable levels:

environment:
  LOG_LEVEL: INFO # DEBUG for troubleshooting
  JAVALIN_DEV_LOGGING_ENABLED: "false" # Never enable in production

Distributed Tracing

When configured with OpenTelemetry, the service automatically creates spans for:

HTTP requests (parent spans)
Backend Schema Registry calls (child spans)
Kafka operations (consuming permissions, publishing heartbeats)
Authentication/authorization operations

Conduktor in production

Deploy Console

Deploy Schema Registry Proxy

Deploy Gateway

Initial setup

​Core settings

​Server Configuration

​SSL/TLS Configuration

​Server SSL Configuration

​JKS Keystore Mode

​PEM Certificate Mode

​mTLS Configuration

​Kafka Backend Configuration

​Connection Settings

​Kafka Security Configuration

​SASL Configuration

​SASL/OAUTHBEARER Configuration

​Kafka SSL/TLS Configuration

​Schema Registry Backend Configuration

​Backend Selection

​Confluent Schema Registry Configuration

​Basic Authentication

​Bearer/OAuth Authentication

​Schema Registry SSL/TLS Configuration

​Authentication Configuration

​Provider Selection

​JWT Authentication Configuration

​Authorization Configuration

​Observability Configuration

​OpenTelemetry Configuration

​Logging Configuration

​Deployment Examples

​Production Deployment with Full Security

​Multi-Node Deployment Configuration

​Security Configurations

​Example: Confluent Cloud Integration

​Example: Keycloak Integration

​Monitoring and Operations

​Health Checks

​Metrics

​Logging

​Distributed Tracing