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