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