Use API Keys to Control Access in StreamNative Cloud

Note

You need to upgrade the Pulsar cluster to the following minimum versions (2.9.5.2, 2.10.4.4, or 3.0.0.3) in order to access this feature. If you want to turn this feature on, please submit a ticket to the support team.

StreamNative Cloud API keys are used to control access to StreamNative Cloud components and resources.

API keys are JSON Web Tokens (JWTs) issued and managed in StreamNative Cloud. It allows you to create long-lived tokens and revoke them. These API keys are associated with the service accounts and the organization & instance from which you create them. For details about using user and service accounts and their ownership of API keys, see Ownership of API keys.

Use the Cluster API keys to control access to StreamNative Cloud clusters. Each Cluster API key is valid for one specific Pulsar cluster.

Currently, StreamNative Cloud doesn't support using API keys to control access to StreamNative Cloud resources and use the StreamNative Cloud APIs available for instances, user accounts, service accounts, and other resources. We plan to add this support based on user feedback.

To create and manage API keys in StreamNative Cloud, you can use the following tools:

StreamNative Cloud Console

For recommendations on using API keys, see Best Practices for Using API Keys in StreamNative Cloud.

Ownership of API keys

Each API key is associated with a specific [service account][id:service-accounts].

A best practice is to create separate service accounts associated with an API keys for each applications or use case.
Using API keys associated with a user account is currently not supported yet.
API keys are immutable and cannot be modified. If you need to change the permissions associated with an API key, you must delete the key and create a new one.
Access control lists (ACLs) and role bindings are associated with principals, not with API keys. For details, see Use Access Control Lists (ACLs) for StreamNative Cloud.
Restric access to an application that uses an API key associated with a service account:
- For resource API keys, you can use access control lists (ACLs).

Warning

When you delete a service account, all associated API keys will also be deleted. Any client applications using a deleted API key will lose access, which many cause an outage for your streaming application. Always confirm that none of the API keys owned by an account are in active use before deleting a service account.

Cluster API keys

Cluster API Keys are used to control access to specific StreamNative Cloud clusters. Each Cluster API key is valid for one specific Pulsar cluster. You can view the API keys of your organization by going to the Service Accounts page, and clicking on a Service Account's name, or by using snctl get apikey -n your-org-name.

Important

Cluster API keys propagate quickly after creation, usually within a few minutes. If you try to use an API key before propagation completes, authentication failures occur. Depending on workloads, you might need to wait a few minutes more and try again.

Prerequisites

Ensure your Pulsar cluster has been upgraded to the following minimum versions:

2.9.5.2
2.10.4.4
3.0.0.3

To use snctl for managing API keys, you will need snctl version 0.16.0 or later.

Create an Cluster API key

To create an Cluster API key for a specific service account in StreamNative Cloud Console, follow these steps.

On the left navigation pane, click Service Accounts.
On the Service Accounts page, select a specific service account.
Tip
You can also click New on the top-right corner and select Create API Key to create the API key for any service account.
On the API Key page of this service account, click New API Key.

Specify the required attributes for the API key.

Field	Description
Name	The name of the API key.
Expiration date	By default, each API key expires in 30 days. If you want it to be long-lived, you can select `No expiration date`.
Service Account	The service account you want to associate the API key with. The one selected in step 2 is auto-populated.
Instance	The instance where the API key applies (it won't work for other instances).
Description (optional)	The descriptive text to introduce the API key.

Click Confirm.
Click Copy and close to copy the generated API key and save it in a safe location for future use.
Warning
Make sure the generated API key is securely saved since you won't be able to see it again after closing this window.

Using API keys to connect to your cluster

After creating an API key in StreamNative Cloud Console, you can use it to authenticate Kafka, Pulsar, and MQTT clients.

Kafka Clients

You can use API keys with SASL/PLAIN authentication to connect Kafka clients to StreamNative Cloud clusters.

To configure SASL authentication on the clients:

Configure the JAAS configuration property for each client in producer.properties or consumer.properties. The login module describes how the clients like producers and consumers can connect to the cluster. Below is an example configuration for a client for the PLAIN mechanism:
```
sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
username="<tenant>/<namespace>" \
password="token:<API KEY>";
```
Use <tenant>/<namespace> as username and <API KEY> in password.
Configure the following properties in producer.properties or consumer.properties:
```
security.protocol=SASL_SSL
sasl.mechanism=PLAIN
```

For configuring Kafka clients in different languages to use API keys, you can find examples on "Build Applications > Kafka Clients".

Pulsar Clients

You can use API keys with JWT authentication to connect Pulsar clients to StreamNative Cloud clusters.

For configuring Pulsar clients in different languages to use API keys, you can find examples on "Build Applications > Pulsar Clients".

For more examples of configuring Pulsar clients using API keys, see JWT Authentication in Pulsar documentation.

MQTT Clients

You can use API keys as password to connect MQTT clients to StreamNative Cloud clusters.

An example is shown below, where <username> can be any string and password is the API key.

Mqtt5SimpleAuth simpleAuth = Mqtt5SimpleAuth.builder().username("<username>")
                .password("<API KEY>")
                .build();

Deleting and Revoking API Keys

To delete or revoke an API key for a specific service account in StreamNative Cloud Console, follow these steps.

On the left navigation pane, click Service Accounts.
On the Service Accounts page, select a specific service account.
On the API Key page of this service account, click the Ellipsis (...) icon in the row of the API key that you want to revoke/delete, and select Revoke or Delete.
Type the API key’s name to confirm and then click Revoke or Confirm.

What's expected after a revocation?

Revoked API keys will be removed from their service accounts in 15 days.
If an API key gets revoked when being used by Kafka clients, the connection will stay alive. For Pulsar clients, the connection will be terminated in 1 minute.

What's expected after a deletion?

If an API key is deleted, it will simulateneously be revoked.

Cloud API keys

StreamNative Cloud doesn't support using API keys to access StreamNative Cloud API. Instead, you can use OAuth2 to connect to the StreamNative Cloud API.