1# Authentication Commands
2
3Manage Gordon server authentication tokens.
4
5## gordon auth
6
7### Subcommands
8
9| Subcommand | Description |
10|------------|-------------|
11| `login` | Store a token for a remote Gordon server |
12| `show-token` | Print the stored token for a remote |
13| `logout` | Remove stored token for a remote |
14| `status` | Check authentication session status |
15| `token generate` | Generate a new JWT token |
16| `token list` | List all stored tokens |
17| `token revoke` | Revoke a token by ID (use `--all` to revoke all tokens) |
18| `internal` | Show internal registry credentials |
19
20---
21
22## gordon auth login
23
24Store a pre-generated token for a remote Gordon server.
25
26```bash
27gordon auth login --token <token> [options]
28```
29
30### Options
31
32| Option | Description |
33|--------|-------------|
34| `-t, --token` | **Required.** Authentication token to store |
35
36Use the global `--remote, -r` flag to target a specific remote. See [CLI Overview](./index.md).
37
38### Description
39
40Stores a token for use with a remote Gordon server. The `--token` flag is required — generate a token on the server with `gordon auth token generate`.
41
42When [pass](https://www.passwordstore.org/) is available, the token is stored encrypted at `gordon/remotes/<name>/token` and plaintext fields are cleared from `remotes.toml`. When `pass` is unavailable, the token is stored in plaintext with a warning.
43
44The token is verified against `/admin/status` on a best-effort basis.
45
46### Examples
47
48```bash
49gordon auth login --token <token>
50gordon auth login --remote prod --token <token>
51```
52
53### Output
54
55When `pass` is available:
56
57```text
58Token stored in pass for remote 'prod'
59```
60
61When `pass` is not available:
62
63```text
64Warning: 'pass' not available. Storing token in plaintext config. Consider installing pass (https://www.passwordstore.org/) for secure token storage.
65Token stored for remote 'prod'
66```
67
68---
69
70## gordon auth show-token
71
72Print the stored token for a remote.
73
74```bash
75gordon auth show-token [--remote <name>]
76```
77
78Output is the raw token string, suitable for piping. Returns an error if no token is stored.
79
80```bash
81gordon auth show-token
82gordon auth show-token --remote prod
83gordon auth show-token | pbcopy  # copy to clipboard
84```
85
86---
87
88## gordon auth logout
89
90Remove the stored token for a remote.
91
92```bash
93gordon auth logout [--remote <name>] [--revoke]
94```
95
96| Option | Description |
97|--------|-------------|
98| `--revoke` | Also revoke the token server-side (not yet implemented) |
99
100Use the global `--remote, -r` flag to target a specific remote. See [CLI Overview](./index.md).
101
102Deletes the token from pass and clears token fields in `remotes.toml`.
103
104---
105
106## gordon auth token generate
107
108Generate a new JWT authentication token for registry access.
109
110```bash
111gordon auth token generate --subject <name> [options]
112```
113
114### Options
115
116| Option | Default | Description |
117|--------|---------|-------------|
118| `--subject` | (required) | Username/subject for the token |
119| `--scopes` | `push,pull` | Comma-separated scopes |
120| `--expiry` | `30d` | Duration until expiry (0 = never) |
121| `-c, --config` | Auto | Path to config file |
122
123### Duration Format
124
125Supports human-friendly duration units:
126
127| Unit | Description | Example |
128|------|-------------|---------|
129| `d` | Days (24 hours) | `30d` |
130| `w` | Weeks (7 days) | `2w` |
131| `M` | Months (30 days) | `6M` |
132| `y` | Years (365 days) | `1y` |
133
134Compound durations are also supported: `1y6M`, `2w3d`, `1d12h`
135
136Standard Go durations also work: `24h`, `30m`, `1h30m`
137
138### Scopes
139
140Registry scopes: `push`, `pull`, `push,pull`
141
142Admin scopes: `admin:*:*`, `admin:routes:read`, `admin:routes:write`, `admin:config:read`, `admin:config:write`, `admin:status:read`, `admin:secrets:read`, `admin:secrets:write`
143
144Combine scopes with commas:
145
146```bash
147gordon auth token generate --subject admin --scopes "push,pull,admin:*:*" --expiry 0
148```
149
150### Examples
151
152```bash
153# CI token that never expires
154gordon auth token generate --subject github-actions --expiry 0
155
156# Read-only token for 30 days
157gordon auth token generate --subject reader --scopes pull --expiry 30d
158
159# Push-only token for 1 year
160gordon auth token generate --subject builder --scopes push --expiry 1y
161
162# Temporary token (24 hours)
163gordon auth token generate --subject temp --expiry 24h
164
165# Full admin access token
166gordon auth token generate --subject admin --scopes "push,pull,admin:*:*" --expiry 6M
167
168# Read-only admin token
169gordon auth token generate --subject monitor --scopes "admin:status:read" --expiry 30d
170```
171
172### Output
173
174```
175Token generated successfully!
176Subject: github-actions
177Scopes: push, pull
178Expiry: never
179
180Token (use as password with docker login):
181eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
182
183Usage: docker login -u github-actions -p <token> <registry>
184```
185
186---
187
188## gordon auth token list
189
190List all stored authentication tokens.
191
192```bash
193gordon auth token list [options]
194```
195
196### Output
197
198```
199ID                                    Subject               Expires               Revoked
200------------------------------------------------------------------------------------------
201a1b2c3d4-e5f6-7890-abcd-ef1234567890  github-actions        never                 no
202b2c3d4e5-f6a7-8901-bcde-f12345678901  deploy-bot            2024-02-15 10:30      no
203c3d4e5f6-a7b8-9012-cdef-123456789012  old-token             2024-01-01 00:00      yes
204```
205
206---
207
208## gordon auth token revoke
209
210Revoke a token by its ID.
211
212```bash
213gordon auth token revoke <token-id> [options]
214gordon auth token revoke --all  # Revoke all tokens
215```
216
217### Example
218
219```bash
220gordon auth token revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
221```
222
223### Output
224
225```
226Token a1b2c3d4-e5f6-7890-abcd-ef1234567890 has been revoked.
227```
228
229---
230
231## gordon auth internal
232
233Display the auto-generated internal registry credentials.
234
235```bash
236gordon auth internal
237```
238
239Gordon generates temporary credentials for loopback-only communication with its local registry. These credentials are useful for manual recovery when debugging deployment issues.
240
241When registry auth is enabled, Gordon also generates a separate service token for its own registry-domain pulls. That token is not exposed via the CLI.
242
243### Output
244
245```
246Internal Registry Credentials
247==============================
248Username: gordon-internal
249Password: 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
250
251Usage:
252  docker login localhost:5000 -u gordon-internal -p 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
253```
254
255### Notes
256
257- Credentials are regenerated each time Gordon starts
258- Only available while Gordon is running
259- Used for manual `docker pull` from the local registry during debugging
260- Separate from the service token used by Gordon core for registry-domain pulls
261
262### Use Cases
263
264- Debugging image pull failures
265- Manual recovery after deployment issues
266- Inspecting images in the local registry
267
268---
269
270## Token Scopes
271
272| Scope | Permission |
273|-------|------------|
274| `push` | Push images to registry |
275| `pull` | Pull images from registry |
276| `push,pull` | Both push and pull (default) |
277| `admin:*:*` | Full admin access |
278| `admin:routes:read` | Read-only routes access |
279| `admin:routes:write` | Routes write access |
280| `admin:config:read` | Read-only config access |
281| `admin:config:write` | Config write access |
282| `admin:status:read` | Read-only status/health |
283| `admin:secrets:read` | List secret keys |
284| `admin:secrets:write` | Set/delete secrets |
285
286## Token Expiry Formats
287
288| Format | Duration |
289|--------|----------|
290| `0` | Never expires |
291| `24h` | 24 hours |
292| `720h` | 30 days |
293| `8760h` | 1 year |
294
295---
296
297## Workflow Examples
298
299### CI/CD Setup
300
301```bash
302# Generate token for CI
303gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
304
305# Save token as CI secret
306# GitHub: Settings > Secrets > New repository secret
307# GitLab: Settings > CI/CD > Variables
308```
309
310### Docker Login
311
312```bash
313# Using generated token
314docker login -u ci-bot -p <token> registry.mydomain.com
315
316# In CI/CD
317echo "$GORDON_TOKEN" | docker login -u ci-bot --password-stdin registry.mydomain.com
318```
319
320### Token Rotation
321
322```bash
323# Generate new token
324gordon auth token generate --subject ci-bot --expiry 0
325
326# Update CI secrets with new token
327
328# Revoke old token
329gordon auth token revoke <old-token-id>
330```
331
332### Token-only Setup
333
334```bash
335# Create token secret
336pass insert gordon/auth/token_secret
337# Enter a random 32+ character string
338
339# Configure gordon.toml
340[auth]
341enabled = true
342secrets_backend = "pass"
343token_secret = "gordon/auth/token_secret"
344
345# Generate a deploy token
346gordon auth token generate --subject deploy --scopes "push,pull" --expiry 0
347```
348
349## Related
350
351- [CLI Overview](./index.md)
352- [Authentication Configuration](../config/auth.md)