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 bearer value in gRPC metadata attached to every outgoing request, set via the auth_token: keyword argument when constructing KubeMQ::PubSubClient. The server validates it before honoring any call, including the initial handshake. Because a static token eventually expires, source it from an environment variable or a secrets manager rather than a literal, so rotation only requires updating the environment and reconnecting.

Gotchas: an invalid or expired token isn't rejected until the first real call — call ping right after connecting so failures surface as a KubeMQ::AuthenticationError immediately instead of on your first business request; never hardcode a real token in source; and the client's auth_token is static for its lifetime, so long-running processes holding short-lived JWTs need to reconnect on a schedule rather than expecting in-place refresh.

Prerequisites

• KubeMQ server running on localhost:50000 with authentication enabled
• Ruby SDK installed (gem install kubemq)

Code

require 'kubemq'

address = ENV.fetch('KUBEMQ_ADDRESS', 'localhost:50000')
token = ENV.fetch('KUBEMQ_AUTH_TOKEN', 'your-auth-token-here')

begin
  client = KubeMQ::PubSubClient.new(
    address: address,
    client_id: 'auth-token-example',
    auth_token: token
  )
  puts "Connected with auth token to #{address}"

  info = client.ping
  puts "Ping OK: host=#{info.host}, version=#{info.version}"
rescue KubeMQ::Error => e
  puts "KubeMQ error: #{e.message}"
ensure
  client&.close
  puts 'Connection closed'
end

How It Works

• The auth_token is sent as a bearer token in the gRPC metadata for every request.
• Store tokens in environment variables or a secrets manager — never hard-code credentials.
• If authentication fails, the SDK raises KubeMQ::AuthenticationError.
• Review timeouts, channel names, and client IDs before running against shared environments.

Related

• Ruby SDK Reference
• Connect
• TLS Setup