Pocket ID

This guide walks you through setting up Pocket ID as an OIDC provider for Grimmory. Pocket ID is a lightweight, self-hosted identity provider that’s especially popular in homelabs for its simplicity. If you just want SSO without the complexity of a full-featured provider, Pocket ID is a great choice.

By the end of this guide, your users will be able to sign in to Grimmory with their Pocket ID account. The setup takes about 3 minutes.

Part 1: Create an OIDC Client in Pocket ID

Open your Pocket ID admin panel and go to Settings > Administration > OIDC Clients. Click Add OIDC Client.

Fill in the client configuration:

Field	Value	Notes
Name	`Grimmory`	Shown to users in the Pocket ID dashboard
Callback URLs	`https://books.example.com/oauth2-callback`	Replace with your actual Grimmory domain
Public Client	ON	Grimmory uses PKCE, so no client secret is needed
Client Launch URL	`https://books.example.com/`	The URL where users access Grimmory

Local development example:

Callback URLs: http://localhost:4200/oauth2-callback
Client Launch URL: http://localhost:4200/

Click Save.

Part 2: Get Your Credentials

After saving, Pocket ID generates a Client ID for your application.

Copy it. You’ll also need your Issuer URL, which is simply your Pocket ID base URL:

Value	Example
Client ID	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`
Issuer URL	`https://pocket-id.example.com`

Part 3: Configure Grimmory

Navigate to Settings > OIDC in Grimmory.

Fill in the provider configuration:

Field	Value
Provider Name	`Pocket ID` (shown on the login button)
Client ID	Paste the Client ID from Pocket ID
Client Secret	Leave empty (public client)
Issuer URI	Your Pocket ID URL (e.g., `https://pocket-id.example.com`)

The default claim mappings work with Pocket ID out of the box:

Claim	Value
Username	`preferred_username`
Email	`email`
Display Name	`name`
Groups	`groups`

Click Test Connection to verify Grimmory can reach Pocket ID. All checks should pass.

Click Save, then toggle OIDC Login to ON in the Login Methods section.

Test It

Open your Pocket ID dashboard and go to My Apps. You should see the Grimmory application card.

Click the Grimmory card. Pocket ID handles the authentication and redirects you to Grimmory.

You should be logged in automatically. Verify that your username and email are correct.

Alternative: Open an incognito window, go to your Grimmory instance, and click “Sign in with Pocket ID”.

What’s Next

Now that basic OIDC is working, you can configure additional features in Grimmory’s OIDC Settings:

User Provisioning: Automatically create Grimmory accounts when users sign in for the first time
Group Mapping: Map Pocket ID groups to Grimmory permissions and library access
OIDC-Only Mode: Hide the local login form and redirect everyone to Pocket ID
Account Linking: Migrate existing local users to OIDC without losing their data

Troubleshooting

The Callback URL in Pocket ID must match the Redirect URI from Grimmory’s Provider Configuration Reference panel exactly.
Make sure Public Client is toggled ON in Pocket ID.
Verify the Client ID has no extra spaces.

”User Not Provisioned” Error

Auto-provisioning is off by default. Either enable it in OIDC Settings, or create a Grimmory user with a username that exactly matches the Pocket ID username (case-sensitive).

”Invalid Client” Error

Double-check the Client ID. Copy it fresh from Pocket ID.
Make sure the Issuer URI matches your Pocket ID URL exactly.

Grimmory Can’t Reach Pocket ID

If Test Connection fails, Grimmory’s server can’t reach the Pocket ID discovery endpoint. Common causes:

If both run in Docker, make sure they’re on the same network or that the external URL is reachable from Grimmory’s container.
Check DNS resolution: can the Grimmory container resolve the Pocket ID hostname?
Check firewall rules between the two services.

Can’t Access Grimmory At All

Admin backdoor: /login?local=true
Nuclear option: set FORCE_DISABLE_OIDC=true as an environment variable and restart