Configure Gateway external connections

An external connection is a named, reusable declaration of one external system, made when Gateway starts. Interceptors and topic views then reference it by name, instead of each carrying its own copy of the address and credentials. For topic views this is the only way to configure a schema registry. For Interceptors, prefer an external connection when several resources use the same registry: the address and credentials live in one place instead of being repeated in every Interceptor, so rotating a credential or moving a registry is a single edit. Inline configuration keeps working and is not deprecated.

Declare a connection

Declare each connection with environment variables that follow this pattern:

GATEWAY_EXTERNAL_CONNECTION_<NAME>_CONFIG_<PROPERTY>

<NAME> is a label you choose, and is how a resource references the connection. <PROPERTY> is one of the properties the connection’s type accepts.

Connection names have to start with a letter and can contain letters, numbers and underscores, so DEFAULT_SR is a valid name. A name can’t contain _CONFIG_, because that’s the delimiter between the name and the property. Gateway rejects such a variable at startup rather than guessing where the name ends. Names are case-insensitive and Gateway stores them in upper case, so default_sr and DEFAULT_SR are the same connection. We recommend you declare them in upper case to match the variable.

Every connection needs a TYPE, which selects the system it connects to:

`TYPE`	System	Properties
`CONFLUENT_SCHEMA_REGISTRY`	Confluent Schema Registry and compatible registries, including Redpanda Schema Registry	Confluent-like schema registries
`AWS_SCHEMA_REGISTRY`	AWS Glue Schema Registry	AWS Glue schema registries
`HASHICORP_VAULT`	HashiCorp Vault, for encryption or tokenization	HashiCorp Vault
`AWS_KMS`	AWS Key Management Service, for encryption keys	AWS KMS
`AZURE_KMS`	Azure Key Vault, for encryption keys	Azure Key Vault
`GCP_KMS`	Google Cloud Key Management Service, for encryption keys	Google Cloud KMS
`FORTANIX_KMS`	Fortanix Data Security Manager, for encryption keys	Fortanix DSM

Every connection follows the same shape. This one is a Confluent-like schema registry named DEFAULT_SR, which needs only a URL:

GATEWAY_EXTERNAL_CONNECTION_DEFAULT_SR_CONFIG_TYPE=CONFLUENT_SCHEMA_REGISTRY
GATEWAY_EXTERNAL_CONNECTION_DEFAULT_SR_CONFIG_SCHEMA_REGISTRY_URL=http://schema-registry:8081

Gateway rejects an unrecognized property at startup, naming the variable and listing the properties the connection’s type accepts, so a typo never becomes a silently ignored setting.

Reference a connection

A resource reaches a connection through a field in its own configuration:

Resource	Field
Interceptors that read schemas — data security and data quality	`schemaRegistryConnectionName`
Topic views	`spec.schemaRegistryConnectionName`
Encryption Interceptors	`kmsConnectionName`

Set the field to the connection’s <NAME>. The schema registry connection declared above is named DEFAULT_SR, so an Interceptor or topic view reaches it with:

"schemaRegistryConnectionName": "DEFAULT_SR"

Gateway checks the name when you create or update the resource, and rejects an unknown one with 400 Bad Request. Remove a connection that a resource already names and the resource stays saved and visible through the API, but stops serving traffic. An Interceptor can name a schema registry connection, or configure a registry inline in its own schemaRegistryConfig. Gateway rejects a configuration that sets both rather than silently picking one.

Connect to a schema registry

Gateway needs a schema registry to decode Avro, Protobuf and JSON-Schema records. Both Interceptors and topic views can reference a schema registry connection. Gateway contacts the registry at startup and fails to start if it can’t be reached — see what happens at startup for the timeout, the permissions the connection needs and what the log shows.

Confluent-like schema registries

Set TYPE to CONFLUENT_SCHEMA_REGISTRY for Confluent Schema Registry and compatible registries, including Redpanda Schema Registry:

GATEWAY_EXTERNAL_CONNECTION_DEFAULT_SR_CONFIG_TYPE=CONFLUENT_SCHEMA_REGISTRY
GATEWAY_EXTERNAL_CONNECTION_DEFAULT_SR_CONFIG_SCHEMA_REGISTRY_URL=http://schema-registry:8081

For every property this type accepts, see the environment variables reference. To reach a registry that needs authentication, pass the registry client’s own properties as additional client properties.

Don’t put credentials in SCHEMA_REGISTRY_URL. Gateway rejects a URL carrying user information before an @ and names the connection, so pass them as additional client properties instead.

AWS Glue schema registries

Set TYPE to AWS_SCHEMA_REGISTRY for AWS Glue Schema Registry:

GATEWAY_EXTERNAL_CONNECTION_PROD_SR_CONFIG_TYPE=AWS_SCHEMA_REGISTRY
GATEWAY_EXTERNAL_CONNECTION_PROD_SR_CONFIG_REGION=us-east-1
GATEWAY_EXTERNAL_CONNECTION_PROD_SR_CONFIG_BASIC_CREDENTIALS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
GATEWAY_EXTERNAL_CONNECTION_PROD_SR_CONFIG_BASIC_CREDENTIALS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

For every property this type accepts, see the environment variables reference. Leave every BASIC_CREDENTIALS_ property unset and Gateway falls back to the AWS SDK’s default credentials provider, which searches environment variables, Java system properties, the shared credentials and config files, and container or instance IAM roles. See how the AWS SDK resolves default credentials.

Pass additional client properties

A schema registry connection also accepts any property its registry’s own client understands. Gateway doesn’t interpret these properties. It collects them and hands the map to the client, so a key the client doesn’t recognize passes startup rather than failing it. Use indexed entries, where each value is a key=value pair split at the first =:

GATEWAY_EXTERNAL_CONNECTION_DEFAULT_SR_CONFIG_0=basic.auth.credentials.source=USER_INFO
GATEWAY_EXTERNAL_CONNECTION_DEFAULT_SR_CONFIG_1=basic.auth.user.info=user:password

Or pass a JSON object, which suits keys containing = and migration from existing JSON configuration:

GATEWAY_EXTERNAL_CONNECTION_DEFAULT_SR_CONFIG_JSON={"basic.auth.credentials.source":"USER_INFO","basic.auth.user.info":"user:password"}

Both formats work together, under two rules:

Indexed entries win. An indexed entry overrides the same key in the JSON object, so you can patch one value without rewriting the object.
Two indexed entries can’t share a key. There’s no patch order between them, so Gateway rejects the pair and names the key.

A client property can address the same setting as a typed one — _CONFIG_0=schema.registry.url=… beside _CONFIG_SCHEMA_REGISTRY_URL, for example. Gateway doesn’t check for the overlap, and which of the two it connects with is left to the registry’s client. Which keys to use depends on the registry:

Connection type	Keys are	Reference
`CONFLUENT_SCHEMA_REGISTRY`	Confluent Schema Registry client configuration. This is also how the connection authenticates, since it has no typed credential properties: use `basic.auth.credentials.source` and `basic.auth.user.info`, as above	Schema Registry security
`AWS_SCHEMA_REGISTRY`	AWS Glue Schema Registry serde configuration, merged over the typed properties. Credentials come from the `BASIC_CREDENTIALS_` properties or the AWS SDK’s default chain, so these keys cover other client settings	AWS Glue Schema Registry library

Connect to a KMS

Gateway encrypts data in Kafka records with keys held in a key management service. An external connection holds the provider’s address, credentials and account details, so an Interceptor’s keyId contains the provider-specific identifier described below rather than a full provider URI. When it validates the Interceptor configuration, Gateway rejects any keyId that starts with a supported KMS URI scheme, such as azure-kms://. External connections support HashiCorp Vault, AWS KMS, Azure Key Vault, Google Cloud KMS and Fortanix DSM. You can also configure these providers inline in an Interceptor’s kmsConfig. In-memory KMS and Gateway KMS remain inline-only; see choose your KMS provider. An Interceptor can also use a KMS connection for crypto shredding. The connection holds the master key, and Gateway stores a separate key for each record.

HashiCorp Vault

Set TYPE to HASHICORP_VAULT. This example authenticates with a token, one of the auth methods covered below:

GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_TYPE=HASHICORP_VAULT
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_URI=https://vault.internal:8200
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_ENGINE_TYPE=TRANSIT
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_ENGINE_MOUNT=transit
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TYPE=TOKEN
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TOKEN=hvs.CAESIExampleToken

If the engine and the auth method are in a Vault Enterprise namespace, set NAMESPACE too. For every property a Vault connection accepts, including mutual TLS and connection retry, see the environment variables reference.

Don’t put credentials in URI. Gateway rejects a URI carrying user information before an @ and names the connection, so authenticate with AUTH_TYPE and its credentials instead.

Authenticate with a token

Set AUTH_TYPE to TOKEN and AUTH_TOKEN to the Vault token Gateway authenticates with:

GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TYPE=TOKEN
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TOKEN=hvs.CAESIExampleToken

For every property this method accepts, see the environment variables reference.

Gateway doesn’t renew a token you supply — with AUTH_TYPE set to TOKEN it never calls Vault’s renew endpoint, so the token stays in use until its TTL expires, and recovering means replacing the variable and restarting. AppRole and username/password avoid that: Vault issues a short-lived token and Gateway renews it in the background. If you do use a token, give it a TTL that outlives your deployment window, or keep it fresh outside Gateway. See Vault’s production hardening guidance .

Authenticate with AppRole

Set AUTH_TYPE to APP_ROLE and pass the role ID and secret ID. Vault exchanges them for a short-lived token, which Gateway renews in the background:

GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TYPE=APP_ROLE
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_ROLE_ID=59d6d1ca-47bb-4e7e-a40b-8be3bc5a0ba8
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_SECRET_ID=84896a0c-1347-aa90-a4f6-aca8b7558780

For every property this method accepts, including AUTH_MOUNT when you mounted it somewhere other than approle, see the environment variables reference.

Authenticate with a username and password

Set AUTH_TYPE to USERNAME_PASSWORD and pass the userpass login. Vault exchanges it for a short-lived token, which Gateway renews in the background:

GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TYPE=USERNAME_PASSWORD
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_USERNAME=gateway
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_PASSWORD=s3cr3t

For every property this method accepts, including AUTH_MOUNT when you mounted it somewhere other than userpass, see the environment variables reference.

Authenticate with JWT

Set AUTH_TYPE to JWT and pass the Vault role, a signed JWT and the JWT auth method’s mount path. Vault verifies the JWT and returns a short-lived token, which Gateway renews in the background:

GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TYPE=JWT
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_ROLE=gateway
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_JWT=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_MOUNT=jwt

AUTH_MOUNT is required here, unlike the other methods: Gateway builds the JWT login path from it, so there’s no default. For every property this method accepts, see the environment variables reference.

Authenticate with LDAP

Set AUTH_TYPE to LDAP and pass the LDAP login. Vault checks it against the directory and returns a short-lived token, which Gateway renews in the background:

GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TYPE=LDAP
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_USERNAME=gateway
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_PASSWORD=s3cr3t

For every property this method accepts, including AUTH_MOUNT when you mounted it somewhere other than ldap, see the environment variables reference.

Authenticate with GitHub

Set AUTH_TYPE to GITHUB and AUTH_TOKEN to a GitHub token. Vault exchanges it for a short-lived token, which Gateway renews in the background. Gateway can run anywhere, since the token is a static credential:

GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TYPE=GITHUB
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TOKEN=ghp_ExampleToken

For every property this method accepts, including AUTH_MOUNT when you mounted it somewhere other than github, see the environment variables reference.

Authenticate with Kubernetes

Set AUTH_TYPE to KUBERNETES and AUTH_ROLE to the Vault role. Gateway reads the pod’s service account token and Vault exchanges it for a short-lived token, which Gateway renews in the background. Gateway has to run inside the target cluster, since it reads the token the cluster mounts into the pod:

GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TYPE=KUBERNETES
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_ROLE=gateway

Gateway reads the token from /var/run/secrets/kubernetes.io/serviceaccount/token by default. For every property this method accepts, including AUTH_TOKEN_PATH when the token is elsewhere, see the environment variables reference.

Authenticate with GCP

Set AUTH_TYPE to GCP, AUTH_ROLE to the Vault role and AUTH_JWT to a signed Google-issued JWT. Vault verifies it and returns a short-lived token, which Gateway renews in the background. Gateway can run anywhere, since it forwards a JWT minted elsewhere. Mint the JWT close to startup, as Vault rejects one older than 15 minutes:

GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TYPE=GCP
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_ROLE=gateway
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_JWT=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

For every property this method accepts, see the environment variables reference.

Authenticate with AWS IAM

Set AUTH_TYPE to AWS_IAM and pass a pre-signed sts:GetCallerIdentity request: its URL, body and headers. Vault replays the request to AWS to confirm the caller, then returns a short-lived token, which Gateway renews in the background. Gateway can run anywhere, since it forwards a request signed elsewhere:

GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TYPE=AWS_IAM
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_IAM_REQUEST_URL=https://sts.amazonaws.com
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_IAM_REQUEST_BODY=Action=GetCallerIdentity&Version=2011-06-15
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_IAM_REQUEST_HEADERS={"Authorization":["AWS4-HMAC-SHA256..."]}

For every property this method accepts, including the optional AUTH_ROLE and AUTH_MOUNT, see the environment variables reference.

Authenticate with AWS EC2

Set AUTH_TYPE to AWS_EC2 and pass the EC2 instance identity document and its signature. Vault verifies them with AWS and returns a short-lived token, which Gateway renews in the background. Gateway has to run on an EC2 instance, since the identity document comes from the instance metadata service:

GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TYPE=AWS_EC2
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_IDENTITY=<base64 instance identity document>
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_SIGNATURE=<base64 signature>

For every property this method accepts, including the optional AUTH_ROLE, AUTH_NONCE and AUTH_MOUNT, see the environment variables reference.

Authenticate with AWS EC2 by PKCS7

Set AUTH_TYPE to AWS_EC2_PKCS7 and pass the PKCS7 signature of the EC2 instance identity document. Vault verifies it with AWS and returns a short-lived token, which Gateway renews in the background. Gateway has to run on an EC2 instance, since the signature comes from the instance metadata service:

GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_TYPE=AWS_EC2_PKCS7
GATEWAY_EXTERNAL_CONNECTION_PROD_VAULT_CONFIG_AUTH_PKCS7=<PKCS7 document>

For every property this method accepts, including the optional AUTH_ROLE, AUTH_NONCE and AUTH_MOUNT, see the environment variables reference.

Gateway configures these six methods the same way as any Vault auth method, but each one logs in against an identity provider our automated tests don’t cover. Validate your connection in a non-production environment before you use it in production.

Tokenize with the Transform Secrets Engine

The Transform Secrets Engine needs Vault Enterprise and has to be mounted at its default path, transform. The connection’s Vault identity needs the Transform policy. To tokenize through a connection, set ENGINE_TYPE to TRANSFORM and leave ENGINE_MOUNT unset:

GATEWAY_EXTERNAL_CONNECTION_PROD_TRANSFORM_CONFIG_TYPE=HASHICORP_VAULT
GATEWAY_EXTERNAL_CONNECTION_PROD_TRANSFORM_CONFIG_URI=https://vault.internal:8200
GATEWAY_EXTERNAL_CONNECTION_PROD_TRANSFORM_CONFIG_ENGINE_TYPE=TRANSFORM
GATEWAY_EXTERNAL_CONNECTION_PROD_TRANSFORM_CONFIG_AUTH_TYPE=TOKEN
GATEWAY_EXTERNAL_CONNECTION_PROD_TRANSFORM_CONFIG_AUTH_TOKEN=hvs.CAESIExampleToken

In the Interceptor, set kmsConnectionName to PROD_TRANSFORM and each keyId to a bare Transform role name, such as email. See how to configure tokenization. To cache tokens, see the environment variables reference.

AWS KMS

Set TYPE to AWS_KMS. A connection covers one AWS account in one region. This example authenticates with access keys, one of three credential types covered below:

GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_TYPE=AWS_KMS
GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_REGION=eu-west-1
GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_ACCOUNT_ID=123456789012
GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_CREDENTIALS_TYPE=BASIC
GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_CREDENTIALS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_CREDENTIALS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

For every property an AWS KMS connection accepts, see the environment variables reference. REGION and ACCOUNT_ID are both required, because Gateway builds each key’s full ARN from them — so an Interceptor names a key as a bare key id or alias/<name>, never an ARN. See how the ARN is built and what’s rejected. The connection needs kms:Encrypt and kms:Decrypt on every key it uses, allowed by the key policy and by the identity’s IAM policy.

Authenticate with access keys

Set CREDENTIALS_TYPE to BASIC and pass a long-lived access key pair:

GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_CREDENTIALS_TYPE=BASIC
GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_CREDENTIALS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_CREDENTIALS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

For every property this type accepts, see the environment variables reference.

Authenticate with temporary credentials

Set CREDENTIALS_TYPE to SESSION and pass the session token alongside the key pair. Gateway doesn’t refresh these, so they stop working when they expire:

GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_CREDENTIALS_TYPE=SESSION
GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_CREDENTIALS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE
GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_CREDENTIALS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_CREDENTIALS_SESSION_TOKEN=IQoJb3JpZ2luX2VjEXAMPLE

For every property this type accepts, see the environment variables reference.

Authenticate with the AWS default provider chain

Set CREDENTIALS_TYPE to DEFAULT and pass no credentials at all. Gateway uses the AWS SDK’s default provider chain, which searches the container or instance role, IAM Roles for Service Accounts, the shared credentials file and the AWS_ environment variables. This suits a Gateway that already runs with an AWS identity, and it’s the only type where the credentials rotate without a restart:

GATEWAY_EXTERNAL_CONNECTION_PROD_AWS_CONFIG_CREDENTIALS_TYPE=DEFAULT

See how the AWS SDK resolves default credentials .

Azure Key Vault

Set TYPE to AZURE_KMS. A connection covers one Azure Key Vault. This example authenticates with a client secret, one of three credential types covered below:

GATEWAY_EXTERNAL_CONNECTION_PROD_AZURE_CONFIG_TYPE=AZURE_KMS
GATEWAY_EXTERNAL_CONNECTION_PROD_AZURE_CONFIG_VAULT_URL=https://my-key-vault.vault.azure.net
GATEWAY_EXTERNAL_CONNECTION_PROD_AZURE_CONFIG_CREDENTIALS_TYPE=TOKEN
GATEWAY_EXTERNAL_CONNECTION_PROD_AZURE_CONFIG_CREDENTIALS_CLIENT_ID=00000000-0000-0000-0000-000000000000
GATEWAY_EXTERNAL_CONNECTION_PROD_AZURE_CONFIG_CREDENTIALS_TENANT_ID=11111111-1111-1111-1111-111111111111
GATEWAY_EXTERNAL_CONNECTION_PROD_AZURE_CONFIG_CREDENTIALS_CLIENT_SECRET=example-client-secret

Configure the connection with these properties:

Variable suffix	Description	Default
`VAULT_URL`	HTTPS URL of the Azure Key Vault. Can’t have a trailing slash	Required
`CREDENTIALS_TYPE`	Authentication method: `TOKEN`, `USERNAME_PASSWORD` or `DEFAULT`	Required
`RETRY_MAX_RETRIES`	Maximum number of retry attempts for a failed Key Vault request. Has to be positive	`3`
`RETRY_DELAY_MS`	Initial retry delay in milliseconds. Has to be positive and no greater than `RETRY_MAX_DELAY_MS`	`800`
`RETRY_MAX_DELAY_MS`	Maximum retry delay in milliseconds. Has to be positive	`8000`

VAULT_URL has to be an HTTPS URL with a host and no trailing slash. The connection owns this URL, so each Interceptor keyId is a bare key name rather than a path or name/version. Gateway resolves the latest version of the key. The identity needs get, encrypt and decrypt access to each key. If a key doesn’t exist, Gateway creates an RSA key, so the identity also needs create access.

Authenticate with a client secret

Set CREDENTIALS_TYPE to TOKEN and pass the application and tenant identifiers with the client secret, as shown above.

Variable suffix	Description	Default
`CREDENTIALS_CLIENT_ID`	Microsoft Entra application client ID	Required
`CREDENTIALS_TENANT_ID`	Microsoft Entra tenant ID	Required
`CREDENTIALS_CLIENT_SECRET`	Application client secret	Required

Authenticate with a username and password

Set CREDENTIALS_TYPE to USERNAME_PASSWORD and pass the application and tenant identifiers with the username and password:

GATEWAY_EXTERNAL_CONNECTION_PROD_AZURE_CONFIG_CREDENTIALS_TYPE=USERNAME_PASSWORD
GATEWAY_EXTERNAL_CONNECTION_PROD_AZURE_CONFIG_CREDENTIALS_CLIENT_ID=00000000-0000-0000-0000-000000000000
GATEWAY_EXTERNAL_CONNECTION_PROD_AZURE_CONFIG_CREDENTIALS_TENANT_ID=11111111-1111-1111-1111-111111111111
GATEWAY_EXTERNAL_CONNECTION_PROD_AZURE_CONFIG_CREDENTIALS_USERNAME=gateway@example.com
GATEWAY_EXTERNAL_CONNECTION_PROD_AZURE_CONFIG_CREDENTIALS_PASSWORD=example-password

Variable suffix	Description	Default
`CREDENTIALS_CLIENT_ID`	Microsoft Entra application client ID	Required
`CREDENTIALS_TENANT_ID`	Microsoft Entra tenant ID	Required
`CREDENTIALS_USERNAME`	Username	Required
`CREDENTIALS_PASSWORD`	Password	Required

Username and password authentication uses the Resource Owner Password Credentials flow. It can’t complete multifactor authentication (MFA) or satisfy a Conditional Access policy that requires MFA, and Microsoft recommends against using it. For production, use CREDENTIALS_TYPE=DEFAULT with a workload identity or managed identity instead. See Microsoft’s ROPC guidance .

Authenticate with the Azure default credential chain

Set CREDENTIALS_TYPE to DEFAULT and pass no credentials on the connection:

GATEWAY_EXTERNAL_CONNECTION_PROD_AZURE_CONFIG_CREDENTIALS_TYPE=DEFAULT

Gateway uses the Azure SDK’s default credential chain, which can resolve environment credentials, workload identity, managed identity and developer credentials. See how DefaultAzureCredential resolves credentials .

Google Cloud KMS

Set TYPE to GCP_KMS. A connection covers one key ring in one Google Cloud project and location:

GATEWAY_EXTERNAL_CONNECTION_PROD_GCP_CONFIG_TYPE=GCP_KMS
GATEWAY_EXTERNAL_CONNECTION_PROD_GCP_CONFIG_PROJECT=my-gcp-project
GATEWAY_EXTERNAL_CONNECTION_PROD_GCP_CONFIG_LOCATION=europe-west1
GATEWAY_EXTERNAL_CONNECTION_PROD_GCP_CONFIG_KEY_RING=gateway
GATEWAY_EXTERNAL_CONNECTION_PROD_GCP_CONFIG_SERVICE_ACCOUNT_CREDENTIALS_FILE_PATH=/etc/gateway/gcp-service-account.json

Configure the connection with these properties:

Variable suffix	Description	Default
`PROJECT`	Google Cloud project ID that owns the key ring	Required
`LOCATION`	Google Cloud location of the key ring, for example `europe-west1`	Required
`KEY_RING`	Name of the Cloud KMS key ring	Required
`SERVICE_ACCOUNT_CREDENTIALS_FILE_PATH`	Path to a readable service-account key file	Application Default Credentials
`ENDPOINT`	Root URL of a private or custom Cloud KMS endpoint. Has to end with `/`	`https://cloudkms.googleapis.com/`
`ENABLE_DETAILED_ERROR_LOGGING`	Whether Gateway logs complete Cloud KMS error responses	`false`

PROJECT, LOCATION and KEY_RING are required because Gateway builds the full Cloud KMS resource name from them. Each Interceptor keyId is the bare crypto key name, never a full projects/.../cryptoKeys/... resource path. The crypto key has to exist before Gateway uses it. The identity needs permission to encrypt and decrypt with each key. The predefined roles/cloudkms.cryptoKeyEncrypterDecrypter role provides these permissions.

Authenticate with Application Default Credentials

Leave SERVICE_ACCOUNT_CREDENTIALS_FILE_PATH unset. Gateway uses Application Default Credentials , including a GKE workload identity or the attached service account on Google Cloud infrastructure.

Authenticate with a service-account key file

Set SERVICE_ACCOUNT_CREDENTIALS_FILE_PATH to the path of a readable service-account JSON key file, as shown above. You can also set ENDPOINT to the root URL of a private Cloud KMS endpoint. The URL has to end with /. Leave it unset to use https://cloudkms.googleapis.com/.

ENABLE_DETAILED_ERROR_LOGGING=true logs complete Google Cloud KMS error responses, which can contain sensitive information. Leave it at its default of false unless you need the additional detail to diagnose a problem.

Fortanix DSM

Set TYPE to FORTANIX_KMS. This example authenticates to Fortanix Data Security Manager (DSM) with an API key, one of two credential types covered below:

GATEWAY_EXTERNAL_CONNECTION_PROD_FORTANIX_CONFIG_TYPE=FORTANIX_KMS
GATEWAY_EXTERNAL_CONNECTION_PROD_FORTANIX_CONFIG_BASE_PATH=https://apac.smartkey.io
GATEWAY_EXTERNAL_CONNECTION_PROD_FORTANIX_CONFIG_CREDENTIALS_TYPE=API_KEY
GATEWAY_EXTERNAL_CONNECTION_PROD_FORTANIX_CONFIG_CREDENTIALS_API_KEY=example-api-key

Configure the connection with these properties:

Variable suffix	Description	Default
`BASE_PATH`	URL of the Fortanix DSM endpoint	Required
`CREDENTIALS_TYPE`	Authentication method: `API_KEY` or `USERNAME_PASSWORD`	Required

The connection owns the DSM base URL, so each Interceptor keyId is a bare security-object name. Gateway searches security objects by that name and uses the first match, so keep names unique. The existing object has to be an AES key. If no object matches, Gateway generates a 256-bit AES security object. Gateway sends AES-CBC encrypt and decrypt requests. It doesn’t set permissions on a generated object, so the Fortanix application has to be allowed to search for and generate security objects, and to encrypt and decrypt with them.

Authenticate with an API key

Set CREDENTIALS_TYPE to API_KEY and pass the application API key, as shown above.

Variable suffix	Description	Default
`CREDENTIALS_API_KEY`	Fortanix application API key	Required

Authenticate with a username and password

Set CREDENTIALS_TYPE to USERNAME_PASSWORD and pass the Fortanix username and password:

GATEWAY_EXTERNAL_CONNECTION_PROD_FORTANIX_CONFIG_CREDENTIALS_TYPE=USERNAME_PASSWORD
GATEWAY_EXTERNAL_CONNECTION_PROD_FORTANIX_CONFIG_CREDENTIALS_USERNAME=gateway
GATEWAY_EXTERNAL_CONNECTION_PROD_FORTANIX_CONFIG_CREDENTIALS_PASSWORD=example-password

Variable suffix	Description	Default
`CREDENTIALS_USERNAME`	Fortanix username	Required
`CREDENTIALS_PASSWORD`	Fortanix password	Required

What happens at startup

Connections are read once, when Gateway starts, and this is true of every connection type:

Configuration is validated. An unrecognized property, or a malformed value such as a JSON object of additional client properties, fails startup and names the variable.
Connections load before persisted resources. Interceptors and topic views are activated from storage after the connections exist, so their names resolve.
A missing connection doesn’t stop Gateway. If an Interceptor or topic view names a connection that’s no longer declared, that resource stays saved and visible through the API but doesn’t activate, while everything else starts normally. Gateway logs an error naming the missing connection — check the startup log.
Secrets are masked in the startup log. Additional client property values are masked whichever format set them, and their keys stay visible.

Whether Gateway also contacts the external system at startup depends on the connection type:

Connection type	Contacted at startup
Schema registry — `CONFLUENT_SCHEMA_REGISTRY`, `AWS_SCHEMA_REGISTRY`	Yes. Gateway fails to start if a registry can’t be reached.
KMS — `HASHICORP_VAULT`, `AWS_KMS`, `AZURE_KMS`, `GCP_KMS`, `FORTANIX_KMS`	No. Gateway validates the connection’s properties but doesn’t contact the provider.

Gateway checks schema registry connections in parallel and waits for all of them to finish, so one broken connection doesn’t hide another — you see every failure in one startup attempt. Each attempt is bounded by GATEWAY_EXTERNAL_CONNECTIONS_INIT_TIMEOUT_SECONDS, which defaults to 30 seconds and caps at 300. See the variable reference. The check, and the permission it needs, differ by registry:

Confluent-like — Gateway lists the registry’s subjects, so the connection needs permission to list them even if your Interceptors only read schemas by ID.
AWS Glue — Gateway requests a schema version that deliberately doesn’t exist, so the connection needs glue:GetSchemaVersion and a not-found answer counts as success.

A KMS connection is established when an Interceptor that names it loads, so a wrong credential or an unreachable provider surfaces then rather than at boot, and Gateway starts normally either way. Check the Interceptor’s own status after deploying it, not the startup log.

Verify the configuration

Gateway logs each schema registry connection’s startup check. Look for one line per connection:

Schema registry connection DEFAULT_SR initialized in 84ms

A failure names the connection and the cause, and Gateway then reports how many failed before it stops:

Schema registry connection PROD_SR failed: ...
1 of 2 schema registry connections failed: PROD_SR

With none declared, Gateway logs No schema registry connections configured and starts normally. Gateway reports KMS connections separately, one line each:

Loaded 6 KMS connection(s):
  PROD_VAULT [HASHICORP_VAULT] engine=TRANSIT mount=transit uri=https://vault.internal:8200
  PROD_TRANSFORM [HASHICORP_VAULT] engine=TRANSFORM uri=https://vault.internal:8200
  PROD_AWS [AWS_KMS] region=eu-west-1 accountId=123456789012 credentials=BASIC keyUri=aws-kms://arn:aws:kms:eu-west-1:123456789012:<keyId>
  PROD_AZURE [AZURE_KMS] vaultUrl=https://my-key-vault.vault.azure.net credentials=DEFAULT
  PROD_GCP [GCP_KMS] project=my-gcp-project location=europe-west1 keyRing=gateway credentials=default
  PROD_FORTANIX [FORTANIX_KMS] basePath=https://apac.smartkey.io credentials=API_KEY

With none declared, that becomes No KMS connections configured. The summary names each credential method but never prints a secret value.

Current limitations

Connections are read and checked once, at startup. Changing one takes a restart. Gateway doesn’t monitor a system that becomes unreachable afterwards, so that failure surfaces on traffic needing an uncached schema.
A schema-backed topic view has to use SELECT *. A WHERE clause is still allowed. See read schema-encoded topics.
Gateway doesn’t contact a KMS at startup. It validates the connection’s properties, so a wrong credential or an unreachable provider surfaces when an Interceptor that names it loads, not at boot.
An Interceptor that names a removed connection stops applying, rather than failing. It stays saved and visible through the API, but after a restart the traffic it covered passes through unprocessed. An upcoming release will reject that traffic instead.
There’s no API that lists configured connections. Use the startup log to confirm what Gateway loaded.

​Declare a connection

​Reference a connection

​Connect to a schema registry

​Confluent-like schema registries

​AWS Glue schema registries

​Pass additional client properties

​Connect to a KMS

​HashiCorp Vault

​Authenticate with a token

​Authenticate with AppRole

​Authenticate with a username and password

​Authenticate with JWT

​Authenticate with LDAP

​Authenticate with GitHub

​Authenticate with Kubernetes

​Authenticate with GCP

​Authenticate with AWS IAM

​Authenticate with AWS EC2

​Authenticate with AWS EC2 by PKCS7

​Tokenize with the Transform Secrets Engine

​AWS KMS

​Authenticate with access keys

​Authenticate with temporary credentials

​Authenticate with the AWS default provider chain

​Azure Key Vault

​Authenticate with a client secret

​Authenticate with a username and password

​Authenticate with the Azure default credential chain

​Google Cloud KMS

​Authenticate with Application Default Credentials

​Authenticate with a service-account key file

​Fortanix DSM

​Authenticate with an API key

​Authenticate with a username and password

​What happens at startup

​Verify the configuration

​Current limitations

​Related resources

Declare a connection

Reference a connection

Connect to a schema registry

Confluent-like schema registries

AWS Glue schema registries

Pass additional client properties

Connect to a KMS

HashiCorp Vault

Authenticate with a token

Authenticate with AppRole

Authenticate with a username and password

Authenticate with JWT

Authenticate with LDAP

Authenticate with GitHub

Authenticate with Kubernetes

Authenticate with GCP

Authenticate with AWS IAM

Authenticate with AWS EC2

Authenticate with AWS EC2 by PKCS7

Tokenize with the Transform Secrets Engine

AWS KMS

Authenticate with access keys

Authenticate with temporary credentials

Authenticate with the AWS default provider chain

Azure Key Vault

Authenticate with a client secret

Authenticate with a username and password

Authenticate with the Azure default credential chain

Google Cloud KMS

Authenticate with Application Default Credentials

Authenticate with a service-account key file

Fortanix DSM

Authenticate with an API key

Authenticate with a username and password

What happens at startup

Verify the configuration

Current limitations

Related resources