Skip to main content
OIDC mode replaces the password with a sign-in at an external identity provider — Google, Keycloak, Authentik, or any OpenID Connect-compatible service. It is also required if you want Claude web or ChatGPT web to connect to your MCP server without you pasting a token into them. Once configured, the account you sign in with at the provider becomes the owner of the instance — no password is ever set.
OIDC mode requires an https:// URL for your plamotrack instance. You need a TLS-terminating proxy (like Caddy) or a Cloudflare Tunnel in front of the stack. See Deployment if you need to set that up first.

​
Choose your provider

Any provider that publishes a discovery document at <issuer>/.well-known/openid-configuration works. Three common examples:
  • Google — issuer: https://accounts.google.com
  • Keycloak — issuer: https://keycloak.example/realms/your-realm
  • Authentik — issuer: https://authentik.example/application/o/plamotrack/
To sign in with a passkey and no cloud account, run your own provider: see Pocket ID. Use the issuer URL exactly as your provider’s discovery document states it. Even a trailing slash difference can cause verification to fail.

​
Register a client with your provider

Create an OAuth/OIDC client (also called an “application”) in your provider’s dashboard. Configure it with these two redirect URIs:
  • Browser login: <PUBLIC_BASE_URL>/api/auth/oidc/callback
  • MCP clients (Claude web, ChatGPT web, Gemini Spark, Mistral): <PUBLIC_BASE_URL>/mcp/auth/callback
The client must be the only audience of the ID tokens it issues. Do not attach other clients’ audience mappers to it — a token naming an additional audience is refused by plamotrack. Note down the client ID and client secret before moving on.

​
Update .env

Add the following to your .env file, then restart the stack:
Then bring the stack back up:

​
Claim the instance in OIDC mode

The API still prints a one-time setup token to its log on first start, just like a fresh install. Open the app, enter the token when prompted, and plamotrack will redirect you to your identity provider. The account you sign in with at the provider becomes the owner of the instance, bound to the stable identity the provider asserts — its issuer and subject, not an email address, which is shown in the UI and used for nothing else. No password is set. Any other account that signs in at the same provider is refused, and the refusal is recorded in the audit log. If you miss the token or need a fresh one, restart the API container:
Then read the new token from the log:

​
Switching from password to OIDC

It is safe to switch an existing instance from password to OIDC. Your entire collection is untouched. On the first start in the new mode, the API signs every active browser session out and records the change in the audit log. The first sign-in at the provider with the new setup token binds that account as the owner — the old password is then ignored. Switching back to password mode (AUTH_MODE=local) works the same way in reverse: everyone is signed out, and you set a new password during the re-claim step.

​
Lost access to your provider account?

If you lose access to the identity provider account bound to your instance — or you want to switch to a different provider entirely — run this from the host machine:
This command clears the bound identity, signs every active browser session out, and ends every MCP client link made through the provider: the grants are purged from the instance and, best effort, the provider’s own refresh tokens behind them are revoked — the command reports how many the provider accepted, and a provider that cannot be reached leaves the local purge standing. Then restart the API and sign in with the new account:
Read the new setup token from the log and complete the claim as normal. Access tokens are untouched — revoke any you no longer trust from Settings → Access tokens once you are back in.
If your identity provider is temporarily unavailable, existing browser sessions and personal access tokens keep working normally. New sign-ins will fail with a clear error message until the provider comes back online. plamotrack never falls back to password mode on its own.