Skip to content
github-actions[bot] edited this page Nov 9, 2026 · 8 revisions

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.


Prerequisites

  • 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 like https://id.example.com.
  • Admin access to Pocket ID.
  • Muximux on a stable URL.

Step 1: Register the OIDC Client

  1. In Pocket ID admin, open OIDC Clients.
  2. Click Add OIDC Client.
  3. 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.
  4. Save. Pocket ID shows you a Client ID and Client Secret.
  5. Copy both.

Step 2: Allow the Client to See Group Memberships

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.

  1. In the same OIDC client edit page, find the Allowed User Groups section.
  2. 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
  3. Save.

If you don't have those groups yet, create them under Groups first. Then assign members.


Step 3: Configure Muximux

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-Admins

issuer_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.

  1. Set POCKETID_CLIENT_SECRET in the environment.
  2. Restart Muximux.

Using Settings

Instead of editing config.yaml, you can use Settings:

  1. Open Settings > Security.
  2. Choose Single sign-on (OIDC).
  3. As the issuer URL, enter the public URL of Pocket ID (for example https://id.example.com, no trailing path).
  4. Enter the client ID and secret from Step 1.
  5. Add groups to the scopes.
  6. Enter groups as the groups claim.
  7. Enter your admin group (for example Muximux-Admins) under admin groups.
  8. Copy the Callback URL (register at the provider) and Back-channel logout URL rows into the provider.
  9. Press Test connection.
  10. Press Update Method.

See Authentication for how the form handles the client secret and SSO-only sign-in.


Step 4: Validate

  1. Visit https://muximux.example.com/login.
  2. Click Login with SSO. Pocket ID prompts you for a passkey.
  3. Sign in. You should land back on the Muximux dashboard.
  4. Sign in as a member of Muximux-Admins.
  5. Confirm that the Settings gear is visible.

Sign-out

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 your post_logout_redirect_url) to the client's logout callback URLs. Then set provider_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 reports backchannel_logout_session_supported as false.) Muximux therefore matches sessions by sub.

Troubleshooting

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.

See Also

Clone this wiki locally