Registering OAuth clients

An application that wants to log its users in through Everlock is registered as a client. Registration is what produces the client_id and client_secret the application needs, and it names the redirect URIs Everlock is willing to send a user back to.

Clients live in the OAuth backend's own store, so the list survives restarts and every change is a commit.

Creating a client

/oauth client create <id> name=<name> redirect-uri=<uri> [redirect-uri=<uri>...] [scope=<s>...]

The id is the client_id the application will send. Pick something stable and recognisable — it appears in the application's own configuration:

/oauth client create grafana \
  name="Grafana" \
  redirect-uri=https://grafana.example.com/login/generic_oauth

OAuth client created

  client_id:    grafana
  name:         Grafana
  scopes:       openid profile email
  redirect_uri: https://grafana.example.com/login/generic_oauth

client_secret: <secret>
Save the client_secret now - it will not be shown again.

The secret is shown once. It is stored hashed, so a lost secret is rotated rather than recovered.

Redirect URIs are repeatable and exact. Pass redirect-uri= once per URI. Everlock will only redirect to a URI on the list, which is what stops an attacker from pointing an authorization code at a host they control.

Scopes default to openid profile email when none are given. Pass scope= once per scope to narrow or extend that.

Listing and inspecting

/oauth client list

  CLIENT ID   NAME      REDIRECT URIS
  ─────────────────────────────────────────────────────────────────
  grafana     Grafana   https://grafana.example.com/login/generic_oauth

/oauth client show grafana

show prints the client id, name, scopes, and every redirect URI — the same detail block create returned, without the secret.

Rotating a secret

/oauth client rotate-secret grafana

A new secret is generated and printed once, and the previous one stops working immediately. Rotate when a secret has leaked, when someone who knew it leaves, or on whatever schedule you keep — then update the application's configuration.

Deleting a client

/oauth client delete grafana

The registration is removed, so the application can no longer obtain tokens. Tokens already issued to it are signed JWTs and stay valid until they expire.

Pointing an application at Everlock

Applications that speak OIDC discovery need only the issuer URL: they read everything else from

https://<issuer-host>/.well-known/openid-configuration

For an application that wants each endpoint spelled out:

Endpoint	Path
Discovery	`/.well-known/openid-configuration`
JWKS	`/.well-known/jwks.json`
Authorization	`/oauth/authorize`
Token	`/oauth/token`
User info	`/oauth/userinfo`
Logout	`/oauth/logout`

Tokens are signed RS256; the public key is served from the JWKS endpoint, which is how an application verifies them without holding a shared secret.