openZro

PocketID with openZro Self-Hosted

PocketID is a simplified identity management solution designed for self-hosted environments, offering a lightweight and easy-to-deploy option for authentication.

PocketID is secure and effective but makes some tradeoffs in terms of features. Notably, it does not allow scoping the access of API Tokens. Keep careful track of the token used by openZro for management.

Add PocketID as an external IdP directly in the openZro Management Dashboard. This is the simplest approach and recommended for most deployments.

Prerequisites

  • openZro self-hosted with embedded IdP enabled
  • PocketID instance with admin access

Step 1: Create OIDC Client in PocketID

  1. Navigate to PocketID console
  2. Click the Administration dropdown in the left-hand bar
  3. Select OIDC Clients
  4. Click Add to create a new client

Add OIDC client

  1. Fill in the form:
    • Name: openZro
    • Public Client: Off (for confidential client)
    • PKCE: Off
  2. Click Save

Save OIDC client

  1. Note the Client ID and Client Secret

Note client ID

Step 2: Add Identity Provider in openZro

  1. Log in to your openZro Dashboard
  2. Navigate to Settings → Identity Providers
  3. Click Add Identity Provider
  4. Fill in the fields:
FieldValue
TypePocketID
NamePocketID (or your preferred display name)
Client IDFrom PocketID
Client SecretFrom PocketID
Issuerhttps://pocketid.example.com

Important: Make sure not to add a trailing slash "/" after the issuer URL for PocketID. This differs from some of the other providers.

  1. Click Save

openZro configuration

Step 3: Configure Redirect URI

After saving, openZro displays the Redirect URL. Copy this URL and add it to your PocketID client:

Copy redirect URL from openZro

  1. Return to PocketID console → OIDC Clients
  2. Edit your openZro client
  3. Add the redirect URL to Callback URLs

Add callback URL

  1. Click Save

Step 4: Create User Group and Assign to Client

  1. Return to PocketID console → User Groups
  2. Click Add to create a new group
  3. Fill in:
    • Name: openZro
  4. Click Save

Add user group

  1. Add users to the openZro group:
    • Click on the openZro group
    • Click Add Users
    • Select the users who should have access to openZro
    • Click Save or Add

Add users to group

  1. Go to OIDC Clients → openZro (the client you created earlier)
  2. Find the Groups or User Groups section
  3. Add the openZro group to the client

Add group to OIDC client

  1. Click Save

Step 5: Test the Connection

  1. Log out of openZro Dashboard
  2. On the login page, you should see a "PocketID" button
  3. Click it and authenticate with your PocketID credentials
  4. You should be redirected back to openZro and logged in

Configuring JWT 'groups' Claim

PocketID includes user groups in the ID token by default when you've assigned groups to users and linked those groups to the OIDC client. If you followed Step 4 above, groups should already be included in the token.

Verify Groups Are Included

  1. Ensure you've created a User Group in PocketID (Step 4)
  2. Ensure users are assigned to the group
  3. Ensure the group is linked to your openZro OIDC client

Enable JWT Group Sync in openZro

  1. In openZro Dashboard, go to Settings → Groups
  2. Enable JWT group sync
  3. Set JWT claim to groups
  4. Optionally configure JWT allow groups to restrict access to users in specific PocketID groups

PocketID restricts OIDC client access based on group membership. Only users in groups assigned to the OIDC client can authenticate. This is configured in Step 4 above.

Standalone Setup (Advanced)

The standalone setup wires PocketID as openZro's only identity provider — Dex is disabled and the management daemon talks directly to PocketID for token validation. Choose this path only if all three apply:

  1. You want to skip the Dex layer entirely. Unlike Keycloak or Zitadel, PocketID does not expose a writeback API to openZro — the management cannot list, invite, or delete users in PocketID. The standalone path's only motivation is removing one component (Dex) at the cost of multi-IdP support and the static admin fallback.
  2. You need just one IdP, and it's PocketID. The standalone path doesn't support multiple upstreams — there's no Dex to aggregate them.
  3. You're willing to give up the bootstrap admin fallback. No embedded local user store. If PocketID is down or misconfigured, nobody can log into the dashboard.

For everyone else — multi-IdP shops, anyone wanting a static admin fallback, or anyone unsure whether they'll outgrow PocketID later — stick with the Management Setup (Recommended) above. It runs Dex in front of PocketID and makes a future swap to a different IdP painless.

For detailed standalone instructions, see PocketID SSO with openZro Self-Hosted (Advanced).

Troubleshooting

"Invalid redirect URI" error

  • Ensure all callback URLs are properly configured in PocketID
  • Include both HTTP (localhost) and HTTPS (domain) variants