authelia/docs/CI_CD_VAULT_SETUP.md

CI/CD Vault Setup & Secret Management

This guide covers managing secrets in your Woodpecker CI vault for Authelia deployment.

🔑 Required Vault Secrets

Your Woodpecker CI vault must contain 12 total secrets for proper Authelia deployment:

Core Secrets (5)

Variable Name	Description	Generation Method
AUTHENTICATION_BACKEND_LDAP_PASSWORD	LDAP authentication password	./generate-secrets.sh
IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET	Password reset JWT secret	./generate-secrets.sh
STORAGE_ENCRYPTION_KEY	Database encryption key	./generate-secrets.sh
SESSION_SECRET	Session encryption secret	./generate-secrets.sh
NOTIFIER_SMTP_PASSWORD	SMTP email notifications	Manual configuration

OIDC Secrets (3)

Variable Name	Description	Generation Method
IDENTITY_PROVIDERS_OIDC_HMAC_SECRET	OIDC HMAC signing secret	./generate-secrets.sh
IDENTITY_PROVIDERS_OIDC_ISSUER_PRIVATE_KEY	OIDC token signing private key (RSA)	./generate-secrets.sh
IDENTITY_PROVIDERS_OIDC_JWKS_KEY	OIDC JWKS validation key (RSA)	./generate-secrets.sh

OAuth Client Secrets (4)

Variable Name	Description	Generation Method
CLIENT_SECRET_HEADSCALE	Headscale VPN OIDC client	./generate-secrets.sh
CLIENT_SECRET_HEADADMIN	Headscale admin OIDC client	./generate-secrets.sh
CLIENT_SECRET_PORTAINER	Portainer OAuth client	./scripts/generate-oauth-secrets.sh
CLIENT_SECRET_GITEA	Gitea OAuth client	./scripts/generate-oauth-secrets.sh

🚀 Setup Process

1. Generate Core Secrets

# Generate main Authelia secrets (10 secrets)
./generate-secrets.sh

2. Generate OAuth Client Secrets

# Generate OAuth client secrets (2 additional secrets)
./scripts/generate-oauth-secrets.sh

3. Update CI/CD Vault

Using Woodpecker Web Interface

1. Go to your repository in Woodpecker CI
2. Navigate to Settings → Secrets
3. Add each secret with the exact variable name
4. Copy values from generated secret files

Using Woodpecker CLI

# Install Woodpecker CLI if not already installed
curl -L https://github.com/woodpecker-ci/woodpecker/releases/latest/download/woodpecker-cli_linux_amd64.tar.gz | tar zx
sudo mv woodpecker-cli /usr/local/bin/

# Configure CLI
export WOODPECKER_SERVER=https://your-woodpecker-server.com
export WOODPECKER_TOKEN=your-api-token

# Update all secrets (example commands)
woodpecker secret update --repository your-repo --name CLIENT_SECRET_PORTAINER --value "$(cat secrets/clients/portainer-secret.txt)"
woodpecker secret update --repository your-repo --name CLIENT_SECRET_GITEA --value "$(cat secrets/clients/gitea-secret.txt)"

🔄 Secret Rotation

Full Secret Rotation (Rare)

⚠️ WARNING: This causes service downtime and invalidates all sessions

# Regenerate all secrets
./generate-secrets.sh

# Update all 10 core secrets in CI vault
# Deploy immediately to avoid extended downtime

OAuth Client Secret Rotation (Safe)

# Regenerate OAuth client secrets only
./scripts/generate-oauth-secrets.sh

# Update CLIENT_SECRET_PORTAINER and CLIENT_SECRET_GITEA in vault
# Deploy when convenient

🛡️ Security Best Practices

Secret Storage

• Never commit secrets to git (automatically gitignored)
• Use secure transmission when copying to CI vault
• Delete local secret files after updating vault (optional)
• Rotate secrets periodically (recommended quarterly)

Access Control

• Limit vault access to deployment administrators only
• Use separate secrets for development vs production
• Monitor secret access in CI/CD logs
• Audit secret usage regularly

Backup and Recovery

• Document secret locations in secure password manager
• Test recovery procedures before emergencies
• Keep vault backups according to your backup policy
• Plan for secret compromise scenarios

🔍 Verification

Check Secret Access

# Verify secrets are accessible in deployment
ssh macmini7 'docker service logs authelia_authelia | grep -i "secret\|error"'

# Check for missing secrets
ssh macmini7 'docker service logs authelia_authelia | grep -i "failed\|missing"'

Test OAuth Integration

# Test OAuth endpoint accessibility
curl -s https://login.nixc.us/.well-known/openid_configuration | jq .

# Verify client configurations
ssh macmini7 'docker service logs authelia_authelia | grep -i "oidc\|oauth"'

🚨 Troubleshooting

Common Issues

Secret Not Found

Error: secret not found: CLIENT_SECRET_PORTAINER

Solution: Verify secret name exactly matches in CI vault

Invalid Secret Format

Error: failed to parse RSA private key

Solution: Regenerate OIDC secrets with proper formatting

Service Won't Start

Error: configuration validation failed

Solution: Check all 12 secrets are present in vault

Emergency Recovery

Lost Access to Vault

1. Contact CI/CD administrator for vault access
2. Regenerate all secrets with generation scripts
3. Update vault immediately with new values
4. Redeploy services to use new secrets

Compromised Secrets

1. Rotate affected secrets immediately
2. Update CI/CD vault with new values
3. Deploy new secrets as soon as possible
4. Monitor for unauthorized access in logs
5. Review access logs for compromise timeline

📞 Support

CI/CD Vault Issues

• Check vault permissions and access rights
• Verify secret names match exactly (case-sensitive)
• Confirm vault backup and recovery procedures
• Test secret retrieval in deployment pipeline

Secret Generation Issues

• Ensure OpenSSL is available for key generation
• Check file permissions in secrets directory
• Verify gitignore is properly configured
• Confirm script execution permissions

Deployment Issues

• Monitor deployment logs for secret-related errors
• Check Docker Swarm secret creation
• Verify Authelia configuration template processing
• Test service connectivity after deployment