1# Authentication Commands
2
3Manage Gordon server authentication tokens and passwords.
4
5## gordon auth
6
7### Subcommands
8
9| Subcommand | Description |
10|------------|-------------|
11| `login` | Authenticate with a remote Gordon server |
12| `token generate` | Generate a new JWT token |
13| `token list` | List all stored tokens |
14| `token revoke` | Revoke a token by ID (use `--all` to revoke all tokens) |
15| `password hash` | Generate bcrypt password hash |
16| `internal` | Show internal registry credentials |
17
18---
19
20## gordon auth login
21
22Authenticate with a remote Gordon server using password authentication.
23
24```bash
25gordon auth login [options]
26```
27
28### Options
29
30| Option | Description |
31|--------|-------------|
32| `-r, --remote` | Remote to authenticate with (defaults to active remote) |
33| `-u, --username` | Username for authentication |
34
35### Description
36
37This command prompts for your username and password, authenticates with the remote server's `/auth/password` endpoint, and stores the returned token in your remotes configuration.
38
39The token is a long-lived JWT (7 days) that's used for subsequent CLI operations against the remote.
40
41> **Note:** This command only works with servers that have password authentication configured (`username` + `password_hash`). For token-only servers, use `gordon remotes set-token` instead.
42
43### Examples
44
45```bash
46# Login using active remote
47gordon auth login
48
49# Login to specific remote
50gordon auth login --remote prod
51
52# Pre-fill username
53gordon auth login --username admin
54```
55
56### Output
57
58```
59Username: admin
60Password: ********
61Authenticating with prod...
62
63✓ Authentication successful!
64Token stored for remote 'prod'
65Expires in: 604800 seconds
66```
67
68---
69
70## gordon auth token generate
71
72Generate a new JWT authentication token for registry access.
73
74```bash
75gordon auth token generate --subject <name> [options]
76```
77
78### Options
79
80| Option | Default | Description |
81|--------|---------|-------------|
82| `--subject` | (required) | Username/subject for the token |
83| `--scopes` | `push,pull` | Comma-separated scopes |
84| `--expiry` | `30d` | Duration until expiry (0 = never) |
85| `-c, --config` | Auto | Path to config file |
86
87### Duration Format
88
89Supports human-friendly duration units:
90
91| Unit | Description | Example |
92|------|-------------|---------|
93| `d` | Days (24 hours) | `30d` |
94| `w` | Weeks (7 days) | `2w` |
95| `M` | Months (30 days) | `6M` |
96| `y` | Years (365 days) | `1y` |
97
98Compound durations are also supported: `1y6M`, `2w3d`, `1d12h`
99
100Standard Go durations also work: `24h`, `30m`, `1h30m`
101
102### Examples
103
104```bash
105# CI token that never expires
106gordon auth token generate --subject github-actions --expiry 0
107
108# Read-only token for 30 days
109gordon auth token generate --subject reader --scopes pull --expiry 30d
110
111# Push-only token for 1 year
112gordon auth token generate --subject builder --scopes push --expiry 1y
113
114# Temporary token (24 hours)
115gordon auth token generate --subject temp --expiry 24h
116
117# Token for 6 months
118gordon auth token generate --subject deploy --expiry 6M
119```
120
121### Output
122
123```
124Token generated successfully!
125Subject: github-actions
126Scopes: push, pull
127Expiry: never
128
129Token (use as password with docker login):
130eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
131
132Usage: docker login -u github-actions -p <token> <registry>
133```
134
135---
136
137## gordon auth token list
138
139List all stored authentication tokens.
140
141```bash
142gordon auth token list [options]
143```
144
145### Output
146
147```
148ID                                    Subject               Expires               Revoked
149------------------------------------------------------------------------------------------
150a1b2c3d4-e5f6-7890-abcd-ef1234567890  github-actions        never                 no
151b2c3d4e5-f6a7-8901-bcde-f12345678901  deploy-bot            2024-02-15 10:30      no
152c3d4e5f6-a7b8-9012-cdef-123456789012  old-token             2024-01-01 00:00      yes
153```
154
155---
156
157## gordon auth token revoke
158
159Revoke a token by its ID.
160
161```bash
162gordon auth token revoke <token-id> [options]
163gordon auth token revoke --all  # Revoke all tokens
164```
165
166### Example
167
168```bash
169gordon auth token revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
170```
171
172### Output
173
174```
175Token a1b2c3d4-e5f6-7890-abcd-ef1234567890 has been revoked.
176```
177
178---
179
180## gordon auth password hash
181
182Generate a bcrypt hash for password authentication.
183
184```bash
185gordon auth password hash
186```
187
188Interactively prompts for a password and outputs the bcrypt hash.
189
190### Output
191
192```
193Enter password: ********
194
195Bcrypt hash (store in your secrets backend):
196$2a$10$N9qo8uLOickgx2ZMRZoMye...
197
198Then reference the path in your config:
199  [auth]
200  username = "deploy"
201  password_hash = "gordon/auth/password_hash"
202  token_secret = "gordon/auth/token_secret"
203```
204
205---
206
207## gordon auth internal
208
209Display the auto-generated internal registry credentials.
210
211```bash
212gordon auth internal
213```
214
215Gordon generates temporary credentials for internal communication with its local registry. These credentials are useful for manual recovery when debugging deployment issues.
216
217### Output
218
219```
220Internal Registry Credentials
221==============================
222Username: gordon-internal
223Password: 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
224
225Usage:
226  docker login localhost:5000 -u gordon-internal -p 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
227```
228
229### Notes
230
231- Credentials are regenerated each time Gordon starts
232- Only available while Gordon is running
233- Used for manual `docker pull` from the local registry during debugging
234
235### Use Cases
236
237- Debugging image pull failures
238- Manual recovery after deployment issues
239- Inspecting images in the local registry
240
241---
242
243## Token Scopes
244
245| Scope | Permission |
246|-------|------------|
247| `push` | Push images to registry |
248| `pull` | Pull images from registry |
249| `push,pull` | Both push and pull (default) |
250
251## Token Expiry Formats
252
253| Format | Duration |
254|--------|----------|
255| `0` | Never expires |
256| `24h` | 24 hours |
257| `720h` | 30 days |
258| `8760h` | 1 year |
259
260---
261
262## Workflow Examples
263
264### CI/CD Setup
265
266```bash
267# Generate token for CI
268gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
269
270# Save token as CI secret
271# GitHub: Settings → Secrets → New repository secret
272# GitLab: Settings → CI/CD → Variables
273```
274
275### Docker Login
276
277```bash
278# Using generated token
279docker login -u ci-bot -p <token> registry.mydomain.com
280
281# In CI/CD
282echo "$GORDON_TOKEN" | docker login -u ci-bot --password-stdin registry.mydomain.com
283```
284
285### Token Rotation
286
287```bash
288# Generate new token
289gordon auth token generate --subject ci-bot --expiry 0
290
291# Update CI secrets with new token
292
293# Revoke old token
294gordon auth token revoke <old-token-id>
295```
296
297### Password Setup
298
299```bash
300# Generate hash
301gordon auth password hash
302# Enter: mypassword
303
304# Store in pass
305pass insert gordon/auth/password_hash
306# Paste: $2a$10$...
307
308# Create token secret
309pass insert gordon/auth/token_secret
310# Enter a random 32+ character string
311
312# Configure gordon.toml
313[auth]
314enabled = true
315secrets_backend = "pass"
316username = "deploy"
317password_hash = "gordon/auth/password_hash"
318token_secret = "gordon/auth/token_secret"
319```
320
321## Related
322
323- [CLI Overview](./index.md)
324- [Authentication Configuration](../config/auth.md)