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 application.

The token travels as a gRPC Authorization header attached to every outgoing request. The credentials option on KubeMQClient.create(...) accepts either a plain JWT string for a long-lived token, or a CredentialProvider instance — StaticTokenProvider wraps a fixed token explicitly, while a custom provider can fetch and refresh a token on its own schedule instead of forcing a client recreation on rotation.

Gotchas: an invalid token throws AuthenticationError (code AUTH_FAILED) directly from KubeMQClient.create() — not on a later call — so wrap connection setup in a try/catch, not just your first request; never hardcode a real token in source, read it from an environment variable or secrets manager; and the error is not retried automatically, so a rotating token needs a real CredentialProvider implementation rather than a plain string that goes stale.

Prerequisites

• KubeMQ server running on localhost:50000
• Node.js SDK installed (npm install kubemq-js)

Code

/**
 * Example: Token Authentication
 *
 * Demonstrates connecting to a KubeMQ server with token-based
 * authentication. You can pass a static token string or use a
 * CredentialProvider for dynamic token refresh.
 *
 * Prerequisites:
 *   - KubeMQ server running with authentication enabled
 *
 * Run: npx tsx examples/configuration/token-auth.ts
 */
import { KubeMQClient, StaticTokenProvider, AuthenticationError } from 'kubemq-js';

async function main(): Promise<void> {
  // Option 1: Pass a token string directly.
  try {
    const client = await KubeMQClient.create({
      address: 'localhost:50000',
      clientId: 'js-configuration-token-auth-client',
      credentials: 'your-jwt-auth-token',
    });

    console.log('Connected with static token');
    await client.close();
  } catch (err) {
    if (err instanceof AuthenticationError) {
      console.error('Auth failed:', err.message);
    }
  }

  // Option 2: Use a StaticTokenProvider (same result, explicit provider pattern).
  try {
    const client = await KubeMQClient.create({
      address: 'localhost:50000',
      clientId: 'js-configuration-token-auth-client',
      credentials: new StaticTokenProvider('your-jwt-auth-token'),
    });

    console.log('Connected with StaticTokenProvider');
    await client.close();
  } catch (err) {
    if (err instanceof AuthenticationError) {
      console.error('Auth failed:', err.message);
    }
  }
}

main().catch(console.error);

How It Works

• The credentials option accepts either a plain JWT string (Option 1) or a CredentialProvider instance (Option 2). Both result in the same gRPC Authorization header on every request.
• StaticTokenProvider wraps a fixed token; implement CredentialProvider yourself for dynamic refresh (e.g. tokens that rotate every hour).
• Authentication errors surface as AuthenticationError (code AUTH_FAILED) thrown during KubeMQClient.create() — not retryable by default.
• Replace 'your-jwt-auth-token' with the actual token issued by your KubeMQ server's auth configuration.

Related

• Node.js SDK Reference
• Connect
• Close