1.4 KiB
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:
- Fresh wallet entry: return it.
- Stale entry with refresh token: refresh under
$XDG_RUNTIME_DIR/sherlock.refresh.lock, persist, return. - 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.