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 | `"720h"` | Token validity duration (0 = never expires) |
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 = "720h"  # 30 days, or "0" for never
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 720h
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:
125
126```bash
127# Never expires (for CI/CD)
128gordon auth token generate --subject ci --expiry 0
129
130# Expires in 30 days
131gordon auth token generate --subject temp --expiry 720h
132
133# Expires in 24 hours
134gordon auth token generate --subject short --expiry 24h
135```
136
137## Instance-Specific Tokens
138
139Tokens are signed with the `token_secret`, which is unique to each Gordon instance. This means:
140
141- Tokens from one Gordon instance won't work on another
142- Changing the `token_secret` invalidates all existing tokens
143- Each environment (dev, staging, prod) should have different secrets
144
145## Examples
146
147### CI/CD Setup
148
149```toml
150[secrets]
151backend = "pass"
152
153[registry_auth]
154enabled = true
155type = "token"
156token_secret = "gordon/registry/token_secret"
157```
158
159```bash
160# Generate CI token
161gordon auth token generate --subject github-actions --scopes push,pull --expiry 0
162
163# Token output:
164# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
165```
166
167In GitHub Actions:
168```yaml
169- name: Login to Gordon Registry
170  run: docker login -u github-actions -p ${{ secrets.GORDON_TOKEN }} ${{ secrets.GORDON_REGISTRY }}
171```
172
173### Development Setup
174
175```toml
176[registry_auth]
177enabled = false  # Disable for local development
178```
179
180### Production with Password
181
182```toml
183[secrets]
184backend = "pass"
185
186[registry_auth]
187enabled = true
188type = "password"
189username = "deploy"
190password_hash = "gordon/registry/password_hash"
191```
192
193## Internal Registry Auth
194
195Gordon generates internal credentials automatically when auth is enabled. These are used for loopback pulls when deploying containers and are regenerated on each restart.
196
197## Related
198
199- [Secrets Configuration](./secrets.md)
200- [CLI Commands](../cli/commands.md)
201- [GitHub Actions Deployment](../deployment/github-actions.md)