Skip to content

Authentication

bindcar uses Bearer token authentication to secure API endpoints.

Overview

By default, authentication is enabled for all API endpoints except: - /api/v1/health - /api/v1/ready - /metrics

All other endpoints require a valid Bearer token in the Authorization header.

Authentication Modes

The published bindcar images are built with the k8s-token-review feature compiled in, and the active mode is selected at runtime. Shared-secret and TokenReview auth are mutually exclusive — a single Bearer token cannot be both a shared secret and a valid ServiceAccount token — so BIND_API_TOKEN selects the mode:

Shared-secret Mode (BIND_API_TOKEN set)

  • The presented Bearer token must equal BIND_API_TOKEN (constant-time compare)
  • The Kubernetes TokenReview API is not consulted, and the fail-closed TokenReview allowlist guard (below) is not enforced at startup
  • Suitable for drone/standalone deployments and trusted environments

TokenReview Mode (BIND_API_TOKEN unset, feature compiled)

  • Full token validation with the Kubernetes TokenReview API
  • Verifies token signatures, checks expiration, validates token audience
  • Restricts to allowed namespaces and ServiceAccounts
  • Fail-closed: bindcar refuses to start unless an allowlist (BIND_ALLOWED_NAMESPACES / BIND_ALLOWED_SERVICE_ACCOUNTS) is set or BIND_ALLOW_ANY_SERVICEACCOUNT=true is explicitly configured
  • Recommended for production Kubernetes deployments (this is how bindy runs bindcar)

A build without the k8s-token-review feature only validates token presence/format (no signature check) — token verification must then be handled by infrastructure (API gateway, Linkerd service mesh). See Kubernetes TokenReview Validation.

Bearer Token Authentication

How It Works

  1. Client obtains a token (e.g., Kubernetes ServiceAccount token)
  2. Client includes token in the Authorization header
  3. bindcar validates the token format
  4. Request is processed if token is valid

Token Format

Authorization: Bearer <token>

Example: 

curl http://localhost:8080/api/v1/zones \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6..."

Kubernetes ServiceAccount Tokens

In Kubernetes environments, use ServiceAccount tokens for authentication.

Creating a ServiceAccount

apiVersion: v1
kind: ServiceAccount
metadata:
  name: bindcar-client
  namespace: default

Using the Token

Get the token: 

# Kubernetes 1.24+
kubectl create token bindcar-client

# Or from a mounted secret
kubectl get secret bindcar-client-token -o jsonpath='{.data.token}' | base64 -d

Use with bindcar: 

TOKEN=$(kubectl create token bindcar-client)

curl http://bindcar-service:8080/api/v1/zones \
  -H "Authorization: Bearer $TOKEN"

Complete Kubernetes Example

apiVersion: v1
kind: ServiceAccount
metadata:
  name: dns-api-client
---
apiVersion: v1
kind: Pod
metadata:
  name: dns-client
spec:
  serviceAccountName: dns-api-client
  containers:
  - name: client
    image: curlimages/curl:latest
    command:
    - sh
    - -c
    - |
      TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
      curl -H "Authorization: Bearer $TOKEN" \
        http://bindcar-service:8080/api/v1/zones

Custom Bearer Tokens

For non-Kubernetes environments, you can use any bearer token:

# Generate a random token
TOKEN=$(openssl rand -base64 32)

# Use with bindcar
curl http://localhost:8080/api/v1/zones \
  -H "Authorization: Bearer $TOKEN"

Note: In Basic Mode, bindcar validates token format but does not verify token signatures. Token verification should be handled by infrastructure (API gateway, Linkerd service mesh, etc.). For production environments requiring token signature verification, use TokenReview Mode.

Disabling Authentication

For trusted environments where authentication is handled by infrastructure:

Docker

docker run -d \
  -p 8080:8080 \
  -e DISABLE_AUTH=true \
  ghcr.io/firestoned/bindcar:latest

Kubernetes

env:
- name: DISABLE_AUTH
  value: "true"

WARNING: Only disable authentication when: - Running behind an authenticating API gateway - Using Linkerd service mesh with mTLS and authorization policies - Running in a completely trusted network - For local development only

Authentication Errors

401 Unauthorized

Missing or invalid authorization header:

curl http://localhost:8080/api/v1/zones

Response: 

{
  "error": "Unauthorized",
  "message": "Missing Authorization header"
}

Invalid Token Format

curl http://localhost:8080/api/v1/zones \
  -H "Authorization: InvalidFormat"

Response: 

{
  "error": "Unauthorized",
  "message": "Invalid Authorization header format. Expected: Bearer <token>"
}

Empty Token

curl http://localhost:8080/api/v1/zones \
  -H "Authorization: Bearer "

Response: 

{
  "error": "Unauthorized",
  "message": "Empty token"
}

Linkerd Service Mesh Integration

When using Linkerd, authentication can be handled at the mesh level:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    linkerd.io/inject: enabled
spec:
  containers:
  - name: bindcar
    image: ghcr.io/firestoned/bindcar:latest
    env:
    - name: DISABLE_AUTH
      value: "true"  # Linkerd handles auth

Best Practices

  1. Always enable authentication in production - Unless using Linkerd service mesh
  2. Rotate tokens regularly - Especially for long-lived tokens
  3. Use short-lived tokens - Kubernetes ServiceAccount tokens are ideal
  4. Limit token scope - Use Kubernetes RBAC to limit what tokens can do
  5. Monitor authentication failures - Watch for 401 errors in logs
  6. Use HTTPS in production - Protect tokens in transit

Security Considerations

Basic Mode: - Validates token format but not signatures - Token verification should be done by: - API gateway or Linkerd service mesh - External authentication service - Suitable for trusted environments only

TokenReview Mode: - Full token validation with Kubernetes API - Recommended for production environments - Provides defense-in-depth security - Can restrict access by namespace and ServiceAccount

General: - Tokens are logged at debug level - use info in production - Always use HTTPS in production to protect tokens - Rotate tokens regularly - Use short-lived tokens when possible

Next Steps