1# Secrets Configuration
2
3Configure how Gordon stores and retrieves sensitive data: auth secrets such as `token_secret` (this page) and app secret values (managed with `gordon apps secrets`, values in pass under `gordon/apps/<uuid>/<service>/<name>`).
4
5## Configuration
6
7The secrets backend is configured within the `[auth]` section:
8
9```toml
10[auth]
11secrets_backend = "pass"  # "pass", "sops", or "unsafe"
12```
13
14## Options
15
16| Option | Type | Default | Description |
17|--------|------|---------|-------------|
18| `secrets_backend` | string | `"unsafe"` | Secrets storage backend |
19
20## Backends
21
22### Pass (Recommended for Production)
23
24Uses the Unix password manager (`pass`) for secure secret storage:
25
26```toml
27[auth]
28secrets_backend = "pass"
29```
30
31**Setup:**
32```bash
33# Install pass
34sudo apt install pass
35
36# Initialize with GPG key
37pass init your-gpg-key-id
38
39# Store secrets
40pass insert gordon/auth/token_secret
41```
42
43**Usage in config:**
44```toml
45[auth]
46token_secret = "gordon/auth/token_secret"  # Path in pass store
47```
48
49**Benefits:**
50- GPG-encrypted storage
51- Version control friendly (encrypted files)
52- Standard Unix tooling
53- Works with team GPG keys
54
55### SOPS
56
57Uses Mozilla SOPS for encrypted file-based secrets:
58
59```toml
60[auth]
61secrets_backend = "sops"
62```
63
64**Setup:**
65```bash
66# Install sops
67brew install sops  # macOS
68# or download from https://github.com/getsops/sops/releases
69
70# Create encrypted secrets file
71sops secrets.yaml
72```
73
74**Benefits:**
75- Multiple encryption backends (AWS KMS, GCP KMS, Azure Key Vault, PGP)
76- YAML/JSON file encryption
77- Git-friendly (encrypted files in repo)
78
79**Security:**
80- Absolute paths are rejected to prevent arbitrary file access
81- Path traversal (`..`) is blocked
82- Only relative paths from your config directory are allowed
83
84### Unsafe (Development Only)
85
86Stores secrets as plain text files:
87
88```toml
89[auth]
90secrets_backend = "unsafe"
91```
92
93**Storage location:**
94```
95{data_dir}/secrets/
96├── gordon/
97│   └── auth/
98│       └── token_secret
99```
100
101**Usage:**
102```bash
103# Create secret
104mkdir -p ~/.gordon/secrets/gordon/auth
105echo "your-token-secret" > ~/.gordon/secrets/gordon/auth/token_secret
106```
107
108> **Warning:** Only use for local development. Secrets are stored in plain text.
109
110## App Secret Values
111
112App secret names are registered in the app manifest (`[services.<name>.secrets]` maps ENV name to secret name); values are written separately and stay in pass:
113
114```bash
115gordon apps secrets set blog --service web DATABASE_URL=...
116```
117
118Values affect the next deploy/restart, never running containers. Only key names are ever echoed back, never values. See [App Manifest](./apps.md) and [Apps CLI](../cli/apps.md).
119
120## Examples
121
122### Production with Pass
123
124```toml
125[auth]
126enabled = true
127secrets_backend = "pass"
128token_secret = "gordon/auth/token_secret"
129```
130
131```bash
132# Setup
133pass insert gordon/auth/token_secret
134# Enter a random 32+ character string
135
136# Generate tokens
137gordon auth token generate --subject deploy --expiry 0
138```
139
140### Development with Unsafe
141
142```toml
143[auth]
144enabled = false
145secrets_backend = "unsafe"
146```
147
148## Security Recommendations
149
1501. **Production**: Always use `pass` or `sops` backend
1512. **Never commit**: Don't commit unencrypted secrets to git (app files must never contain secret values)
1523. **Rotate regularly**: Regenerate tokens and passwords periodically
1534. **Least privilege**: Use separate secrets per environment
1545. **Path validation**: SOPS provider rejects absolute paths and path traversal attempts for security
155
156## Related
157
158- [Authentication](./auth.md)
159- [App Manifest](./apps.md)
160- [Configuration Overview](./index.md)