1# Authentication
2
3Configure authentication for the Gordon registry and Admin API.
4
5Authentication is enabled by default. Gordon will not start without a valid `token_secret` (or `GORDON_AUTH_TOKEN_SECRET`).
6
7## Pick a Mode
8
9### Token-only (recommended for CI/CD)
10
11```toml
12[auth]
13enabled = true
14secrets_backend = "pass"
15token_secret = "gordon/auth/token_secret"
16token_expiry = "30d"
17```
18
19### Password + Token (interactive + CI/CD)
20
21```toml
22[auth]
23enabled = true
24secrets_backend = "pass"
25username = "deploy"
26password_hash = "gordon/auth/password_hash"
27token_secret = "gordon/auth/token_secret"
28```
29
30Token auth always works. Adding `username` + `password_hash` enables interactive login.
31
32## Options
33
34| Option | Type | Default | Description |
35|--------|------|---------|-------------|
36| `enabled` | bool | `true` | Enable authentication |
37| `secrets_backend` | string | `"unsafe"` | Secrets backend: `"pass"`, `"sops"`, or `"unsafe"` |
38| `token_secret` | string | - | **Required.** Path to JWT signing secret in secrets backend |
39| `token_expiry` | string | `"30d"` | Token validity duration (0 = never expires) |
40| `username` | string | - | Username for password auth (optional) |
41| `password_hash` | string | - | Path to bcrypt hash in secrets backend (optional) |
42
43## Secrets Backends
44
45`token_secret` and `password_hash` are read through the configured backend:
46
47| Backend | Description |
48| --------- | ------------- |
49| `pass` | Unix password manager (GPG-encrypted) |
50| `sops` | Mozilla SOPS encrypted files |
51| `unsafe` | Plain text files (development only) |
52
53See [Secret Providers](./secrets.md) for setup details.
54
55## Environment Variable
56
57`GORDON_AUTH_TOKEN_SECRET` overrides `token_secret` in the config. If you don’t set the env var, `token_secret` is loaded from the configured secrets backend (including `pass`).
58
59```bash
60export GORDON_AUTH_TOKEN_SECRET="your-32-character-secret-here"
61gordon serve
62```
63
64## Setup
65
66### Token-only setup
67
68```bash
69# Create token secret (random 32+ characters)
70pass insert gordon/auth/token_secret
71
72# Generate a token
73gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
74```
75
76```bash
77# Docker login with token
78docker login -u ci-bot -p <token> registry.mydomain.com
79```
80
81### Password + token setup
82
83```bash
84# Generate bcrypt hash
85gordon auth password hash
86
87# Store hash and token secret
88pass insert gordon/auth/password_hash
89pass insert gordon/auth/token_secret
90```
91
92```bash
93# Docker registry access
94docker login -u deploy -p <password> registry.mydomain.com
95
96# Remote CLI login (stores a token for you)
97gordon auth login --remote prod
98```
99
100## Remote CLI Tokens
101
102If you already have a token (token-only servers), store it directly:
103
104```bash
105gordon auth login --token <token>
106# or
107gordon remotes set-token prod <token>
108```
109
110## Token Scopes
111
112Registry scopes:
113
114| Scope | Permission |
115| ------- | ------------ |
116| `push` | Push images to registry |
117| `pull` | Pull images from registry |
118| `push,pull` | Both push and pull (default) |
119
120Admin scopes (for remote CLI):
121
122| Scope | Permission |
123|-------|------------|
124| `admin:*:*` | Full admin access |
125| `admin:routes:read` | Read-only routes access |
126| `admin:routes:write` | Routes write access |
127| `admin:config:read` | Read-only config access |
128| `admin:config:write` | Config write access |
129| `admin:status:read` | Read-only status/health |
130| `admin:secrets:read` | List secret keys |
131| `admin:secrets:write` | Set/delete secrets |
132
133Examples:
134
135```bash
136gordon auth token generate --subject reader --scopes pull --expiry 30d
137gordon auth token generate --subject builder --scopes push --expiry 0
138gordon auth token generate --subject admin --scopes "push,pull,admin:*:*" --expiry 0
139```
140
141## Token Expiry
142
143Durations support `d`, `w`, `M`, `y` and combinations like `1y6M` or `2w3d`.
144
145```bash
146gordon auth token generate --subject ci --expiry 0
147gordon auth token generate --subject deploy --expiry 1y
148gordon auth token generate --subject temp --expiry 30d
149```
150
151## Instance-specific Tokens
152
153- Tokens are signed with `token_secret`
154- Tokens from one Gordon instance won't work on another
155- Changing `token_secret` invalidates all existing tokens
156
157## Disable Auth (development only)
158
159```toml
160[auth]
161enabled = false
162```
163
164## Internal Registry Auth
165
166Gordon generates internal credentials when auth is enabled. These are used for loopback pulls during deploys and are regenerated on each restart.
167
168Gordon also generates a separate service token for its own registry-domain pulls. This token is managed internally and is not exposed via configuration or CLI.
169
170To view internal credentials (for troubleshooting):
171
172```bash
173gordon auth internal
174```
175
176## Related
177
178- [Secret Providers](./secrets.md)
179- [CLI Commands](../cli/index.md)
180- [GitHub Actions Deployment](../deployment/github-actions.md)