# Implementing External Authentication in Pangolin Using OIDC (PocketId)

**URL:** <https://forum.hhf.technology/t/implementing-external-authentication-in-pangolin-using-oidc-pocketid/1955>\
**Category:** General\
**Tags:** pocketid, pangolin\
**Created:** [May 15, 2025, 1:09pm UTC](https://forum.hhf.technology/t/implementing-external-authentication-in-pangolin-using-oidc-pocketid/1955 "2025-05-15T13:09:37Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![Mattercoder](https://forum.hhf.technology/letter_avatar_proxy/v4/letter/m/54ee81/32.png) [@Mattercoder](https://forum.hhf.technology/u/Mattercoder)\
**Post date:** [May 15, 2025, 1:09pm UTC](https://forum.hhf.technology/t/implementing-external-authentication-in-pangolin-using-oidc-pocketid/1955/1 "2025-05-15T13:09:37Z")

</div>

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.

 ![pocket-id-login](https://forum-cdn.hhf.technology/original/2X/8/8335f4efa5b199db6d9f281e2d1c850d1c90008d.png)

* * *

## 📄 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](https://forum.hhf.technology/t/using-aws-cloudformation-to-create-test-authentication-servers-for-pangolin-and-the-middleware-manager/1961) to quickly deploy PocketID.

* * *

## 🚀 Step 1: Upgrade Pangolin

Ensure you are running at least version `1.3.0`.

Update your Docker Compose:

```yaml
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:

```bash
docker compose down
docker compose up -d

```

* * *

## 🔑 Step 2: Set Up PocketId as OIDC Provider

1. Log into your PocketId dashboard.

2. Go to **OIDC Clients** and create a new one.

3. Set the callback URL to:

 ![creating_oidc](https://forum-cdn.hhf.technology/original/2X/4/4115b7a9ac938149e07a9c255ca86cc6adc71e28.png)

1. After creating the OIDC configuration, retrieve the **Client ID** and **Client Secret**.

 ![after_created_oidc](https://forum-cdn.hhf.technology/original/2X/c/c3362be3d793d3108d407a7eb76b8b0d8dc3adae.png)

* * *

## 🧠 Step 3: Create Identity Provider in Pangolin

1. In Pangolin, go to **Server Admin \> Identity Providers**

2. Click **Create Identity Provider**

3. Fill in the following:

 ![pangolin_side](https://forum-cdn.hhf.technology/original/2X/9/9a8fc455326b070489a01affd903fd0f26ee81df.png)

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

1. Go to **Organization \> Access Control**
2. Then **Users**
3. Click **Create User** , select **External User**
4. Under **Identity Provider** , choose **PocketId**
5. Set the **Username** to the email or ID used in PocketId

 ![adding_oidc_user1](https://forum-cdn.hhf.technology/original/2X/1/1278d6db2f2bd3e7a71ff4c9a51d8a299dc030be.png)

 ![adding_oidc_user2](https://forum-cdn.hhf.technology/original/2X/8/81aeb7082c4802dfec19a56883a7ca77609c8a9c.png)

* * *

## ⚙ Step 5: Test with a Sample Web App

### 5.1 Start a Simple HTTP Server

```yaml
  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:

```bash
docker compose up -d

```

### 5.2 Create a Resource in Pangolin

1. Go to **Resources** in Pangolin

2. Click **Create Resource**

3. Use:

 ![provisioning_user_to_resource1](https://forum-cdn.hhf.technology/original/2X/8/8189e9873951e13482638940f11d52605c34fb45.jpeg)

### 5.3 Assign Role to User

1. Go to the created resource
2. Add the external user you created and assign them a role (e.g., `member`)

 ![provisioning_user_to_resource2](https://forum-cdn.hhf.technology/original/2X/f/fd44d0d126873cab043a07f4d49e7e1748d4c49c.png)

* * *

## 🧪 Step 6: Log In and Test

1. Open a new **Incognito** window

2. Visit:

3. 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

 ![if_dont_provision_user](https://forum-cdn.hhf.technology/original/2X/c/c9b8505fe09b29756676966e35847076d3c104e7.png)

**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! 🚀

---

<div class="post-metadata">

**Author:** ![netsrot303](https://forum.hhf.technology/letter_avatar_proxy/v4/letter/n/90ced4/32.png) [@netsrot303](https://forum.hhf.technology/u/netsrot303)\
**Post date:** [August 4, 2025, 8:54am UTC](https://forum.hhf.technology/t/implementing-external-authentication-in-pangolin-using-oidc-pocketid/1955/2 "2025-08-04T08:54:52Z")

</div>

Nice tutorial, it works with pangolin . Thanks.

I want to configure Headscale so that I can use Pocket ID to log in. I used this tutorial to install Pangolin and Headscale. [Integrating Headscale and Headplane with Pangolin](https://forum.hhf.technology/t/integrating-headscale-and-headplane-with-pangolin/930#p-1300-integrating-headscale-and-headplane-with-pangolin-1) Unfortunately, I can’t get Pocket ID and Headscale to work together. Do you have any ideas?

---

<div class="post-metadata">

**Author:** ![Mattercoder](https://forum.hhf.technology/letter_avatar_proxy/v4/letter/m/54ee81/32.png) [@Mattercoder](https://forum.hhf.technology/u/Mattercoder)\
**Post date:** [August 4, 2025, 9:10am UTC](https://forum.hhf.technology/t/implementing-external-authentication-in-pangolin-using-oidc-pocketid/1955/3 "2025-08-04T09:10:51Z")

</div>

Sorry I am not familiar with headscale