Authentication Commands
Manage Gordon server authentication tokens and passwords.
gordon auth
Subcommands
| Subcommand | Description |
|---|---|
login |
Authenticate with a remote Gordon server |
token generate |
Generate a new JWT token |
token list |
List all stored tokens |
token revoke |
Revoke a token by ID (use --all to revoke all tokens) |
password hash |
Generate bcrypt password hash |
internal |
Show internal registry credentials |
gordon auth login
Authenticate with a remote Gordon server using password authentication or a pre-generated token.
gordon auth login [options]
Options
| Option | Description |
|---|---|
-r, --remote |
Remote to authenticate with (defaults to active remote) |
-u, --username |
Username for authentication |
-p, --password |
Password for authentication |
-t, --token |
Authentication token to store for the remote |
Description
This command prompts for your username and password, authenticates with the remote server's /auth/password endpoint, and stores the returned token. When pass is available, the token is stored encrypted at gordon/remotes/<name>/token and any plaintext token fields are cleared from remotes.toml. When pass is unavailable, the token is stored in plaintext in remotes.toml with a warning.
If you provide --token, the token is stored directly and verified against /admin/status on a best-effort basis.
The token is a long-lived JWT (7 days) that's used for subsequent CLI operations against the remote.
Note: For token-only servers, you can pass
--tokenhere or usegordon remotes set-token.
Examples
# Login using active remote
gordon auth login
# Login to specific remote
gordon auth login --remote prod
# Pre-fill username
gordon auth login --username admin
# Store a pre-generated token
gordon auth login --token <token>
Output
When pass is available:
Username: admin
Password: ********
Authenticating with prod...
✓ Authentication successful!
Token stored in pass for remote 'prod'
Expires in: 604800 seconds
When pass is not available:
Username: admin
Password: ********
Authenticating with prod...
Warning: 'pass' not available. Storing token in plaintext config. Consider installing pass (https://www.passwordstore.org/) for secure token storage.
✓ Authentication successful!
Token stored for remote 'prod'
Expires in: 604800 seconds
gordon auth token generate
Generate a new JWT authentication token for registry access.
gordon auth token generate --subject <name> [options]
Options
| Option | Default | Description |
|---|---|---|
--subject |
(required) | Username/subject for the token |
--scopes |
push,pull |
Comma-separated scopes |
--expiry |
30d |
Duration until expiry (0 = never) |
-c, --config |
Auto | Path to config file |
Duration Format
Supports human-friendly duration units:
| Unit | Description | Example |
|---|---|---|
d |
Days (24 hours) | 30d |
w |
Weeks (7 days) | 2w |
M |
Months (30 days) | 6M |
y |
Years (365 days) | 1y |
Compound durations are also supported: 1y6M, 2w3d, 1d12h
Standard Go durations also work: 24h, 30m, 1h30m
Examples
# CI token that never expires
gordon auth token generate --subject github-actions --expiry 0
# Read-only token for 30 days
gordon auth token generate --subject reader --scopes pull --expiry 30d
# Push-only token for 1 year
gordon auth token generate --subject builder --scopes push --expiry 1y
# Temporary token (24 hours)
gordon auth token generate --subject temp --expiry 24h
# Token for 6 months
gordon auth token generate --subject deploy --expiry 6M
Output
Token generated successfully!
Subject: github-actions
Scopes: push, pull
Expiry: never
Token (use as password with docker login):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Usage: docker login -u github-actions -p <token> <registry>
gordon auth token list
List all stored authentication tokens.
gordon auth token list [options]
Output
ID Subject Expires Revoked
------------------------------------------------------------------------------------------
a1b2c3d4-e5f6-7890-abcd-ef1234567890 github-actions never no
b2c3d4e5-f6a7-8901-bcde-f12345678901 deploy-bot 2024-02-15 10:30 no
c3d4e5f6-a7b8-9012-cdef-123456789012 old-token 2024-01-01 00:00 yes
gordon auth token revoke
Revoke a token by its ID.
gordon auth token revoke <token-id> [options]
gordon auth token revoke --all # Revoke all tokens
Example
gordon auth token revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
Output
Token a1b2c3d4-e5f6-7890-abcd-ef1234567890 has been revoked.
gordon auth password hash
Generate a bcrypt hash for password authentication.
gordon auth password hash
Interactively prompts for a password and outputs the bcrypt hash.
Output
Enter password: ********
Bcrypt hash (store in your secrets backend):
$2a$10$N9qo8uLOickgx2ZMRZoMye...
Then reference the path in your config:
[auth]
username = "deploy"
password_hash = "gordon/auth/password_hash"
token_secret = "gordon/auth/token_secret"
gordon auth internal
Display the auto-generated internal registry credentials.
gordon auth internal
Gordon generates temporary credentials for loopback-only communication with its local registry. These credentials are useful for manual recovery when debugging deployment issues.
When registry auth is enabled, Gordon also generates a separate service token for its own registry-domain pulls. That token is not exposed via the CLI.
Output
Internal Registry Credentials
==============================
Username: gordon-internal
Password: 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
Usage:
docker login localhost:5000 -u gordon-internal -p 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
Notes
- Credentials are regenerated each time Gordon starts
- Only available while Gordon is running
- Used for manual
docker pullfrom the local registry during debugging - Separate from the service token used by Gordon core for registry-domain pulls
Use Cases
- Debugging image pull failures
- Manual recovery after deployment issues
- Inspecting images in the local registry
Token Scopes
| Scope | Permission |
|---|---|
push |
Push images to registry |
pull |
Pull images from registry |
push,pull |
Both push and pull (default) |
Token Expiry Formats
| Format | Duration |
|---|---|
0 |
Never expires |
24h |
24 hours |
720h |
30 days |
8760h |
1 year |
Workflow Examples
CI/CD Setup
# Generate token for CI
gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
# Save token as CI secret
# GitHub: Settings → Secrets → New repository secret
# GitLab: Settings → CI/CD → Variables
Docker Login
# Using generated token
docker login -u ci-bot -p <token> registry.mydomain.com
# In CI/CD
echo "$GORDON_TOKEN" | docker login -u ci-bot --password-stdin registry.mydomain.com
Token Rotation
# Generate new token
gordon auth token generate --subject ci-bot --expiry 0
# Update CI secrets with new token
# Revoke old token
gordon auth token revoke <old-token-id>
Password Setup
# Generate hash
gordon auth password hash
# Enter: mypassword
# Store in pass
pass insert gordon/auth/password_hash
# Paste: $2a$10$...
# Create token secret
pass insert gordon/auth/token_secret
# Enter a random 32+ character string
# Configure gordon.toml
[auth]
enabled = true
secrets_backend = "pass"
username = "deploy"
password_hash = "gordon/auth/password_hash"
token_secret = "gordon/auth/token_secret"