Zitadel Auth Callout for NATS

This project implements a NATS auth callout service that authenticates users using Zitadel as an Identity Provider (IdP).

Overview

The service verifies Zitadel OIDC tokens and issues corresponding NATS JWTs with appropriate permissions based on the user's roles and identity information provided by Zitadel.

Features

• Integrates with Zitadel as an OIDC identity provider
• Verifies JWT tokens issued by Zitadel
• Maps Zitadel users to NATS permissions
• Stores user information in NATS JetStream KV store
• Configurable permissions based on Zitadel roles
• HTTP API for token validation
• Kubernetes-ready deployment options

Prerequisites

• Go 1.21+
• NATS server
• Task - Task runner (alternative to Make)
• Zitadel instance (default: https://zitadel.252.no)
• Docker (optional, for containerized deployment)
• Kubernetes and Helm (optional, for Kubernetes deployment)

Configuration

Configuration is handled via environment variables with sensible defaults:

Variable	Default	Description
NATS_URL	nats://localhost:4222	NATS server URL
NATS_USER	auth	NATS user for authentication
NATS_PASSWORD	auth	NATS password for authentication
NKEY_SEED	SAAIRUPUPZ4CZZX4EYX2MF6A3KN7FGI3AQPEVF3HI2JXVNV6DJGSTZGDFE	NKey seed for signing JWTs
ZITADEL_URL	https://zitadel.252.no	Zitadel instance URL
ZITADEL_CLIENT_ID	your-client-id	Zitadel client ID
USER_BUCKET	zitadel_users	NATS KV bucket for user storage
HTTP_ADDR	:8080	HTTP server address and port
DEBUG	false	Enable debug logging
TEST_MODE	false	Enable test mode (use mock verifier)

Building and Running

We use Task for building and running the service:

# List available tasks
task

# Install dependencies
task tidy

# Build
task build

# Run
task run

# Run with test environment
task test

# Test a token
task token:test -- 'your-zitadel-token'

# Clean up
task clean

Docker Deployment

A multi-stage Dockerfile is included for containerized deployment:

# Build the Docker image
docker build -t nats-auth-callout-zitadel:latest .

# Run the container
docker run -p 8080:8080 \
  -e NATS_URL=nats://host.docker.internal:4222 \
  -e ZITADEL_CLIENT_ID=your-client-id \
  nats-auth-callout-zitadel:latest

The image uses a minimal scratch base for security and performance.

Kubernetes Deployment

Kubernetes deployment files are provided in the kubernetes/ directory:

# Deploy to Kubernetes
kubectl apply -f kubernetes/auth-service.yaml -n nats-system

# Configure NATS with Helm
helm upgrade --install nats-server nats/nats \
  -f kubernetes/nats-values.yaml -n nats-system

The deployment includes:

• Secret management for sensitive values
• Readiness/liveness probes
• Resource management
• Service configuration

NATS Configuration

The included nats.conf configures NATS to use this service for authentication:

authorization {
  auth_callout {
    issuer: AC25V2UFTKLJSBOGZAQC7Q2LRZKYHBUNXP3NOWBY72A6UYECOJKXHGU2
    auth_users: [ auth, user ]
    account: ZITADEL
  }
}

For Kubernetes deployments, use the kubernetes/nats-values.yaml configuration with the NATS Helm chart.

Token Management

The scripts/token.sh script provides utilities for token management:

# Generate a token
scripts/token.sh generate > token.txt

# Validate a token
scripts/token.sh validate $(cat token.txt)

# Test token validation
scripts/token.sh test

HTTP API

The service exposes an HTTP API for token validation:

• POST /validate - Validates a token (JSON body: {"token": "your-token"})
• GET /health - Health check endpoint

Security Considerations

• The NKeySeed should be stored securely, not hardcoded in the source
• Configure proper TLS for NATS connections in production
• Use environment variables or Kubernetes secrets for sensitive configuration
• The Docker image uses a minimal scratch base for reduced attack surface