Set Up OAuth Authentication

This guide shows you how to enable OAuth authentication on swamp serve so that users log in through swamp-club instead of receiving manually minted tokens.

Start the server with OAuth

Pass --auth-mode oauth with at least one admission policy (--allowed-collectives or --allowed-users) and an admin:

swamp serve --auth-mode oauth \
  --admins swampadmin \
  --allowed-collectives acme-corp

--admins accepts swamp-club usernames — the server resolves them at startup.

Important

Off-loopback binding (e.g., --host 0.0.0.0) requires both TLS and authentication. The server refuses to start without them. See Set Up TLS for certificate setup.

First-time bootstrap

On the first start, the server registers itself as an OAuth client with swamp-club automatically. You do not need to provide --oauth-client-id — it is created for you:

The server prints a verification URL and a code to your terminal
Open the URL in a browser and sign in to swamp-club
Enter the code and approve the registration
The server stores the client credentials in the vault — subsequent starts skip this step entirely

If you already have a client ID from a previous registration or manual setup, pass it with --oauth-client-id <id> to skip the bootstrap flow.

Users authenticate with swamp auth server-login:

swamp auth server-login --server wss://swamp-serve.example.com

This starts a device authorization flow:

The CLI displays a verification URL and a user code
The user opens the URL in a browser and signs in to swamp-club
The user enters the code and approves access
The CLI receives a token and stores it in ~/.config/swamp/servers.json

Subsequent commands using --server wss://swamp-serve.example.com (or SWAMP_SERVE_URL) authenticate automatically with the stored token.

Collective-based admission

--allowed-collectives controls which swamp-club collectives grant access. Users who belong to at least one listed collective are admitted:

swamp serve --auth-mode oauth \
  --admins swampadmin \
  --allowed-collectives acme-corp,other-team

Users not in any of the listed collectives are rejected. Membership changes in swamp-club take effect on the user's next login.

User-based admission

--allowed-users admits specific swamp-club usernames or user:<sub> subjects:

swamp serve --auth-mode oauth \
  --admins swampadmin \
  --allowed-users alice,bob

At least one of --allowed-collectives or --allowed-users is required for OAuth mode. Both can be used together — a user matching either policy is admitted.

Subsequent starts

After the first-time bootstrap, the server loads its OAuth client credentials from the vault and resolves admin usernames using cached mappings. No browser interaction is needed on restart.

HTTPS requirement

--oauth-provider defaults to https://swamp-club.com. If you specify a custom provider URL, it must use HTTPS — except for localhost, where HTTP is accepted for local development.

Set Up Token Authentication — token-based alternative for air-gapped environments
Set Up TLS for swamp serve — required for off-loopback deployments
Manage Access Grants — control what authenticated users can do
OAuth and collective-based admission — why OAuth, the device grant flow, and how collectives map to admission
Serve Flags — full flag and environment variable reference