Token Auth

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

The token travels as a bearer value in gRPC metadata attached to every outgoing call, set via the auth_token: option passed to KubeMQ.Client.start_link/1. The server validates it before honoring any call, including the initial handshake. Because a static token eventually expires, the recommended pattern is to source it from an environment variable (System.get_env("KUBEMQ_AUTH_TOKEN")) rather than hardcoding it, so rotation only requires updating the environment and restarting the client process.

Gotchas: an invalid or expired token isn't rejected until the first real call — call KubeMQ.Client.ping/1 right after start_link/1 so failures surface immediately instead of on your first business request; never hardcode a real token in source; and the client's auth_token is static for the life of the process, so long-running clients holding short-lived JWTs need to be restarted with a fresh token rather than expecting in-place refresh.

Prerequisites

• KubeMQ server running on localhost:50000 with authentication enabled
• Elixir SDK installed ({:kubemq, "~> 1.0"} in mix.exs)

Code

auth_token = System.get_env("KUBEMQ_AUTH_TOKEN", "your-auth-token-here")
IO.puts("Connecting with auth token...")

case KubeMQ.Client.start_link(
       address: "localhost:50000",
       client_id: "elixir-auth-example",
       auth_token: auth_token
     ) do
  {:ok, client} ->
    IO.puts("Authenticated connection established!")

    case KubeMQ.Client.ping(client) do
      {:ok, info} -> IO.puts("Server version: #{info.version}")
      {:error, err} -> IO.puts("Ping failed: #{err.message}")
    end

    KubeMQ.Client.close(client)

  {:error, reason} ->
    IO.puts("Auth connection failed: #{inspect(reason)}")
end

How It Works

• The auth_token option attaches a bearer token to all gRPC calls
• Token is read from the KUBEMQ_AUTH_TOKEN environment variable for production use
• Connection fails with an authentication error if the token is invalid

Related

• Connect
• TLS Setup
• Connection Error