passkey-auth/PRODUCTION.md

Production Deployment Guide

This guide covers deploying Passkey Auth in a production Kubernetes environment.

Prerequisites

• Kubernetes cluster with nginx ingress controller
• Domain name with SSL certificate
• kubectl access to the cluster
• Docker registry access (optional, for custom builds)

Step 1: Prepare Configuration

1. Generate Session Secret:

openssl rand -base64 32

2. Update Kubernetes Configuration:

Edit k8s/deployment.yaml and update the ConfigMap:

data:
  config.yaml: |
    server:
      port: "8080"
      host: "0.0.0.0"

    webauthn:
      rp_display_name: "Your Company Auth"
      rp_id: "auth.yourcompany.com"        # Your auth domain
      rp_origins:
        - "https://auth.yourcompany.com"    # Your auth URL
        - "https://app.yourcompany.com"     # Your app URLs

    database:
      path: "/data/passkey-auth.db"

    cors:
      allowed_origins:
        - "https://auth.yourcompany.com"
        - "https://app.yourcompany.com"

    auth:
      session_secret: "YOUR_GENERATED_SECRET_HERE"
      require_approval: true

Step 2: Deploy to Kubernetes

1. Create Namespace:

kubectl apply -f k8s/namespace.yaml

2. Deploy Application:

kubectl apply -f k8s/deployment.yaml

3. Verify Deployment:

kubectl get pods -n passkey-auth
kubectl logs -f deployment/passkey-auth -n passkey-auth

Step 3: Configure SSL/TLS

Create an ingress with SSL termination:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: passkey-auth-ingress
  namespace: passkey-auth
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"  # If using cert-manager
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  tls:
  - hosts:
    - auth.yourcompany.com
    secretName: passkey-auth-tls
  rules:
  - host: auth.yourcompany.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: passkey-auth-service
            port:
              number: 80

Step 4: Configure Your Application Ingress

Update your application's ingress to use passkey auth:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: your-app-ingress
  annotations:
    # Auth configuration
    nginx.ingress.kubernetes.io/auth-url: "http://passkey-auth-service.passkey-auth.svc.cluster.local/auth"
    nginx.ingress.kubernetes.io/auth-signin: "https://auth.yourcompany.com"
    nginx.ingress.kubernetes.io/auth-response-headers: "X-Auth-User,X-Auth-User-ID"

    # SSL configuration
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  tls:
  - hosts:
    - app.yourcompany.com
    secretName: your-app-tls
  rules:
  - host: app.yourcompany.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: your-app-service
            port:
              number: 80

Step 5: Set Up Monitoring (Optional)

Health Checks

The service includes health checks at /health. Configure monitoring:

# Add to your monitoring stack
- job_name: 'passkey-auth'
  static_configs:
  - targets: ['passkey-auth-service.passkey-auth.svc.cluster.local:80']
  metrics_path: '/health'

Log Aggregation

Configure log forwarding to your logging system:

kubectl logs -f deployment/passkey-auth -n passkey-auth | your-log-forwarder

Step 6: Backup Strategy

Database Backup

Set up regular backups of the SQLite database:

# Create a backup cronjob
apiVersion: batch/v1
kind: CronJob
metadata:
  name: passkey-auth-backup
  namespace: passkey-auth
spec:
  schedule: "0 2 * * *"  # Daily at 2 AM
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: backup
            image: alpine
            command:
            - /bin/sh
            - -c
            - |
              cp /data/passkey-auth.db /backup/passkey-auth-$(date +%Y%m%d).db
              # Upload to your backup storage
            volumeMounts:
            - name: data
              mountPath: /data
            - name: backup
              mountPath: /backup
          restartPolicy: OnFailure
          volumes:
          - name: data
            persistentVolumeClaim:
              claimName: passkey-auth-storage
          - name: backup
            # Configure your backup storage volume

Security Checklist

• HTTPS enforced for all endpoints
• Session secret is randomly generated and secure
• CORS origins are specifically configured (not "*")
• WebAuthn RP ID matches your domain exactly
• Network policies restrict pod-to-pod communication
• Regular security updates applied
• Database backups are encrypted and tested
• Access logs are monitored
• Kubernetes RBAC is properly configured

Troubleshooting

Common Production Issues

1. WebAuthn Registration Fails:

   • Verify RP ID matches domain exactly
   • Ensure HTTPS is properly configured
   • Check browser developer console for errors

2. Auth Backend Returns 502:

   • Verify service is running: kubectl get pods -n passkey-auth
   • Check service connectivity: kubectl get svc -n passkey-auth
   • Review nginx ingress logs

3. Session Issues:

   • Verify session secret is consistent across restarts
   • Check cookie domain settings
   • Ensure persistent storage is working

Debug Commands

# Check service status
kubectl get all -n passkey-auth

# View logs
kubectl logs -f deployment/passkey-auth -n passkey-auth

# Test auth endpoint
kubectl exec -it deployment/passkey-auth -n passkey-auth -- wget -O- http://localhost:8080/health

# Check ingress
kubectl describe ingress -n passkey-auth

# Port forward for testing
kubectl port-forward svc/passkey-auth-service 8080:80 -n passkey-auth

Scaling Considerations

High Availability

For high availability, consider:

1. Multiple Replicas: Increase replica count in deployment
2. Session Storage: Use Redis for shared session storage
3. Database: Consider PostgreSQL for better concurrent access
4. Load Balancing: Ensure proper session affinity

Performance Tuning

1. Resource Limits: Adjust based on usage patterns
2. Database Optimization: Regular VACUUM for SQLite
3. Caching: Add caching layer for frequently accessed data

Updates and Maintenance

Rolling Updates

# Update the image
kubectl set image deployment/passkey-auth passkey-auth=passkey-auth:v1.1.0 -n passkey-auth

# Monitor rollout
kubectl rollout status deployment/passkey-auth -n passkey-auth

# Rollback if needed
kubectl rollout undo deployment/passkey-auth -n passkey-auth

Database Migrations

For schema changes, implement migration scripts and run them during maintenance windows.

---

This production guide ensures a secure, reliable deployment of Passkey Auth in your Kubernetes environment.