This guide demonstrates how to implement seamless OAuth2 authentication for your Pangolin resources using PocketID and the Traefik OIDC plugin. Unlike traditional setups that require users to navigate through multiple login pages, this approach redirects users directly to PocketID’s login page where they can authenticate with passkeys.
Why This Matters
Traditional authentication flows often require users to:
- Visit your application
- Get redirected to Pangolin’s login page
- Click to authenticate with a third-party provider
- Complete authentication and return to your app
With this direct OAuth2 implementation:
- Users visit your protected resource
- They’re immediately redirected to PocketID
- They authenticate with passkeys
- They’re returned directly to your application
This streamlined experience feels more professional and reduces friction for your users.
Prerequisites
- Pangolin with Middleware Manager installed
- A domain with DNS properly configured
- Basic understanding of OAuth2/OIDC concepts
Step 1: Set Up PocketID Authentication Server
First, you’ll need a running PocketID instance. You can follow our guide on Using AWS CloudFormation to Create Test Authentication Servers to quickly deploy PocketID.
Alternatively, you can add the following to your docker compose to run pocketid on your VPS
pocketid:
image: ghcr.io/pocket-id/pocket-id
container_name: pocketid
restart: unless-stopped
env_file: .env
volumes:
- "./pocketid:/app/backend/data"
and include the following in your dynamic_config.yml file
# Add these lines for pocketid
# pocketid http redirect router
pocketid-router-redirect:
rule: "Host(`pocketid.yourdomain.com`)"
service: pocketid-service
entryPoints:
- web
middlewares:
- redirect-to-https
# pocketid router
pocketid:
rule: "Host(`pocketid.yourdomain.com`)"
service: pocketid-service
entryPoints:
- websecure
tls:
certResolver: letsencrypt
pocketid-service:
loadBalancer:
servers:
- url: "http://pocketid:1411"
Once deployed, your PocketID instance should be accessible at https://pocketid.yourdomain.com.
Step 2: Configure PocketID Admin Account
When accessing PocketID for the first time, you’ll need to set up an admin account:
- Navigate to
https://pocketid.yourdomain.com/setup - Follow the prompts to create your administrator account
- Register a passkey for secure authentication
Step 3: Create an OIDC Client in PocketID
Now you’ll create an OAuth2/OIDC client that your applications will use:
- Log in to PocketID admin interface
- Navigate to the Clients section
- Create a new client with these settings:
- Name: MyAuth (or any descriptive name)
- Callback URL:
https://*.yourdomain.com/oidc/callback(wildcard allows any subdomain)
- Save the client configuration
- Important: Copy the generated Client ID and Client Secret - you’ll need these later
Step 4: Add the OIDC Plugin to Traefik
Edit your config/traefik/traefik_config.yml file to include the OIDC authentication plugin:
experimental:
plugins:
traefik-oidc-auth:
moduleName: "github.com/sevensolutions/traefik-oidc-auth"
version: "v0.11.0"
Step 5: Create the OIDC Middleware
- Open the Pangolin Middleware Manager
- Navigate to the Middlewares tab
- Click Create Middleware
- Select Plugin as the middleware type
- Name it “Traefik OIDC Auth” (or similar)
- Enter the following JSON configuration, replacing the placeholder values with your actual Client ID, Client Secret, and PocketID domain:
{
"traefik-oidc-auth": {
"Provider": {
"ClientId": "ee55e81a-e06f-408a-92cf-5f7dd55a1a70",
"ClientSecret": "YourClientSecret",
"TokenValidation": "IdToken",
"Url": "https://pocketid.yourdomain.com"
},
"Scopes": [
"openid",
"profile",
"email"
]
}
}
- Click Update Middleware
Step 6: Protect Your Resources
- From the Middleware Manager dashboard, select the resource you want to protect
- Click Manage
- Under Attached Middlewares, click Add Middleware
- Select your newly created OIDC middleware
- Click Add Middlewares
- Save your changes
Step 7: Test the Authentication Flow
- Open an incognito/private browser window
- Navigate to your protected resource (e.g.,
https://app.yourdomain.com) - You should be immediately redirected to the PocketID login page
- Authenticate using your passkey
Step 8: Consent Screen (First-time Access)
The first time you access a protected resource, PocketID will display a consent screen asking permission to share your information with the application.
- Review the requested permissions
- Click Allow to proceed
After granting consent, you’ll be redirected to your protected resource, now authenticated!
Troubleshooting
Issue: Not being redirected to PocketID when accessing a protected resource after clearing cookies.
Solution: Browser caching can sometimes interfere with the authentication flow. Try:
- Open Developer Tools (F12 or Right-click > Inspect)
- Navigate to Application > Storage
- Click “Clear site data” to completely remove all stored data for the site
- Reload the page
Summary
This direct OAuth2 authentication approach with PocketID and the Traefik OIDC plugin offers:
- A streamlined, professional user experience
- Secure passkey authentication
- No intermediate login pages
- Simplified user journey
By implementing this solution, you’re providing your users with a modern, frictionless authentication experience while maintaining robust security standards.
Thanks for Reading
We hope this guide helps you implement a smoother authentication flow for your Pangolin resources. If you have questions or need further assistance, please visit our community forum.