Set up the login for your AI
For: self-hosters who want claude.ai, ChatGPT or any MCP client to reach their server from
anywhere. At the end: the MCP endpoint answers on https://wow-full.example.org/mcp, only
your account gets in, and a connector added in claude.ai logs in and lists the tools.
claude.ai and ChatGPT call your server from their own servers, not from your browser, so they can’t carry your page’s password. They speak OAuth (the “log in with…” standard): the first time, your browser opens a consent page from your server, then your identity provider’s login, and the client gets a token it renews by itself. wow-stats doesn’t keep passwords: you bring an OIDC identity provider (a login service that speaks OpenID Connect: Keycloak, Authentik, ZITADEL, and most hosted ones).
On the computer that runs the server, Claude Code needs none of this: On the server’s own computer.
Before you start
Section titled “Before you start”- The kit behind HTTPS on a public name: Put it behind a reverse proxy.
The examples use
wow-full.example.org. - An identity provider you can make an app in, reachable from the server over HTTPS.
1. Make an app at your identity provider
Section titled “1. Make an app at your identity provider”Any provider works if it offers OIDC discovery (<issuer>/.well-known/openid-configuration),
the authorization code flow with a client secret, and refresh tokens. Make an app (some call
it a client) with:
| Setting | Value |
|---|---|
| Type | Confidential, or “web application”: it has a client secret |
| Flow | Authorization code |
| Redirect URI | https://wow-full.example.org/oauth/callback |
| Refresh tokens | On (the offline_access scope) |
Note three things: the issuer URL, the client id and the client secret. Then find
your own account’s subject id (sub): the provider’s stable id for you, often a UUID or a
long number, shown on the user’s page in its admin console.
2. Give them to wow-stats
Section titled “2. Give them to wow-stats”From deploy/compose:
printf '%s' 'the client secret' > secrets/oidc_client_secrethead -c 48 /dev/urandom > secrets/mcp_signing_keychmod 644 secrets/oidc_client_secret secrets/mcp_signing_keyThe signing key signs the tokens wow-stats hands to clients. Keep it: a new one logs every
client out. The containers run as their own user, hence chmod 644.
Then in .env:
MCP_PUBLIC_URL=https://wow-full.example.org/mcpOIDC_ISSUER=https://id.example.org/realms/wowOIDC_CLIENT_ID=wow-mcpOIDC_ALLOWED_SUBS=your subMCP_SIGNING_KEY_FILE=/run/wow-secrets/mcp_signing_keyThe host of MCP_PUBLIC_URL is one the page answers for by itself. OIDC_ALLOWED_SUBS takes
several ids, comma separated. Anyone else who logs in at your
provider is refused. Restart with the same files as before (Caddy here):
docker compose -f compose.yaml -f compose.caddy.yaml up -d3. Check it
Section titled “3. Check it”curl -s https://wow-full.example.org/.well-known/oauth-protected-resource/mcpcurl -s -o /dev/null -w '%{http_code}\n' https://wow-full.example.org/mcpThe first prints a JSON document naming https://wow-full.example.org/mcp as the resource; the
second prints 401: the endpoint is there and wants a token. A 502 or 404 instead is the
proxy: the MCP paths must go to port 8090 (What goes where).
Then add the connector in claude.ai, or any client: Connect your AI. Your browser opens a consent page from your server (Approve), then your provider’s login.
Worked example: Keycloak
Section titled “Worked example: Keycloak”Keycloak is a free, self-hosted identity provider. This assumes
it runs at https://id.example.org and you can run its admin CLI, kcadm.sh, which ships in
its container. If yours runs in Docker, prefix each command with
docker exec -it <container> /opt/keycloak/bin/ (-it lets the first one ask for the
password).
Log the CLI in as Keycloak’s admin (it asks for the password):
kcadm.sh config credentials --server http://localhost:8080 --realm master --user adminA realm (Keycloak’s word for a separate set of users and apps) for wow-stats, and the app:
kcadm.sh create realms -s realm=wow -s enabled=truekcadm.sh create clients -r wow -s clientId=wow-mcp -s publicClient=false \ -s standardFlowEnabled=true -s directAccessGrantsEnabled=false \ -s 'redirectUris=["https://wow-full.example.org/oauth/callback"]'The client secret (Keycloak made one):
id=$(kcadm.sh get clients -r wow -q clientId=wow-mcp --fields id --format csv --noquotes)kcadm.sh get clients/$id/client-secret -r wow --fields value --format csv --noquotesYour account in the realm (Keycloak wants a username of 3 characters or more), and its sub
(Keycloak’s user id):
kcadm.sh create users -r wow -s username=player -s enabled=true -s email=player@example.org \ -s emailVerified=true -s firstName=Test -s lastName=Playerkcadm.sh set-password -r wow --username player --new-password 'a long password'kcadm.sh get users -r wow -q username=player --fields id --format csv --noquotesSo in .env: OIDC_ISSUER=https://id.example.org/realms/wow, OIDC_CLIENT_ID=wow-mcp, and
OIDC_ALLOWED_SUBS= the id the last command printed. The secret goes in
secrets/oidc_client_secret as in step 2.
Keycloak lets in any user of the realm; OIDC_ALLOWED_SUBS is what keeps wow-stats to you.
Other providers
Section titled “Other providers”- ZITADEL: the defaults read ZITADEL’s own claims. With one install per person you can
also require a project role (
OIDC_REQUIRED_ROLE) or an organisation (OIDC_ALLOWED_ORGS). - Others with roles or organisations: set
OIDC_ROLES_CLAIMandOIDC_ORG_CLAIMto the claim names your provider uses, then the two settings above.
Every login setting: Environment variables, the MCP endpoint.
When it doesn’t work
Section titled “When it doesn’t work”uikeeps restarting (docker compose ps). It reads your provider’s discovery document when it starts, so the issuer must answer from the server, over HTTPS with a certificate the server trusts.docker compose logs ui | tailnames the address it couldn’t reach.- “Client Not Registered”, or a client that never gets to your login page. The client
isn’t on the server’s list of known clients: Claude, ChatGPT, VS Code, Cursor, Codex,
opencode, Copilot CLI, Zed and Goose are by default. Others: add their redirect address to
MCP_REDIRECT_URISor their host toMCP_CIMD_HOSTS(this replaces the list, so keep the ones you use). - “Authorization session mismatch” at Approve. The proxy drops cookies on the login pages.
- Refused after logging in. Your
subisn’t inOIDC_ALLOWED_SUBS. Theuilog says which one was refused:docker compose logs ui | grep -i refus. - Everyone logged out after a restart.
MCP_SIGNING_KEY_FILEisn’t set, or the file changed.
How the login works inside: MCP, how login works.