🔐 Passkey Auth for Kubernetes Ingress Controllers

A WebAuthn-based passkey authentication provider that integrates with ingress controllers. Currently supports Kubernetes Nginx Ingress Controller and Traefik Ingress Controller. Provides secure, passwordless authentication using passkeys (FIDO2/WebAuthn) as an auth backend.

TLDR;

Log in Apps without typing password or going through 3rd Party Oauth!

I use it for signing into my home lab apps.

🎬 Demo

✨ Features

• Passwordless Authentication: Uses WebAuthn/FIDO2 passkeys for secure authentication
• Ingress Controller Integration: Works as auth backend for Nginx Ingress (auth_request) and Traefik Ingress (ForwardAuth)
• User Management: An simple Admin interface for managing users and approval status
• Kubernetes Native: Designed for Kubernetes deployment with persistent storage

Security Benefits

• No passwords stored - Only WebAuthn public keys
• Email-based access control - Restrict registration to specific domains/emails
• Phishing resistant - WebAuthn is tied to the domain
• MFA built-in - Passkeys require user presence and verification
• Session security - Secure cookie-based sessions

🚀 Quick Start

Using Helm Chart (Recommended)

# Add the Helm repository
helm repo add passkey-auth https://wahyd4.github.io/passkey-auth
helm repo update

# Install with your values
helm upgrade --install my-passkey-auth -n home-apps -f my-values.yaml  passkey-auth/passkey-auth

See the Helm Chart README for detailed configuration options.

Test with Docker

docker run --name passkey-auth -d -p 8080:8080 -e ADMIN_EMAIL="admin@example.com"  ghcr.io/wahyd4/passkey-auth:main

Local Development

# Install dependencies and run locally
go mod download
go run main.go

# Access at http://localhost:8080

Setup Your App's Ingress

Nginx Ingress Controller

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: your-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/auth-url: "https://your-passkey-auth.com/auth"
    nginx.ingress.kubernetes.io/auth-signin: "https://your-passkey-auth.com/?redirect=https%3A%2F%2F$host$request_uri"
    nginx.ingress.kubernetes.io/auth-response-headers: "X-Auth-User,X-Auth-Email"
spec:
  rules:
  - host: your-app.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: your-app-service
            port:
              number: 80

Traefik Ingress Controller

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: your-app-ingress
  annotations:
    traefik.ingress.kubernetes.io/router.middlewares: default-passkey-auth@kubernetescrd
spec:
  rules:
  - host: your-app.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: your-app-service
            port:
              number: 80
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: passkey-auth
spec:
  forwardAuth:
    address: https://your-passkey-auth.com/auth
    authRequestHeaders:
      - "X-Forwarded-Method"
      - "X-Forwarded-Proto"
      - "X-Forwarded-Host"
      - "X-Forwarded-Uri"
      - "X-Forwarded-For"
    authResponseHeaders:
      - "X-Auth-User"
      - "X-Auth-Email"
    authResponseHeadersRegex: "^X-"

👥 User Management

Navigate to https:///your-passkey-auth.com to access the admin interface with three tabs:

• Register User: Register new users with passkeys
• Test Login: Test authentication
• Manage Users: View and manage all users with ADMIN_USER email address

Configuration

# config.yaml
auth:
  require_approval: true    # Require admin approval for new users
  allowed_emails:           # Email allowlist (empty = allow all)
    - "admin@company.com"
    - "user@company.com"

Check config.example.yaml for more details

🔧 Development

Local Development

# Install dependencies and run locally
go mod download
go run main.go

# Access at http://localhost:8080

Auth Endpoint Behavior

The /auth endpoint automatically adapts to work with both Nginx and Traefik ingress controllers:

For Nginx auth_request:

• Authenticated users: Returns 200 OK with user headers
• Unauthenticated users: Returns 401 Unauthorized

For Traefik ForwardAuth:

• Authenticated users: Returns 200 OK with user headers
• Unauthenticated users (with redirect param): Returns 302 Found with Location header pointing to login page
• Unauthenticated users (without redirect param): Returns 401 Unauthorized (fallback for Nginx)

The endpoint detects the ingress controller type by checking for query parameters like rd or redirect that Traefik typically includes.

Key API Endpoints

Endpoint	Method	Description
/api/register/begin	POST	Start passkey registration
/api/register/finish	POST	Complete passkey registration
/api/login/begin	POST	Start passkey authentication
/api/login/finish	POST	Complete passkey authentication
/auth	GET	Auth check endpoint for ingress controllers
/api/users	GET/POST	List/create users
/health	GET	Health check

📄 License

Apache License 2.0