Authentication Overview

​

Authentication System

• Optional Authentication - Run without auth for trusted environments, or enable it for multi-user deployments
• Multiple Providers - Support for local users, OIDC/SSO, and LDAP (Enterprise)
• Strong Security - Argon2id password hashing, secure session management, and optional 2FA
• Session Management - Configurable session timeouts with HttpOnly, Secure, and SameSite cookies

​

Edition Comparison

​

Security Features

​

Password Security

• Argon2id Hashing - Memory-hard algorithm resistant to GPU attacks
• Custom Parameters - 64MB memory cost, 3 iterations, 256-bit output
• Timing Attack Protection - Constant-time comparison prevents username enumeration

​

Session Security

• Cryptographically Secure Tokens - 256-bit random session IDs
• HttpOnly Cookies - Prevents XSS attacks from reading session tokens
• SameSite=Strict - CSRF protection
• Secure Flag - Automatic HTTPS detection via x-forwarded-proto header
• Configurable Timeouts - 1 hour to 7 days (default: 24 hours)

​

Rate Limiting

• Failed Login Protection - 5 attempts per 15 minutes
• 15 Minute Lockout - Automatic lockout after threshold
• IP + Username Tracking - Per-user rate limiting

​

Initial Setup

​

1. Enable Authentication

# Or enable via API
curl -X PUT http://localhost:8000/api/auth/settings \
  -H "Content-Type: application/json" \
  -d '{"authEnabled": true}'

​

2. Create First Admin User

curl -X POST http://localhost:8000/api/users \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your-secure-password",
    "email": "[email protected]"
  }'

​

3. Configure Session Timeout

• Minimum: 1 hour (3600 seconds)
• Maximum: 7 days (604800 seconds)
• Default: 24 hours (86400 seconds)

​

Authentication Flow

​

Local Authentication

1. User submits username and password
2. System verifies credentials using Argon2id
3. If 2FA enabled, user must provide TOTP code
4. Session created with secure cookie
5. User redirected to dashboard

​

OIDC/SSO Authentication

1. User clicks “Sign in with [Provider]”
2. Redirected to Identity Provider (IdP)
3. User authenticates with IdP
4. IdP redirects back with authorization code
5. Dockhand exchanges code for tokens
6. User account created/updated from claims
7. Session created and user logged in

​

LDAP Authentication

1. User submits username and password
2. System searches LDAP directory for user DN
3. Binds as user to verify password
4. Retrieves user attributes (email, display name)
5. Checks group membership for admin/role assignment
6. Local user account created/synced
7. Session created and user logged in

​

Configuration Files

• auth_settings - Global auth configuration
• users - Local user accounts
• sessions - Active user sessions
• oidc_config - OIDC provider configurations
• ldap_config - LDAP directory configurations (Enterprise)

​

Environment Variables

​

Public Endpoints

• /login - Login page
• /api/auth/login - Authentication endpoint
• /api/auth/logout - Logout endpoint
• /api/auth/session - Session validation
• /api/auth/settings - Auth configuration (read-only when auth disabled)
• /api/auth/providers - List available auth providers
• /api/auth/oidc/callback - OIDC callback handler
• /api/health - Health check endpoint
• /api/git/*/webhook - Git webhook receivers (signature verification)

​

Security Best Practices

​

For Production Deployments

1. Always Enable HTTPS
   • Use a reverse proxy (Traefik, Nginx, Caddy)
   • Set x-forwarded-proto: https header
   • Verify Secure flag is set on cookies
2. Use Strong Passwords
   • Minimum 12 characters
   • Mix of uppercase, lowercase, numbers, symbols
   • Consider using a password manager
3. Enable 2FA for Admins
   • All admin accounts should use TOTP
   • Store backup codes securely
   • Test recovery process
4. Configure Session Timeout
   • Balance security vs. convenience
   • Shorter timeouts (4 hours) for sensitive environments
   • Longer timeouts (7 days) for trusted networks
5. Monitor Authentication Logs
   • Review server logs for failed login attempts
   • Watch for unusual IP addresses
   • Enable audit logging (Enterprise)

​

For SSO Deployments

1. Disable Local Login
   • Set DISABLE_LOCAL_LOGIN=true
   • Forces all users through IdP
   • Prevents password-based attacks
2. Configure Role Mappings
   • Map IdP groups to Dockhand roles
   • Automate role assignment
   • Keep permissions in sync with IdP
3. Test Failure Scenarios
   • What happens if IdP is down?
   • Can admins still access via local account?
   • Consider keeping one local admin as backup

​

Troubleshooting

​

Login Loop on HTTP

# Set COOKIE_SECURE=false
docker run -e COOKIE_SECURE=false dockhand/dockhand:latest

​

Session Expires Immediately

# Query current settings
curl http://localhost:8000/api/auth/settings

# Update timeout to 7 days
curl -X PUT http://localhost:8000/api/auth/settings \
  -H "Content-Type: application/json" \
  -d '{"sessionTimeout": 604800}'

​

Can’t Create First User

# Check auth status
curl http://localhost:8000/api/auth/settings

# Enable auth
curl -X PUT http://localhost:8000/api/auth/settings \
  -d '{"authEnabled": true}'

​

Next Steps