Repository navigation
oidc pocket id
Pocket ID is a lightweight self-hosted OIDC provider. (OIDC, OpenID Connect, is a standard sign-in protocol.) Pocket ID signs users in with passkeys instead of passwords. It is popular in homelab setups, because the entire IdP (identity provider) is one small container.
This guide sets up Muximux to sign in against Pocket ID. Muximux receives the user's group memberships and matches them against admin_groups.
- A running Pocket ID instance. Every browser that will use Muximux must be able to reach it. The default port is
1411. You'll typically put it behind a reverse proxy (a server that forwards requests to another server) at an address likehttps://id.example.com. - Admin access to Pocket ID.
- Muximux on a stable URL.
- In Pocket ID admin, open OIDC Clients.
- Click Add OIDC Client.
- Fill in:
- Name:
Muximux - Callback URLs:
https://muximux.example.com/api/auth/oidc/callback - Logout Callback URLs: leave empty unless you've configured a Muximux logout redirect.
- Public Client: Off (we want a confidential client with a secret)
- PKCE: leave at the default.
- Name:
- Save. Pocket ID shows you a Client ID and Client Secret.
- Copy both.
Pocket ID emits the groups claim (the list of the user's groups in the token) only when the client is allowed to read it.
- In the same OIDC client edit page, find the Allowed User Groups section.
- Add the groups you want Muximux to see. Anyone who belongs to one of these groups can sign in to Muximux. The IdP refuses everyone else. Add at least:
-
Muximux-Admins(or whatever you want admin status to map to) - any other group you'll later use for per-app filtering
-
- Save.
If you don't have those groups yet, create them under Groups first. Then assign members.
Edit config.yaml:
auth:
method: oidc
oidc:
enabled: true
issuer_url: https://id.example.com
client_id: <client id from Step 1>
client_secret: ${POCKETID_CLIENT_SECRET}
redirect_url: https://muximux.example.com/api/auth/oidc/callback
scopes:
- openid
- profile
- email
- groups
username_claim: preferred_username
email_claim: email
groups_claim: groups
display_name_claim: name
admin_groups:
- Muximux-Adminsissuer_url is the public URL of Pocket ID, with no trailing path. Pocket ID exposes the OIDC discovery document (a file that lists the provider's endpoints) at https://id.example.com/.well-known/openid-configuration.
- Set
POCKETID_CLIENT_SECRETin the environment. - Restart Muximux.
Instead of editing config.yaml, you can use Settings:
- Open Settings > Security.
- Choose Single sign-on (OIDC).
- As the issuer URL, enter the public URL of Pocket ID (for example
https://id.example.com, no trailing path). - Enter the client ID and secret from Step 1.
- Add
groupsto the scopes. - Enter
groupsas the groups claim. - Enter your admin group (for example
Muximux-Admins) under admin groups. - Copy the Callback URL (register at the provider) and Back-channel logout URL rows into the provider.
- Press Test connection.
- Press Update Method.
See Authentication for how the form handles the client secret and SSO-only sign-in.
- Visit
https://muximux.example.com/login. - Click Login with SSO. Pocket ID prompts you for a passkey.
- Sign in. You should land back on the Muximux dashboard.
- Sign in as a member of
Muximux-Admins. - Confirm that the Settings gear is visible.
Pocket ID's discovery document publishes an end_session_endpoint. It also advertises back-channel logout support (the provider tells Muximux directly when a user signs out). Each client has a list of logout callback URLs and a single backchannel logout URL. This guide could not confirm the exact labels in the admin form. Check the OIDC client form in your Pocket ID version.
-
Return address. Add
https://muximux.example.com/login?logged_out=1(or yourpost_logout_redirect_url) to the client's logout callback URLs. Then setprovider_logout: true. -
Back-channel logout. Set the client's backchannel logout URL to
https://muximux.example.com/api/auth/oidc/backchannel-logout. Pocket ID does not include the session ID (sid) in logout tokens. (Its discovery document reportsbackchannel_logout_session_supportedas false.) Muximux therefore matches sessions bysub.
| Symptom | Cause | Fix |
|---|---|---|
unauthorized_client from Pocket ID |
The client is set to Public but Muximux is sending a client secret. | Switch the client to confidential (turn Public Client off). |
| Sign-in fails with "user is not allowed to use this client" | The user isn't in any group listed under Allowed User Groups. | Add the user (or one of their groups) to the client's allow list in Step 2. |
| Sign-in works but admin gear is missing | The user's groups don't include any value listed in admin_groups. |
Confirm the group exists in Pocket ID and the user is a member. Check the audit log entry on Muximux: OIDC user logged in lists the resolved role. |
Failed to fetch discovery document |
issuer_url doesn't match Pocket ID's public URL exactly. |
Use the URL shown in your browser when you visit Pocket ID's UI, no trailing path. |
-
Authentication overview for the full
auth.oidcreference. - Other identity providers: Microsoft Entra ID, Keycloak, Authentik, Zitadel, Google, Authelia, Cloudflare Access.
Getting Started
Features
- Apps
- HTTP Actions
- Reverse Proxy
- Docker Discovery
- Docker Labels
- Docker Swarm & Compose
- Navigation
- Split View
- Themes
- Keyboard Shortcuts
- Keyboard & Accessibility
- Health Monitoring
- Icons
- Translations
Security
Identity provider guides
Operations