Skip to content

authentication.md

Latest commit

 

History

History
127 lines (89 loc) · 2.88 KB

authentication.md

File metadata and controls

127 lines (89 loc) · 2.88 KB

Authentication

This document describes authentication mechanisms for the HyperFleet API.

Overview

HyperFleet API supports two authentication modes:

  1. Development Mode (No Auth): For local development and testing
  2. Production Mode (JWT Auth): JWT-based authentication with configurable issuer

Development Mode (No Auth)

For local development and testing, authentication can be disabled.

Usage

# Start service without authentication
make run-no-auth

# Access API without tokens
curl http://localhost:8000/api/hyperfleet/v1/clusters | jq

Configuration

export HYPERFLEET_SERVER_JWT_ENABLED=false
./bin/hyperfleet-api serve

Important: Never disable authentication in production environments.

Production Mode (JWT Auth)

Production deployments use JWT-based authentication with a configurable issuer.

Usage

# Start service with authentication
make run

# Access API with a valid JWT
curl -H "Authorization: Bearer ${TOKEN}" \
  http://localhost:8000/api/hyperfleet/v1/clusters

JWT Authentication

HyperFleet API validates JWT tokens using RS256 signature verification.

Token validation checks:

  1. Signature - Token signed by trusted issuer
  2. Issuer - Matches configured HYPERFLEET_SERVER_JWT_ISSUER_URL
  3. Audience - Matches configured HYPERFLEET_SERVER_JWT_AUDIENCE
  4. Expiration - Token not expired
  5. Claims - Required claims present

Token format:

Authorization: Bearer <jwt-token>

Example request:

curl -H "Authorization: Bearer ${TOKEN}" \
  http://localhost:8000/api/hyperfleet/v1/clusters

Configuration

Environment Variables

# Development (no auth)
export HYPERFLEET_SERVER_JWT_ENABLED=false

# Production (with auth)
export HYPERFLEET_SERVER_JWT_ENABLED=true
export HYPERFLEET_SERVER_JWT_ISSUER_URL=https://your-idp.example.com/auth/realms/your-realm
export HYPERFLEET_SERVER_JWT_AUDIENCE=https://your-api.example.com

See Deployment for complete configuration options.

Kubernetes Deployment

Configure via Helm values:

# values.yaml
config:
  server:
    jwt:
      enabled: true
      issuer_url: https://your-idp.example.com/auth/realms/your-realm
      audience: https://your-api.example.com

Deploy:

helm install hyperfleet-api ./charts/ --values values.yaml

Troubleshooting

Common Issues

401 Unauthorized

  • Check token is valid and not expired
  • Verify HYPERFLEET_SERVER_JWT_ISSUER_URL and HYPERFLEET_SERVER_JWT_AUDIENCE match token claims
  • Ensure Authorization header is correctly formatted

Token debugging

# Decode JWT token (header and payload only, not verified)
echo $TOKEN | cut -d. -f2 | base64 -d | jq

# Check token expiration
echo $TOKEN | cut -d. -f2 | base64 -d | jq '.exp | todate'

Related Documentation

  • Deployment - Authentication configuration and Kubernetes setup