Pangolin now supports external identity providers using OAuth2/OIDC. This powerful feature allows Pangolin to act as a full authentication proxy and replace both Pangolin’s own login system and protect downstream services that don’t natively support SSO. In this guide, we’ll demonstrate how to use PocketId as your identity provider. PocketId is a simple but powerful OIDC Provider for SSO with Passkeys.
Prerequisites
- A working Pangolin setup (v1.3.0 or later)
- A domain name with DNS pointing to your Pangolin server (e.g.,
pangolin.yourdomain.com) - A PocketId server deployed and accessible over HTTPS. Note, you can follow our guide on Using AWS CloudFormation to Create Test Authentication Servers to quickly deploy PocketID.
Step 1: Upgrade Pangolin
Ensure you are running at least version 1.3.0.
Update your Docker Compose:
services:
pangolin:
image: fosrl/pangolin:1.3.0
container_name: pangolin
restart: unless-stopped
volumes:
- ./config:/app/config
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3001/api/v1/"]
interval: "3s"
timeout: "3s"
retries: 5
Restart your containers:
docker compose down
docker compose up -d
Step 2: Set Up PocketId as OIDC Provider
-
Log into your PocketId dashboard.
-
Go to OIDC Clients and create a new one.
-
Set the callback URL to:
https://*.yourdomain.com/auth/idp/2/oidc/callback
- After creating the OIDC configuration, retrieve the Client ID and Client Secret.
Step 3: Create Identity Provider in Pangolin
-
In Pangolin, go to Server Admin > Identity Providers
-
Click Create Identity Provider
-
Fill in the following:
- Name: PocketId
- Client ID / Secret: from PocketId
- Authorization URL:
https://<your-pocketid-domain>/oidc/auth - Token URL:
https://<your-pocketid-domain>/oidc/token - Identifier Path:
preferred_username
Click Create Identity Provider. You’ll receive a Redirect URI to add to your PocketId configuration if needed.
Step 4: Add a PocketId User in Pangolin
- Go to Organization > Access Control
- Then Users
- Click Create User, select External User
- Under Identity Provider, choose PocketId
- Set the Username to the email or ID used in PocketId
Step 5: Test with a Sample Web App
5.1 Start a Simple HTTP Server
python-http:
image: python:3.11-slim
container_name: python-http
working_dir: /app
command: python -m http.server 15000
ports:
- "15000:15000"
restart: unless-stopped
Start it:
docker compose up -d
5.2 Create a Resource in Pangolin
-
Go to Resources in Pangolin
-
Click Create Resource
-
Use:
- Name:
local-http - URL:
https://local-http.yourdomain.com - Host:
python-http - Port:
15000
- Name:
5.3 Assign Role to User
- Go to the created resource
- Add the external user you created and assign them a role (e.g.,
member)
Step 6: Log In and Test
-
Open a new Incognito window
-
Visit:
https://local-http.yourdomain.com -
You should see the Pangolin login page with PocketId as a login option
Click the PocketId button, sign in, and return to the HTTP page.
Step 7: Troubleshooting
Redirect URI mismatch:
- Ensure PocketId allows wildcard callback URLs or has the exact redirect URI
User not authorized:
- Check the user is provisioned and has the correct role in Pangolin
No login button shows:
- Confirm the Identity Provider is enabled and correctly linked
Summary
In this guide, we showed how to set up PocketId as an external OIDC identity provider for Pangolin. This provides a fully working, modern authentication flow to protect services with minimal configuration.
Thank You
Thanks for following along! External OIDC integration is a powerful step toward building secure, flexible infrastructure with Pangolin. Try using PocketId alongside other supported providers like Authelia or Authentik, and explore more with Middleware Manager.
Happy authenticating!