Authentication

Configure authentication for the Gordon registry and Admin API.

Authentication is enabled by default. Gordon will not start without a valid token_secret (or GORDON_AUTH_TOKEN_SECRET).

Configuration

Gordon uses token-only authentication. All registry and Admin API access is controlled through JWT tokens.

[auth]
secrets_backend = "pass"
token_secret = "gordon/auth/token_secret"
token_expiry = "30d"
access_token_ttl = "15m"

Options

Option	Type	Default	Description
`enabled`	bool	`true`	Authentication toggle. `false` enables local-only mode (see below)
`secrets_backend`	string	`"unsafe"`	Secrets backend: `"pass"`, `"sops"`, or `"unsafe"`
`token_secret`	string	-	Required. Path to JWT signing secret in secrets backend
`token_expiry`	string	`"30d"`	Token validity duration (0 = never expires)
`access_token_ttl`	string	`"15m"`	Lifetime of ephemeral access tokens issued by `/auth/token`

Secrets Backends

token_secret is read through the configured backend:

Backend	Description
`pass`	Unix password manager (GPG-encrypted)
`sops`	Mozilla SOPS encrypted files
`unsafe`	Plain text files (development only)

See Secret Providers for setup details.

Environment Variable

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).

export GORDON_AUTH_TOKEN_SECRET="your-32-character-secret-here"
gordon serve

Setup

# Create token secret (random 32+ characters)
pass insert gordon/auth/token_secret

# Generate a token
gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0

# Docker login with token
docker login -u ci-bot -p <token> registry.mydomain.com

Remote CLI Tokens

Store a token for remote CLI access:

gordon auth login --token <token>
# or
gordon remotes set-token prod <token>

Token Scopes

Registry scopes:

Scope	Permission
`push`	Push images to registry
`pull`	Pull images from registry
`push,pull`	Both push and pull (default)

Admin scopes (for remote CLI):

Scope	Permission
`admin::`	Full admin access
`admin:routes:read`	Read-only routes access
`admin:routes:write`	Routes write access
`admin:config:read`	Read-only config access
`admin:config:write`	Config write access
`admin:status:read`	Read-only status/health
`admin:secrets:read`	List secret keys
`admin:secrets:write`	Set/delete secrets

Examples:

gordon auth token generate --subject reader --scopes pull --expiry 30d
gordon auth token generate --subject builder --scopes push --expiry 0
gordon auth token generate --subject admin --scopes "push,pull,admin:*:*" --expiry 0

Access Token TTL

The 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.

Value	Meaning
`"15m"`	15 minutes (default)
`"30m"`	30 minutes
`"1h"`	1 hour (maximum before store validation applies)

Tokens 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.

[auth]
access_token_ttl = "30m"

Token Expiry

Durations support d, w, M, y and combinations like 1y6M or 2w3d.

gordon auth token generate --subject ci --expiry 0
gordon auth token generate --subject deploy --expiry 1y
gordon auth token generate --subject temp --expiry 30d

Instance-specific Tokens

Tokens are signed with token_secret
Tokens from one Gordon instance won't work on another
Changing token_secret invalidates all existing tokens

Local-only Mode

Authentication is enabled by default. If you set auth.enabled=false, Gordon switches to local-only mode:

/admin/* endpoints are not registered.
/v2/* registry endpoints are restricted to loopback (127.0.0.1 / ::1).
Remote registry and remote admin access are disabled.

Use this only when Gordon is intended for local machine usage.

Internal Registry Auth

Gordon generates internal credentials when auth is enabled. These are used for loopback pulls during deploys and are regenerated on each restart.

Gordon 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.

To view internal credentials (for troubleshooting):

gordon auth internal

Note: Internal credentials are stored with restrictive permissions (0600) in secure runtime directories (XDG_RUNTIME_DIR or ~/.gordon/run) and cleaned up on shutdown.