187 lines
6.2 KiB
Markdown
187 lines
6.2 KiB
Markdown
# 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
|
|
```bash
|
|
# Generate main Authelia secrets (10 secrets)
|
|
./generate-secrets.sh
|
|
```
|
|
|
|
### 2. Generate OAuth Client Secrets
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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**
|
|
|
|
```bash
|
|
# 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)
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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 |