38 lines
1.4 KiB
Markdown
38 lines
1.4 KiB
Markdown
# Auth model
|
|
|
|
Sherlock is a service-keyed OAuth wallet. There is no `sherlock login` and no
|
|
master session: each MCP authenticates for the service it calls.
|
|
|
|
## Lifecycle
|
|
|
|
For a service such as `gitea`, `grafana`, `gssh`, or `searxng`, the MCP asks
|
|
`internal/authn` for a token on first use:
|
|
|
|
1. Fresh wallet entry: return it.
|
|
2. Stale entry with refresh token: refresh under
|
|
`$XDG_RUNTIME_DIR/sherlock.refresh.lock`, persist, return.
|
|
3. Missing or unrecoverable entry: run a PKCE browser flow on `127.0.0.1:6990`,
|
|
serialized by `$XDG_RUNTIME_DIR/sherlock.login.lock`, persist, return.
|
|
|
|
Long-running MCPs use `TokenSource` and `TokenHolder` so requests always read
|
|
the latest bearer. Refresh follows access-token expiry, never opens a browser,
|
|
and falls back to a fresh login on the next invocation if refresh can no longer
|
|
recover.
|
|
|
|
## Service identity
|
|
|
|
The config supplies issuer, client ID/secret, and base URL. Scopes are owned by
|
|
each MCP because they follow the tool surface, not the deployment.
|
|
|
|
Gitea uses Gitea's OAuth2 server. Grafana, Gssh, and SearXNG normally reuse the
|
|
shared Authentik `sherlock-cli` provider. Tokens are stored and refreshed per
|
|
service and are not reused across unrelated services.
|
|
|
|
## User controls
|
|
|
|
`sherlock status` lists stored sessions. `sherlock logout` clears all sessions;
|
|
`sherlock logout <service>` clears one.
|
|
|
|
Sherlock does not use static service-account tokens, share sessions between
|
|
operators, or perform RFC 8693 token exchange.
|