1# Registry Authentication
2
3Secure your container registry with password or token-based authentication.
4
5## Configuration
6
7```toml
8[registry_auth]
9enabled = true
10type = "token"  # "password" or "token"
11
12# For token auth:
13token_secret = "gordon/registry/token_secret"  # Path in secrets backend
14token_expiry = "720h"                          # Duration or 0 for never
15
16# For password auth:
17# username = "deploy"
18# password_hash = "gordon/registry/password_hash"  # Path in secrets backend
19```
20
21## Options
22
23| Option | Type | Default | Description |
24|--------|------|---------|-------------|
25| `enabled` | bool | `false` | Enable registry authentication |
26| `type` | string | `"password"` | Auth type: `"password"` or `"token"` |
27| `username` | string | - | Username for password auth |
28| `password_hash` | string | - | Path to bcrypt hash in secrets backend |
29| `token_secret` | string | - | Path to JWT signing secret in secrets backend |
30| `token_expiry` | string | `"30d"` | Token validity duration (0 = never expires). Supports: d (days), w (weeks), M (months), y (years) |
31
32## Authentication Types
33
34### Token Authentication (Recommended)
35
36JWT-based authentication, ideal for CI/CD pipelines:
37
38```toml
39[secrets]
40backend = "pass"
41
42[registry_auth]
43enabled = true
44type = "token"
45token_secret = "gordon/registry/token_secret"
46token_expiry = "30d"  # 30 days, or "0" for never. Also: 1y, 2w, 6M
47```
48
49**Setup:**
50```bash
51# Create token secret (random 32+ characters)
52pass insert gordon/registry/token_secret
53
54# Generate a token
55gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
56```
57
58**Usage:**
59```bash
60# Docker login with token
61docker login -u ci-bot -p <token> registry.mydomain.com
62```
63
64**Token Management:**
65```bash
66# List all tokens
67gordon auth token list
68
69# Revoke a token
70gordon auth token revoke <token-id>
71```
72
73### Password Authentication
74
75Simple username/password authentication:
76
77```toml
78[secrets]
79backend = "pass"
80
81[registry_auth]
82enabled = true
83type = "password"
84username = "deploy"
85password_hash = "gordon/registry/password_hash"
86```
87
88**Setup:**
89```bash
90# Generate bcrypt hash
91gordon auth password hash
92# Enter password when prompted
93
94# Store hash in secrets backend
95pass insert gordon/registry/password_hash
96# Paste the bcrypt hash
97```
98
99**Usage:**
100```bash
101docker login -u deploy -p <password> registry.mydomain.com
102```
103
104## Token Scopes
105
106Tokens can have different permission levels:
107
108| Scope | Permission |
109|-------|------------|
110| `push` | Push images to registry |
111| `pull` | Pull images from registry |
112| `push,pull` | Both push and pull (default) |
113
114```bash
115# Pull-only token (for read-only access)
116gordon auth token generate --subject reader --scopes pull --expiry 30d
117
118# Push-only token (for CI builds)
119gordon auth token generate --subject builder --scopes push --expiry 0
120```
121
122## Token Expiry
123
124Control how long tokens remain valid. Supports human-friendly units:
125- `d` - days (24 hours)
126- `w` - weeks (7 days)
127- `M` - months (30 days)
128- `y` - years (365 days)
129
130Compound durations work too: `1y6M`, `2w3d`
131
132```bash
133# Never expires (for CI/CD)
134gordon auth token generate --subject ci --expiry 0
135
136# Expires in 1 year
137gordon auth token generate --subject deploy --expiry 1y
138
139# Expires in 30 days
140gordon auth token generate --subject temp --expiry 30d
141
142# Expires in 2 weeks
143gordon auth token generate --subject short --expiry 2w
144```
145
146## Instance-Specific Tokens
147
148Tokens are signed with the `token_secret`, which is unique to each Gordon instance. This means:
149
150- Tokens from one Gordon instance won't work on another
151- Changing the `token_secret` invalidates all existing tokens
152- Each environment (dev, staging, prod) should have different secrets
153
154## Examples
155
156### CI/CD Setup
157
158```toml
159[secrets]
160backend = "pass"
161
162[registry_auth]
163enabled = true
164type = "token"
165token_secret = "gordon/registry/token_secret"
166```
167
168```bash
169# Generate CI token
170gordon auth token generate --subject github-actions --scopes push,pull --expiry 0
171
172# Token output:
173# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
174```
175
176In GitHub Actions:
177```yaml
178- name: Login to Gordon Registry
179  run: docker login -u github-actions -p ${{ secrets.GORDON_TOKEN }} ${{ secrets.GORDON_REGISTRY }}
180```
181
182### Development Setup
183
184```toml
185[registry_auth]
186enabled = false  # Disable for local development
187```
188
189### Production with Password
190
191```toml
192[secrets]
193backend = "pass"
194
195[registry_auth]
196enabled = true
197type = "password"
198username = "deploy"
199password_hash = "gordon/registry/password_hash"
200```
201
202## Internal Registry Auth
203
204Gordon generates internal credentials automatically when auth is enabled. These are used for loopback pulls when deploying containers and are regenerated on each restart.
205
206## Related
207
208- [Secrets Configuration](./secrets.md)
209- [CLI Commands](../cli/commands.md)
210- [GitHub Actions Deployment](../deployment/github-actions.md)