Authentication (tls, mTLS, SASL)

This page describes how to configure authentication for the WarpStream Agent so it can be exposed safely over the internet.

The WarpStream Agent offers built-in support for secure authentication and encrypted communication:

SASL Authentication: Protects the Apache Kafka protocol port (default 9092) using SASL/PLAIN or SASL/SCRAM-SHA-512.
TLS Encryption: Secures communication over the Apache Kafka protocol port using TLS/mTLS.

This is useful if you need to access your WarpStream topics from outside your VPC, or integrate with cloud-hosted compute engines like Materialize, ClickHouse, MongoDB Stream Processing, or RisingWave.

Important Note:

SASL authentication only protects the Apache Kafka protocol port (default 9092). TheHTTP port (default 8080)inthe Agent that exposes the distributed file cache and prometheus metrics is not protected by SASL and should not be exposed to the public internet.

TLS termination

You can configure TLS termination in two ways: in the Agent or in a load balancer in front of the agents.

Option 1: In the WarpStream Agent

This method leverages the built-in TLS/mTLS support of the WarpStream Agent. Here's a detailed breakdown of the steps involved:

Enable TLS:
- During Agent deployment, include the -kafkaTLS flag or set the environment variable WARPSTREAM_TLS_ENABLED=true. This activates TLS encryption for the Apache Kafka protocol port (default 9092).
Provide Certificates:
- Obtain a valid TLS certificate (public key) and the corresponding private key. These should be in PEM-encoded X.509 format.
- Use the following flags or environment variables to provide the file paths to the Agent:
  - -tlsServerCertFile or WARPSTREAM_TLS_SERVER_CERT_FILE (for the certificate)
  - -tlsServerPrivateKeyFile or WARPSTREAM_TLS_SERVER_PRIVATE_KEY_FILE (for the private key)
Optional: Enable mTLS (Mutual TLS):
- If you want to enforce client authentication, add the -requireMTLSAuthentication flag or set WARPSTREAM_REQUIRE_MTLS_AUTHENTICATION=true.
- This requires clients to present their own valid TLS certificates during connection establishment.
- By default, the Agent will use the Distinguished Name(DN) from the client TLS certificate as the principal for ACLs.
- A custom TLS mapping rule regex can be provided using the -tlsPrincipalMappingRule flag to extract a name from the DN. For example, the rule CN=([^,]+) will extract the Common Name(CN) from the DN, and use that as the ACL principal.
- For example, given the certificate below, and if the -tlsPrincipalMappingRule when the Agent is started is CN=([^,]+) then the name test_principal will be used as the mTLS ACL principal.

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            08:d5:5f:22:cf:32:27:78:67:c1:ed:05:79:83:02:7b
        Signature Algorithm: ecdsa-with-SHA256
        Issuer: O=root, CN=Root CA
        Validity
            Not Before: Sep  3 20:34:13 2024 GMT
            Not After : Sep  1 20:34:13 2034 GMT
        Subject: O=test, CN=test_principal
        Subject Public Key Info:
            Public Key Algorithm: id-ecPublicKey
                Public-Key: (256 bit)
                pub:
                    04:e8:9b:a8:9c:60:6e:4a:a5:8e:d9:77:9b:23:0e:
                    94:eb:53:d2:e5:fc:9a:51:d9:b8:10:f3:e5:1d:e6:
                    c7:a6:91:60:7c:83:2e:93:74:85:b7:3f:fc:e1:a1:
                    dc:d2:d5:bc:3a:a5:51:e3:32:2b:8c:13:73:c9:0f:
                    70:0b:10:9a:96
                ASN1 OID: prime256v1
                NIST CURVE: P-256
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature
            X509v3 Extended Key Usage: 
                TLS Web Server Authentication, TLS Web Client Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE
            X509v3 Authority Key Identifier: 
                EE:9D:66:7C:9F:A1:88:14:71:F6:8E:9F:3E:13:4E:7C:53:D5:99:EF
            X509v3 Subject Alternative Name: 
                DNS:localhost, IP Address:192.168.2.17
    Signature Algorithm: ecdsa-with-SHA256
    Signature Value:
        30:44:02:20:5a:65:92:21:22:0b:61:73:aa:15:98:e0:cd:b1:
        2c:0d:b1:26:79:96:8b:cc:d4:a1:43:32:d9:56:06:70:50:d8:
        02:20:20:77:91:3b:5b:a7:7b:69:e9:6f:b1:aa:76:ba:4e:41:
        d5:90:f3:bb:ec:ad:14:99:5e:ba:ce:29:82:3e:7a:77

Optional: Provide a client root CA cert file (mTLS):
- If you've enabled mTLS, you can provide a root Certificate Authority (CA) certificate file.
- Use the -tlsClientCACertFile flag or the WARPSTREAM_TLS_CLIENT_CA_CERT_FILE environment variable.

Option 2: On a Load Balancer

This method involves placing a load balancer in front of your WarpStream Agents to handle TLS termination. You should only expose the Apache Kafka protocol port, as that is the only one that will be authenticated via SASL. Here's how to configure it:

Configure Load Balancer:
- Set up your load balancer (e.g., AWS Network Load Balancer) to listen for incoming traffic on the Apache Kafka protocol port (default 9092).
- Ensure that the load balancer terminates TLS connections and forwards decrypted traffic to the WarpStream Agents.
Expose Kafka Port Only:
- Configure the load balancer to expose only the Apache Kafka protocol port (9092) to the public internet.
- The HTTP port (8080) used for metrics and the distributed file cache should not be publicly accessible.
Update Service Discovery:
- By default, the WarpStream Agent is designed to automatically integrate with the WarpStream discovery system, assuming they're running inside a VPC. If the Agent is deployed behind a load balancer performing TLS termination, then the configuration must be modified so that service discovery works properly.
- Set the environment variable WARPSTREAM_DISCOVERY_KAFKA_HOSTNAME_OVERRIDE to the host/DNS name of the load balancer.
- If the load balancer uses a non-default port for the Kafka protocol, set WARPSTREAM_DISCOVERY_KAFKA_PORT_OVERRIDE to the correct port.

Example: AWS Network Load Balancer (NLB)

If you're using an AWS NLB, the environment variable would look like this:

WARPSTREAM_DISCOVERY_KAFKA_HOSTNAME_OVERRIDE=$NLB_NAME-XXXXXXXXXXXX.elb.us-east-1.amazonaws.com

Example: Fly.io

If you're using an fly.io, the environment variable would look like this:

WARPSTREAM_DISCOVERY_KAFKA_HOSTNAME_OVERRIDE=$APP_NAME.fly.dev

For more details on how WarpStream and Kafka's service discovery mechanisms interact and why overriding these environment variables is necessary, see our "Service Discovery" reference documentation.

SASL Authentication

The WarpStream Agents support SASL/PLAIN and SASL/SCRAM-SHA-512.

First, deploy the Agent like you normally would following our "Configure the WarpStream Agent for Production" guide. However, you'll need to make one small addition which is to add the -requireAuthentication flag or add an environment variable: WARPSTREAM_REQUIRE_AUTHENTICATION=true .

Once authentication is enabled on the Agent, it will enforce that all Apache Kafka clients that connect to them authenticate themselves via SASL. Otherwise, it will refuse the connection.

In order to connect an Apache Kafka client to the authenticated WarpStream Agent, you'll need to create a set of credentials. You can do that by navigating to the "Virtual Clusters" section of the WarpStream Console and then clicking "View Credentials" on the Virtual Cluster that you want to create a set of credentials for.

Once you're on the credentials view, you can create a new set of SASL credentials by clicking the "New Credentials" button.

Every set of WarpStream SASL credentials are scoped to a specific Virtual Cluster and Agent Pool, so you'll have to select which Agent Pool you'd like to create the credentials for as well.

Once you're done creating the credentials, the admin console will show you the username and password one time. Store these values somewhere safe, as you'll never be able to view them again. WarpStream does not store them in plaintext, so we cannot retrieve them for you.

In the case that you lose your credentials, you can create a new set of credentials in the admin console following the same steps as above, up to a limit of 100 credentials.

Let's test the credentials we just created. Make sure that your Agent is enforcing authentication by trying to connect to it with invalid credentials first:

warpstream kcmd -type diagnose-connection -bootstrap-host $TLS_TERMINATOR_HOST_NAME -tls -username ccun_invalid_username -password ccp_invalid_password

If the Agent is configured to require authentication, this should result in an error message like:

failed to fetch broker metadata: SASL_AUTHENTICATION_FAILED: SASL Authentication failed.

Now let's try with the valid credentials we created previously:

warpstream kcmd -type diagnose-connection -bootstrap-host $TLS_TERMINATOR_HOST_NAME -tls -username ccun_XXXXXXXXXX -password ccp_XXXXXXXXXX

If you want to use SASL/SCRAM-SHA-512 instead, you can run:

warpstream kcmd -type diagnose-connection -bootstrap-host serverless.warpstream.com -tls -username ccun_XXXXXXXXXX -password ccp_XXXXXXXXXX -scram

This time you should see a successful message like the following:

Broker Details
---------------
  $TLS_TERMINATOR_HOST_NAME:9092 (NodeID: 0) [UNKNOWN_RACK]
    ACCESSIBLE ✅


GroupCoordinator: $TLS_TERMINATOR_HOST_NAME:9092 (NodeID: 0)
    ACCESSIBLE ✅

PreviousAgent Groups NextLow Latency Clusters

Last updated 4 days ago