PocketID with NetBird Self-Hosted

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

Management Setup (Recommended)

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

Prerequisites

• NetBird 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

5. Fill in the form:
   • Name: NetBird
   • Public Client: Off (for confidential client)
   • PKCE: Off
6. Click Save

7. Note the Client ID and Client Secret

Step 2: Add Identity Provider in NetBird

1. Log in to your NetBird Dashboard
2. Navigate to Settings → Identity Providers
3. Click Add Identity Provider
4. Fill in the fields:

5. Click Save

Step 3: Configure Redirect URI

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

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

4. 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: NetBird
4. Click Save

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

6. Go to OIDC Clients → NetBird (the client you created earlier)
7. Find the Groups or User Groups section
8. Add the NetBird group to the client

9. Click Save

Step 5: Test the Connection

1. Log out of NetBird 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 NetBird 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 NetBird OIDC client

Enable JWT Group Sync in NetBird

1. In NetBird 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

Standalone Setup (Advanced)

Use PocketID as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced PocketID administrators as it also requires additional setup and ongoing maintenance.

For most deployments, the embedded IdP is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the Management Setup (Recommended) section above.

For detailed instructions on the standalone setup, see the PocketID SSO with NetBird Self-Hosted (Advanced) documentation.

Troubleshooting

"Invalid redirect URI" error

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

Related Resources

• PocketID Documentation
• Embedded IdP Overview