Skip to content

Authentication

Jump to bottom
homelabforge edited this page Apr 5, 2026 · 4 revisions

Authentication

VulnForge has two separate authentication systems for different purposes.

Table of Contents

Overview

VulnForge uses dual authentication to separate browser access from API access:

System Purpose Method Location
User Authentication Browser login JWT session cookies Settings → Security → User Account
API Authentication External tools (TideWatch, scripts) API Keys Settings → Security → API Keys

Why Two Systems?

  • User Auth handles browser sessions (login page, JWT cookies, OIDC/SSO)
  • API Auth handles external integrations (API keys for scripts and automation)
  • Both can coexist - users login via browser, tools use API keys

User Authentication

Manages browser-based login for accessing the VulnForge web interface.

Features

  • Local Authentication - Username/password with Argon2id hashing
  • OIDC/SSO - Single sign-on via Authentik, Keycloak, etc.
  • JWT Sessions - Secure httpOnly cookies with 24-hour expiry
  • Setup Page - First-time account creation
  • Profile Management - Edit email, full name, change password

Configuration

Navigate to Settings → Security → User Account:

  • Edit Profile - Update email and full name
  • Change Password - Real-time validation (8+ chars, uppercase, lowercase, number, special)
  • Configure OIDC/SSO - Set up single sign-on with connection testing
  • Disable Authentication - Turn off browser login (returns to setup page on next visit)

OIDC/SSO Setup

Prerequisite: Set Public Base URL in Settings before enabling OIDC. This is the external URL users access VulnForge from (e.g., https://vulnforge.yourdomain.com). OIDC redirect URIs are built from this setting.

  1. Navigate to Settings and set Public Base URL
  2. Click Configure OIDC/SSO in User Account card
  3. Enter your OIDC provider details:
    • Issuer URL: https://authentik.example.com/application/o/vulnforge/
    • Client ID: Your OIDC client ID
    • Client Secret: Your OIDC client secret
  4. Click Test Connection to validate configuration
  5. Click Save to enable OIDC
  6. In your OIDC provider, set the redirect URI to: {public_base_url}/api/v1/user-auth/oidc/callback

Supported Providers:

  • Authentik
  • Keycloak
  • Auth0
  • Okta
  • Any OIDC-compliant provider

How It Works

First Time:

  1. Navigate to VulnForge URL
  2. Setup page appears with a bootstrap token field
  3. Enter the token from container logs (docker logs vulnforge | grep "SETUP TOKEN")
  4. Create admin credentials (username, password, email)
  5. Login with credentials

Subsequent Access:

  1. Login page with local or SSO options
  2. Successful login creates JWT session cookie
  3. Cookie valid for 24 hours
  4. Automatic logout on expiry

Security Features

  • Bootstrap Token - First-run setup protected by one-time token (printed to container logs)
  • Argon2id Password Hashing - time_cost=2, memory_cost=102400, parallelism=8
  • JWT Security - HS256 algorithm, 256-bit secret, httpOnly + SameSite=Lax cookies
  • Session Invalidation - Password changes invalidate all active sessions immediately
  • Server-Side Logout - Logout denies the specific token server-side (not just cookie deletion)
  • Login Rate Limiting - 5 attempts per minute to prevent brute-force
  • CSRF Protection - 256-bit state tokens with 10-minute TTL (OIDC flow)
  • SSRF Protection - Blocks private IPs, localhost, cloud metadata endpoints
  • Nonce Validation - Prevents replay attacks on ID tokens

API Authentication

Manages API keys for external tools and automation.

Creating API Keys

Navigate to Settings → Security → API Keys:

  1. Click Create New Key
  2. Enter key details:
    • Name: Descriptive name (e.g., "TideWatch Production")
    • Description: Optional notes about usage
  3. Click Create Key
  4. ⚠️ Copy the key immediately - it won't be shown again!

Key Format

API keys use a secure format:

  • Prefix: vf_ for easy identification
  • Length: ~48 characters total
  • Entropy: 256 bits (32 bytes of randomness)
  • Example: vf_abc123XYZ789...secure_random_data

Using API Keys

Include the API key in the X-API-Key header:

curl Example:

curl -H "X-API-Key: vf_abc123XYZ789..." \
  http://localhost:14500/api/v1/containers

Python Example:

import requests

headers = {"X-API-Key": "vf_abc123XYZ789..."}
response = requests.get(
    "http://localhost:14500/api/v1/containers",
    headers=headers
)

JavaScript Example:

const response = await fetch('http://localhost:14500/api/v1/containers', {
  headers: {
    'X-API-Key': 'vf_abc123XYZ789...'
  }
});

Managing Keys

View Keys:

  • All active keys listed in Settings → Security → API Keys
  • Shows: Name, description, key prefix, created date, last used timestamp

Revoke Keys:

  1. Click trash icon next to key
  2. Confirm revocation
  3. Key immediately invalidated (soft delete)

Lost Keys:

  • Cannot recover lost keys (never stored in plaintext)
  • Create new key and revoke old one

Key Permissions

Currently: All API keys have admin access

Future Enhancements:

  • Per-key permission scopes (read-only vs read-write)
  • Key expiration dates (TTL)
  • Rate limiting per key

Security Features

  • Cryptographic Generation - Python secrets.token_urlsafe(32) for 256 bits entropy
  • SHA256 Hashing - Plaintext keys never stored in database
  • One-Time Display - Key shown only on creation, cannot be retrieved later
  • Soft Delete - Revoked keys kept in database for audit trail
  • Usage Tracking - Last used timestamp helps identify stale/compromised keys

Security Best Practices

User Authentication

  1. Use Strong Passwords

    • Minimum 8 characters
    • Include uppercase, lowercase, numbers, special characters
    • Don't reuse passwords from other services

  2. Enable OIDC/SSO

    • Centralized access control
    • MFA enforcement at provider level
    • Single-user application with simple admin/non-admin model

  3. Change Password Regularly

    • Quarterly password rotation recommended
    • Immediately after suspected compromise

API Authentication

  1. Rotate Keys Regularly

    • Create new key, update tools, revoke old key
    • Quarterly rotation recommended
    • Track last used timestamp to identify stale keys

  2. Use Descriptive Names

    • Name keys by purpose: "TideWatch Production", "GitHub Actions CI"
    • Add description with deployment details
    • Easier to identify keys during security audit

  3. Revoke Compromised Keys Immediately

    • Revoke any key suspected of compromise
    • Create new key with different value
    • Update all tools using the key

  4. Limit Key Distribution

    • One key per service/tool
    • Don't share keys across multiple tools
    • Easier to track usage and revoke if needed

  5. Store Keys Securely

    • Use environment variables, not hardcoded
    • Use secret managers (Vault, 1Password, etc.)
    • Never commit keys to version control

Network Security

Defense in Depth:

  1. User + API authentication (this page)
  2. Reverse proxy with TLS (Traefik)
  3. Firewall rules (only necessary ports)
  4. VPN or Tailscale (optional additional layer)

Compliance & Auditing

For regulated environments:

  • Enable OIDC/SSO with MFA enforcement
  • Review Activity logs regularly (Settings → Data → Activity Logs)
  • Audit API keys quarterly (check last used timestamps)
  • Document admin access justification
  • Rotate keys on schedule

Troubleshooting

User Authentication Issues

Can't Login:

  1. Verify username and password (case-sensitive)
  2. Check browser console for errors
  3. Clear cookies and try again
  4. Try incognito/private mode

OIDC/SSO Not Working:

  1. Verify Public Base URL is set in Settings (required for OIDC)
  2. Click Test Connection in OIDC config
  3. Check issuer URL is correct (with trailing slash)
  4. Verify client ID and secret
  5. Check OIDC provider logs for errors
  6. Ensure redirect URI matches: {public_base_url}/api/v1/user-auth/oidc/callback

VulnForge does not trust X-Forwarded-* headers for OIDC redirects. The Public Base URL setting is the sole source of truth.

Session Expired:

  • JWT sessions last 24 hours
  • Password changes invalidate all sessions immediately
  • After upgrading VulnForge, all sessions are invalidated (re-login once)
  • Login again to create new session

API Authentication Issues

401 Unauthorized:

  1. Verify X-API-Key header is present
  2. Check key value is correct (no extra spaces)
  3. Ensure key hasn't been revoked
  4. Check key in Settings → Security → API Keys

Key Not Working After Creation:

  1. Verify you copied the full key (48 characters)
  2. Check for copy-paste errors (trailing newlines, spaces)
  3. Test with simple curl command first
  4. Check VulnForge logs: docker logs vulnforge-backend | grep -i api

Lost API Key:

  • Cannot recover lost keys (never stored in plaintext)
  • Create new key in Settings → Security → API Keys
  • Update tool configuration with new key
  • Revoke old key to clean up

Debug Mode

Enable debug logging to troubleshoot authentication:

environment:
  LOG_LEVEL: DEBUG

Restart VulnForge and check logs:

docker logs vulnforge-backend | grep -i auth

Migration from Old System

VulnForge 3.x Users:

The authentication system was simplified in v4.0:

Removed:

  • Authentik ForwardAuth provider
  • Custom Headers provider
  • Basic Auth provider
  • Complex multi-provider configuration

Added:

  • Simple API key management UI
  • Database-backed keys with secure hashing
  • One-click create/revoke operations

Action Required:

  1. All old API keys are invalidated
  2. Create new API keys via Settings → Security → API Keys
  3. Update tools (TideWatch, scripts) with new keys
  4. Old auth_enabled and auth_provider settings disabled automatically

Next Steps

For advanced authentication scenarios (custom SSO, header-based auth), Traefik ForwardAuth can be configured at the reverse proxy level independently of VulnForge.

Clone this wiki locally