Token Authentication

Overview

Token authentication proves a client's identity to a KubeMQ server that has authentication enabled, without embedding a username/password or issuing per-client TLS certs. It's the mechanism you reach for in shared clusters, multi-tenant deployments, or any environment where you need to control and audit which clients are allowed to connect — the token is issued and revoked by your identity provider, not baked into the binary.

The token travels as a gRPC metadata header attached to every outgoing RPC, set once at client construction with kubemq.WithAuthToken(...). The server validates it against its configured authentication provider before honoring any call, including the very first one. Because a static token eventually expires, kubemq.WithCredentialProvider(p) lets the SDK pull a fresh token from your provider before each RPC instead of forcing a client restart on rotation.

Gotchas: an invalid or expired token isn't rejected until the first real RPC — call Ping right after connecting so failures surface immediately instead of on your first business request; never hardcode a real token in source, read it from an environment variable or secrets manager; and a static WithAuthToken value never refreshes itself, so short-lived JWTs need the credential-provider path, not a periodically-restarted client.

Prerequisites

• KubeMQ server running on localhost:50000
• Go SDK installed (go get github.com/kubemq-io/kubemq-go/v2)

Code

// Example: connection/token-auth
//
// Demonstrates how to connect to a KubeMQ server with authentication
// using a JWT token. The WithAuthToken option sets a static token that
// is sent with every request.
//
// Channel: go-connection.token-auth
// Client ID: go-connection-token-auth-client
//
// Run with a KubeMQ server configured for token authentication.
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/kubemq-io/kubemq-go/v2"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	// Connect with a static JWT authentication token.
	client, err := kubemq.NewClient(ctx,
		kubemq.WithAddress("localhost", 50000),
		kubemq.WithClientId("go-connection-token-auth-client"),
		kubemq.WithAuthToken("your-jwt-token-here"),
	)
	if err != nil {
		log.Fatalf("Failed to connect with token auth: %v", err)
	}
	defer client.Close()

	// Verify the authenticated connection.
	info, err := client.Ping(ctx)
	if err != nil {
		log.Fatalf("Ping failed: %v", err)
	}
	fmt.Printf("Authenticated connection: host=%s version=%s\n",
		info.Host, info.Version)
}

How It Works

1. kubemq.WithAuthToken("your-jwt-token-here") attaches the token as a gRPC metadata header on every outgoing RPC; the broker verifies it against its configured authentication provider.
2. Replace "your-jwt-token-here" with a real JWT before running; the broker returns an ErrCodeAuthentication error on the first call if the token is invalid or expired.
3. For tokens that expire and rotate, use kubemq.WithCredentialProvider(p) instead — the provider is called before each RPC to supply a fresh token without restarting the client.
4. A successful Ping after construction confirms that the authentication handshake completed correctly.

Related

• Go SDK Reference
• Connect
• Close