Skip to main content

Release date: 2025-05-14

Breaking changes​

1. Gateway service accounts are now always required, when using PLAIN tokens​

You're impacted if​
  • your Gateway was not previously configured with the environment variable GATEWAY_USER_POOL_SERVICE_ACCOUNT_REQUIRED=true
  • and your clients are connecting using PLAIN tokens without having a corresponding local service account already created.

Note: Customers using either mTLS or DELEGATED security protocol are unaffected.

Do you have to do anything?​
  • You must create any missing local service accounts that your tokens rely on.
  • You can do this using the following command, adjusting your admin API credentials, host and name as appropriate
curl -X PUT -u admin:conduktor http://localhost:8888/gateway/v2/service-account \
        -H 'accept: application/json' \
        -d '{"kind": "GatewayServiceAccount", "apiVersion": "gateway/v2", "metadata": { "name": "admin", "vCluster": "passthrough"  }, "spec": { "type": "LOCAL" }}'

Find out about creating service accounts and ACLs.

Why did we make this change?​

Previously, PLAIN tokens could be issued to connect to Gateway without having to create the service account they are linked to. This could be configured to require that the service account exists using the environment variable GATEWAY_USER_POOL_SERVICE_ACCOUNT_REQUIRED.

This change improves security and consistency by enforcing that all PLAIN tokens must correspond to a pre-existing local service account. The GATEWAY_USER_POOL_SERVICE_ACCOUNT_REQUIRED variable is now deprecated and will behave as if it was set to true.

This enforces best practises that were previously only encouraged, meaning all tokens must have their service account already created on Gateway before they're allowed to connect.

We expect most customers to be unaffected as this setup is actively discouraged in the onboarding experience, as we recommend creating the service account before creating tokens.

2. Local service account token signing key is now mandatory​

You're impacted if:​
  • your Gateway security protocol (for the client connection to Gateway) is SASL_SSL or SASL_PLAINTEXT
  • and GATEWAY_USER_POOL_SECRET_KEY wasn't already set
Do you have to do anything?​
  • Yes. Set GATEWAY_USER_POOL_SECRET_KEY. We recommend using the following command line to generate the hash:
openssl rand -base64 32
Why did we make this change?​

Previously, when we signed the tokens for the local service accounts, we used a key that's set to a default value. The issue with that is that anybody who knows that default value is able to create their own tokens and connect to Gateway, if you've not changed the key.

To prevent this, we now ask you to set the key and store it safely, so that nobody unauthorized could create identities. Find out more about managing service accounts.

New features​

Enhanced Confluent Cloud authentication with service account mapping​

When using Confluent Cloud with delegated authentication, Gateway now supports automatically resolving API keys to their associated service account. This feature addresses key limitations of the previous approach:

  • Improved Interceptor targeting: Interceptors can now target service accounts directly
  • Enhanced Chargeback capabilities: Usage tracking by service account instead of API key
  • Elimination of manual mappings: Removes the need for administrators to maintain user mappings

Find out more about Gateway principal resolver for Confluent Cloud

Dynamic header Injection from record payloads​

The header injection Interceptor has been enhanced to support deriving header values directly from record payloads.

This powerful feature allows you to extract:

  • the entire record key or value and inject it as a header
  • specific fields from record keys or values and inject them as headers

You can now reference record fields using mustache syntax:

{
  "config": {
    "topic": "topic.*",
    "headers": {
      "X-CLIENT_IP": "{{userIp}} testing",
      "X-USER-ID": "{{record.key.id}}",
      "X-USER-EMAIL": "{{record.value.email}}"
    },
    "overrideIfExists": true
  }
}

This feature supports:

  • Extracting values from JSON, AVRO, PROTOBUF serialized records
  • Accessing record fields using dot notation
  • Referencing the entire key or value payload
  • Using mustache syntax for dynamic header values

Fixes​

HashiCorp Vault token refresh resilience​

Fixed a problem where Gateway would stop scheduling HashiCorp Vault token refreshes after encountering an error during the refresh process. Previously, if Gateway attempted to refresh its Vault token during a Vault outage, it would fail to recover even after Vault became available again, requiring a Gateway restart.

With this fix, Gateway will now:

  • Continue scheduling token refreshes on the regular interval
  • Automatically recover once Vault becomes available again