Apache Kafka Connected System

Apache Kafka connected system configuration

Apache Kafka connected systems allow you to connect to Kafka brokers and share this connection configuration across multiple event consumers.

The following sections describe Kafka connected system properties. For properties that apply to all connected systems, see Connected System Object.

Connected system properties

Each Kafka connected system has the following properties.

Field	Description
Name	The name of the connected system. Use a name that will uniquely identify this connection to the external system.
Description	Supplemental information about the connected system that is displayed in the objects grid of some Designer views and when selecting the system in an integration object.
UUID	The Appian-generated identifier of the connected system object. This UUID is needed when updating the object using the connected system management API.
System Logo	An image document used to visually represent the external system or service being connected to. The logo is displayed in the integration designer and in the Process Modeler on integrations that connect to this system (using the Call Integration Smart Service). If no document is selected a default logo will be used instead.
Authentication	The type of authentication to use when connecting to the Kafka cluster. PLAINTEXT SASL SASL-SSL SSL
Bootstrap Servers	A comma-separated list of the broker hostnames and ports to be used when connecting to the cluster. To help ensure a stable connection, add at least two servers.
Data Source Shortcut	Apache Kafka connected systems cannot be used with integrations to build service-backed record types. This checkbox must not be selected.
Shortcut Display Name	The name of the data source shortcut option. This property only appears when Data Source Shortcut is selected.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Automating property updates

This object's properties can also be updated programmatically using the Update Connected System endpoint. This lets you change passwords, API keys, and other values without needing to sign in to Appian.

The following properties can be included in the JSON request body of the PATCH /connected-system/<UUID> call.

Authentication Type	SASL Mechanism	Available Properties
PLAINTEXT	Not applicable	bootstrapServers
SASL	PLAIN	bootstrapServers, username, password
SASL	SCRAM-SHA-256	bootstrapServers, username, password
SASL	SCRAM-SHA-512	bootstrapServers, username, password
SASL	OAuth 2.0: Client Credentials Grant	bootstrapServers, oauthTokenEndpoint, oauthClientId, oauthClientSecret, oauthScope, saslExtensions
SASL	OAuth 2.0: JWT Bearer Authorization Grant	bootstrapServers, oauthTokenEndpoint, oauthClientId, oauthPrivateKeyId, oauthPrivateKey, oauthScope, saslExtensions
SASL-SSL	PLAIN	bootstrapServers, username, password
SASL-SSL	SCRAM-SHA-256	bootstrapServers, username, password
SASL-SSL	SCRAM-SHA-512	bootstrapServers, username, password
SASL-SSL	OAuth 2.0: Client Credentials Grant	bootstrapServers, oauthTokenEndpoint, oauthClientId, oauthClientSecret, oauthScope, saslExtensions
SASL-SSL	OAuth 2.0: JWT Bearer Authorization Grant	bootstrapServers, oauthTokenEndpoint, oauthClientId, oauthPrivateKeyId, oauthPrivateKey, oauthScope, saslExtensions
SSL	Not applicable	bootstrapServers

Authentication types

The Apache Kafka connected system supports the following authentication methods:

• Plaintext
• SASL (PLAIN)
• SASL (SCRAM)
• SASL (OAuth: Client Credentials)
• SASL (OAuth: JWT Bearer)
• SASL-SSL (PLAIN)
• SASL-SSL (SCRAM)
• SASL-SSL (OAuth: Client Credentials)
• SASL-SSL (OAuth: JWT Bearer)
• SSL

Plaintext authentication properties

No additional properties are needed to use plaintext authentication.

SASL authentication properties

When you select SASL as the authentication type, a secondary SASL Mechanism dropdown appears. The available SASL mechanisms are:

• PLAIN: Authenticates with a username and password sent in plaintext to the broker.
• SCRAM-SHA-256: Authenticates using a challenge-response mechanism with SHA-256 hashing.
• SCRAM-SHA-512: Authenticates using a challenge-response mechanism with SHA-512 hashing.
• OAuth 2.0: Client Credentials Grant: Authenticates using an OAuth 2.0 client credentials flow with an external identity provider.
• OAuth 2.0: JWT Bearer Authorization Grant: Authenticates using a cryptographically signed JWT assertion (RFC 7523) instead of a static client secret. This mechanism eliminates the need to store or transmit shared secrets, enabling zero-secret machine-to-machine connectivity.

SASL with PLAIN or SCRAM mechanism

The following properties apply to the PLAIN, SCRAM-SHA-256, and SCRAM-SHA-512 mechanisms:

Field	Description
SASL Mechanism*	Required. The SASL method to use when connecting to the cluster. Select PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512.
Username*	Required. Username of the service account connecting to the cluster.
Password*	Required/Sensitive. The password of the service account. This value is masked to prevent unauthorized users from seeing it.

SASL with OAuth mechanism

Field	Description
SASL Mechanism*	Required. Select OAuth 2.0: Client Credentials Grant.
Token Endpoint*	Required. The token endpoint of the external OAuth provider used to authenticate with the Kafka broker.
Client ID*	Required. The client ID registered with the OAuth provider.
Client Secret*	Required/Sensitive. The client secret registered with the OAuth provider. This value is masked to prevent unauthorized users from seeing it.
Scope*	Optional. The scopes required by the OAuth provider.
SASL Extensions - Name	The identifier of a SASL extension defined by the broker. For example, Confluent Cloud brokers may require a logicalCluster and identityPoolId. To configure this option, see SASL Extensions for OAuth Authentication.
SASL Extensions - Value	The data to be sent for the SASL extension.

^* This value is included in an import customization file so that you can specify a different value for each environment. Sensitive values will not be exported in the import customization file and must be added manually. Required fields must have a value upon import or else import will fail. See Connected Systems Object import/export behavior for details.

SASL with JWT Bearer mechanism

The OAuth 2.0: JWT Bearer Authorization Grant mechanism uses cryptographic key pairs instead of a static client secret. Appian generates a signed JWT assertion using your RSA private key and exchanges it with the identity provider (IdP) for a short-lived access token. The access token authenticates the connection to the Kafka broker.

Field	Description
SASL Mechanism*	Required. Select OAuth 2.0: JWT Bearer Authorization Grant.
Token Endpoint*	Required. The token endpoint URL of the external identity provider used to request the access token.
Client ID*	Required. The client ID registered with the identity provider.
Private Key ID*	Required. The key identifier (kid) included in the JWT header. The identity provider uses this value to identify the correct public key for signature validation.
Private Key*	Required/Sensitive. The RSA private key used to sign the JWT assertion. Copy the full RSA private key string and paste it in this field. This value is masked to prevent unauthorized users from seeing it.
Scope	Optional. The scopes required by the OAuth provider.
SASL Extensions - Name	The identifier of a SASL extension defined by the broker. For example, Confluent Cloud brokers may require a logicalCluster and identityPoolId. To configure this option, see SASL Extensions for OAuth Authentication.
SASL Extensions - Value	The data to be sent for the SASL extension.

^* This value is included in an import customization file so that you can specify a different value for each environment. Sensitive values will not be exported in the import customization file and must be added manually. Required fields must have a value upon import or else import will fail. See Connected Systems Object import/export behavior for details.

SASL-SSL authentication properties

When you select SASL-SSL as the authentication type, a secondary SASL Mechanism dropdown appears. The available SASL mechanisms are:

• PLAIN: Authenticates with a username and password inside an encrypted SSL tunnel.
• SCRAM-SHA-256: Authenticates using a challenge-response mechanism with SHA-256 hashing inside an encrypted SSL tunnel.
• SCRAM-SHA-512: Authenticates using a challenge-response mechanism with SHA-512 hashing inside an encrypted SSL tunnel.
• OAuth 2.0: Client Credentials Grant: Authenticates using an OAuth 2.0 client credentials flow with an external identity provider, inside an encrypted SSL tunnel.
• OAuth 2.0: JWT Bearer Authorization Grant: Authenticates using a cryptographically signed JWT assertion (RFC 7523) instead of a static client secret, inside an encrypted SSL tunnel. This mechanism eliminates the need to store or transmit shared secrets, enabling zero-secret machine-to-machine connectivity.

The SASL-SSL authentication type combines SSL encryption with SASL credential authentication. The connected system uses the trusted server certificates available in the environment. If you need to use a self-signed or private CA certificate to connect to the Kafka broker, upload the certificate in the Admin Console.

SASL-SSL with PLAIN or SCRAM mechanism

The following properties apply to the PLAIN, SCRAM-SHA-256, and SCRAM-SHA-512 mechanisms:

Field	Description
SASL Mechanism*	Required. The SASL method to use when connecting to the cluster. Select PLAIN, SCRAM-SHA-256, or SCRAM-SHA-512.
Username*	Required. Username of the service account connecting to the cluster.
Password*	Required/Sensitive. The password of the service account. This value is masked to prevent unauthorized users from seeing it.
Enable two-way SSL*	If your Kafka broker is set up for client authentication, select this checkbox and upload the client certificates to the Admin Console.

SASL-SSL with OAuth mechanism

Field	Description
Enable two-way SSL	If your Kafka broker is set up for client authentication, select this checkbox and upload the client certificates to the Admin Console.
SASL Mechanism*	Required. Select OAuth 2.0: Client Credentials Grant.
Token Endpoint*	Required. The token endpoint of the external OAuth provider used to authenticate with the Kafka broker.
Client ID*	Required. The client ID registered with the OAuth provider.
Client Secret*	Required/Sensitive. The client secret registered with the OAuth provider. This value is masked to prevent unauthorized users from seeing it.
Scope*	Optional. The scopes required by the OAuth provider.
SASL Extensions - Name	The identifier of a SASL extension defined by the broker. For example, Confluent Cloud brokers may require a logicalCluster and identityPoolId. To configure this option, see SASL Extensions for OAuth Authentication.
SASL Extensions - Value	The data to be sent for the SASL extension.

^* This value is included in an import customization file so that you can specify a different value for each environment. Sensitive values will not be exported in the import customization file and must be added manually. Required fields must have a value upon import or else import will fail. See Connected Systems Object import/export behavior for details.

SASL-SSL with JWT Bearer mechanism

The OAuth 2.0: JWT Bearer Authorization Grant mechanism over SASL-SSL combines the zero-secret authentication of RFC 7523 with SSL/TLS encryption. Appian first establishes a secure SSL tunnel to the Kafka broker, then generates a signed JWT assertion using your RSA private key and exchanges it with the identity provider (IdP) for a short-lived access token.

Field	Description
Enable two-way SSL	If your Kafka broker is set up for client authentication, select this checkbox and upload the client certificates to the Admin Console.
SASL Mechanism*	Required. Select OAuth 2.0: JWT Bearer Authorization Grant.
Token Endpoint*	Required. The token endpoint URL of the external identity provider used to request the access token.
Client ID*	Required. The client ID registered with the identity provider.
Private Key ID*	Required. The key identifier (kid) included in the JWT header. The identity provider uses this value to identify the correct public key for signature validation.
Private Key*	Required/Sensitive. The RSA private key used to sign the JWT assertion. Copy the full RSA private key string and paste it in this field. This value is masked to prevent unauthorized users from seeing it.
Scope	Optional. The scopes required by the OAuth provider.
SASL Extensions - Name	The identifier of a SASL extension defined by the broker. For example, Confluent Cloud brokers may require a logicalCluster and identityPoolId. To configure this option, see SASL Extensions for OAuth Authentication.
SASL Extensions - Value	The data to be sent for the SASL extension.

^* This value is included in an import customization file so that you can specify a different value for each environment. Sensitive values will not be exported in the import customization file and must be added manually. Required fields must have a value upon import or else import will fail. See Connected Systems Object import/export behavior for details.

SSL authentication properties

If your environment uses self-signed certificates, upload the trusted server certificates to the Admin Console.

If your Kafka broker is set up for client authentication, select the Enable two-way SSL checkbox and upload the client certificates to the Admin Console.

SASL extensions for OAuth authentication

SASL extensions are static name-value pairs that Appian sends to the Kafka broker during the SASL/OAUTHBEARER handshake (after Appian retrieves the OAuth token from the identity provider). Configure SASL extensions when your Kafka broker requires additional routing or identity context to authorize an OAuth connection, such as a Confluent Cloud identity pool.

Add a SASL extension

The SASL Extensions grid appears when you select the OAuth 2.0: Client Credentials Grant or OAuth 2.0: JWT Bearer Authorization Grant for SASL or SASL-SSL authentication.

To add a SASL extension to an OAuth-authenticated Apache Kafka connected system:

1. In the SASL Extensions grid, click Add Row .
2. In the Name field, enter the extension name that your Kafka broker requires.
3. In the Value field, enter the value for that extension name.
4. (Optional) If your broker requires more than one extension, repeat the previous steps to add up to 10 extension rows.

To remove a SASL extension, click Delete for that row.

A Kafka broker that implements the SASL/OAUTHBEARER standard can define its own extension names. For example, a multi-tenant broker might require a tenant identifier such as tenantId. Appian does not validate extension names, because the Kafka broker determines which names it recognizes.

Deploy SASL extension values across environments

When you deploy an Apache Kafka connected system, Appian exports SASL extension values in the import customization file using indexed keys, such as saslExtensions.0 and saslExtensions.1. You can set a different value for each environment, such as a logicalCluster value that differs between development and production.

Import customization files and the connected system management API can update SASL extension values. Neither method can add new extensions, remove extension, or change extension names.

Test the connection

Click TEST CONNECTION to verify your credentials are valid and that you can access the Kafka instance. Appian checks that the credentials you provided can access at least one topic from which you can consume events.

The test connection has a 15-second timeout. If the connection exceeds this limit, the test fails with a timeout error.

Testing SASL-SSL authentication

For SASL-SSL authentication types, Appian validates the SSL handshake before attempting SASL authentication. If the SSL certificate is invalid, the test returns an SSL handshake error. If the SSL handshake succeeds but the broker rejects the SASL credentials, the test returns a SASL authentication error.

Testing JWT Bearer authentication

For the JWT Bearer Authorization Grant mechanism, Appian validates the connection in the following order:

1. Validate the SSL handshake (SASL-SSL only).
2. Generate the cryptographic assertion using the provided RSA private key.
3. Exchange the signed assertion with the identity provider for an access token.
4. Authenticate with the Kafka broker using the access token.

If any step fails, the test connection returns a specific error message indicating which phase failed. For example, if the private key format is invalid, the test returns a cryptographic assertion error. If the identity provider rejects the assertion, the test returns an IdP rejection error with guidance to verify your Client ID, Private Key ID, and public key configuration.

The JWT bearer test connection has a 20-second timeout. If the connection exceeds this limit, the test fails with a timeout error.

Feedback