Using the Kafka API

Support summary for all recommended clients

Connecting your client to Event Streams

For information about how to configure your Java client to connect to Event Streams, see Configuring your client.

Using SASL PLAIN

Use the following strings and properties.

• Use the bootstrap_endpoints string as the list of bootstrap servers and pass this string of host and port pairs to your Kafka client.
• Use the user and api_key properties as the username and password.

For a Java client, the following example shows the minimum set of properties, where ${USERNAME}, ${PASSWORD}, and ${BOOTSTRAP_ENDPOINTS} are to be replaced by the values that you retrieved previously.

bootstrap.servers=${BOOTSTRAP_ENDPOINTS}
sasl.mechanism=PLAIN
sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="${USERNAME}" password="${PASSWORD}";
security.protocol=SASL_SSL
ssl.protocol=TLSv1.2
ssl.enabled.protocols=TLSv1.2
ssl.endpoint.identification.algorithm=HTTPS

If you use a Kafka client earlier than version 0.10.2.1, the sasl.jaas.config property isn't supported, and you must instead provide the client configuration in a JAAS configuration file.

Using SASL OAUTHBEARER

Before configuring the SASL mechanism for Java client, there are two prerequisites.

• The minimum supported Kafka Java client version is 3.1.0.
• Additional jar package needs to be downloaded from Maven Central and made available in the classpath.

If Maven is used in build system, add the following information to the file pom.xml in the dependencies section.

<dependency>
    <groupId>com.ibm.cloud.eventstreams</groupId>
    <artifactId>oauth-client</artifactId>
    <version>1.3.1</version>
</dependency>

If Gradle is used in build system, add the following information to the file build.gradle in the dependencies section.

implementation com.ibm.cloud.eventstreams:oauth-client:1.3.1

Use the following strings and properties.

• Use the bootstrap_endpoints string as the list of bootstrap servers and pass this string of host and port pairs to your Kafka client.
• Use the api_key string as the API key.
• The IAMOAuthBearerLoginCallbackHandler is provided by the jar package com.ibm.cloud.eventstreams:oauth-client:+.
• The IBM Cloud® Identity and Access Management's token endpoint https://iam.cloud.ibm.com/identity/token is configured to generate token from the API key by using specified grant type in jaas config. It is done on client side, thus the API key is never sent to the server side and provides better security than a long-lived API key.
• The Cloud Identity and Access Management's key endpoint https://iam.cloud.ibm.com/identity/keys is configured to validate the token.

For a Java client, the following example shows the minimum set of properties, where ${BOOTSTRAP_ENDPOINTS}, and ${APIKEY} are to be replaced by the values that you retrieved previously.

bootstrap.servers=${BOOTSTRAP_ENDPOINTS}
sasl.mechanism=OAUTHBEARER
sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required grant_type="urn:ibm:params:oauth:grant-type:apikey" apikey="${APIKEY}";
sasl.login.callback.handler.class=com.ibm.eventstreams.oauth.client.IAMOAuthBearerLoginCallbackHandler
sasl.oauthbearer.token.endpoint.url=https://iam.cloud.ibm.com/identity/token
sasl.oauthbearer.jwks.endpoint.url=https://iam.cloud.ibm.com/identity/keys
security.protocol=SASL_SSL
ssl.protocol=TLSv1.2
ssl.enabled.protocols=TLSv1.2
ssl.endpoint.identification.algorithm=HTTPS

The sample code refers to the Event Streams samples.

For other Kafka client libaries, refer to their documentation about how to implement OAUTHBEARER support. For example:.

• sarama: an implementation of AccessTokenProvider interface is required.
• librdkafka: an implementation of oauthbearer_token_refresh_cb callback is required.

For information about how to generate an IBM Cloud IAM token by using an API key, see IBM Cloud® Identity and Access Management's document.