Implementing External Authentication in Pangolin Using OIDC (Google OAuth)
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 Google OAuth as your identity provider but the process should be the same for most Idps.
The diagram above show a screenshot of the Pangolin login page with a Google login option.
Prerequisites
- A working Pangolin setup
- A domain name with DNS pointing to your Pangolin server (e.g.
pangolin.yourdomain.com) - A Google account with access to the Google Cloud Console
Step 1: Upgrade Pangolin
Ensure you’re using at least v1.3.0 or the latest, which supports external identity providers.
Update your Docker Compose to have the latest version of Pangolin.
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 Google OAuth
- Go to the Google Cloud Console
- Navigate to APIs & Services > Credentials
- Click Create Credentials → OAuth client ID
- Choose Web Application
- Add an Authorized redirect URI — you’ll get this later from Pangolin, but it will look like:
https://pangolin.yourdomain.com/auth/idp/1/oidc/callback
You may need to return to update this URI after completing Pangolin setup in Step 3
The diagram above shows the Google Console with the redirect URI input box.
Copy your Client ID and Client Secret.
Step 3: Create a New Identity Provider in Pangolin
- In Pangolin, go to Server Admin → Identity Providers
- Click Create Identity Provider
Fill in the fields:
- Name:
Google - Client ID / Client Secret: Use values from the Google Console
OAuth URLs:
- Authorization URL:
https://accounts.google.com/o/oauth2/v2/auth - Token URL:
https://oauth2.googleapis.com/token
Token Configuration:
- Set
Identifier Pathtoemail
The diagram above shows the filled-out Identity Provider form in Pangolin.
Click Create Identity Provider.
Copy the Redirect URL provided (e.g., https://pangolin.yourdomain.com/auth/idp/1/oidc/callback) and return to Google Cloud Console to paste it in the Authorized redirect URIs.
Step 4: Add a Google User in Pangolin
- Go to Organization → Users
- Click Create User
- Choose External User
- Select Google as the Identity Provider
- Set the username as the email address of the Google account you’ll use to sign in
Step 5: Test with a Sample Web App
You don’t need this step if you already have a resource that you’d like to protect.
5.1 Start a Simple HTTP Server
Add this to your docker-compose.yml for a temporary test 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
- Create a new resource:
- Name:
local-http - URL:
https://local-http.yourdomain.com - IP / Hostname:
python-http - Port:
15000
- Name:
- Assign a Role (e.g.,
member)
The diagram above shows the new resource form with values filled out.
The diagrams above show the proxy settings and authentication settings
Step 6: Try Logging In
- Open an Incognito Window (to avoid existing cookies). If you are still logged in you may need to clear cookies.
- Visit:
https://local-http.yourdomain.com - You should be greeted by a login screen with the Google login button
Above shows the Pangolin login screen with Google option
- Click Google
- You will be redirected to Google’s login page. Use the account you configured.
- On success, you’ll return to the HTTP test page
Above shows a successful login flow and arrival at the web page
Step 7: Troubleshooting
- Google error (400):
- Check that the redirect URI in the Google Console matches Pangolin’s exactly
- Login works but user is unauthorized:
- Make sure the user’s username and email in Pangolin matches the Google account email
- Ensure the correct role is assigned to that user
- Scope errors:
- Check the scopes used by Pangolin and that
emailis correctly parsed via the Identifier Path
- Check the scopes used by Pangolin and that
Summary
In this guide, we showed how to use Google as an external OIDC identity provider to authenticate users in Pangolin. You now have a fully working setup where Google handles identity, and Pangolin handles access control to internal services.
Thank You
Thanks for following along! Pangolin is evolving quickly, and support for OIDC brings it closer to becoming a truly enterprise-ready secure access gateway. If you found this helpful, feel free to explore other features like middleware-manager and join our discord.
Happy authenticating!