# 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