Identity-Aware Access

How Pangolin Authentication Works

Pangolin operates as an identity-aware proxy. Every request that arrives at your VPS hits Traefik first, which routes it to Pangolin's auth middleware before forwarding to the backend service. This means authentication happens at the edge, before traffic ever enters the WireGuard tunnel to your home network.

Pangolin supports three authentication modes for each resource you expose:

Step 1: Configure Built-in Authentication

Pangolin's built-in auth system is active by default after installation. Let's verify and strengthen it.

Enable Two-Factor Authentication

The admin account created during installation should immediately have 2FA enabled:

1. Log in to the Pangolin dashboard at https://pangolin.yourdomain.com.
2. Click your username in the top-right corner and select Account Settings.
3. Under Two-Factor Authentication, click Enable.
4. Scan the QR code with your authenticator app (Authy, Google Authenticator, Bitwarden, etc.).
5. Enter the verification code and save the backup codes in your password manager.

Create Additional Users

Avoid sharing the admin account. Create individual accounts for each person who needs access:

1. Navigate to Access Control → Users in the left sidebar.
2. Click Add User.
3. Choose Internal User for accounts managed by Pangolin, or External User if you're connecting an identity provider (covered next).
4. Assign a role: Admin (full control) or Member (access to assigned resources only).

Step 2: Connect an External Identity Provider (OIDC)

For a true SSO experience, connect Pangolin to an OpenID Connect provider. This lets users log in with their existing accounts from Google, Microsoft, or a self-hosted provider like Pocket ID or Authentik.

Pangolin supports any OIDC-compliant provider, plus dedicated integrations for Google Workspace and Microsoft Entra ID. Below, we'll walk through the setup with Pocket ID (a lightweight, self-hosted option popular with homelabbers) and then note the differences for Google.

Option A: Pocket ID (Self-Hosted OIDC)

Pocket ID is a minimalist identity provider that supports passkeys and OIDC. If you're already running it, integration takes just a few minutes.

In Pocket ID:

• • Navigate to Administration → OIDC Clients.
• • Click Add OIDC Client and name it "Pangolin".
• • Note the auto-generated Client ID and Client Secret. Leave the Callback URL blank for now.

In Pangolin:

• • Navigate to Server Admin → Identity Providers.
• • Click Add Identity Provider.
• • Fill in the OIDC configuration:

• • Click Create Identity Provider.
• • Copy the Redirect URI shown in the General tab.

Back in Pocket ID:

• • Edit the Pangolin OIDC client and paste the Redirect URI into Callback URLs.
• • Save your changes.

Option B: Google Workspace

If your household or team uses Google accounts, Pangolin's dedicated Google integration simplifies the setup:

• • In the Google Cloud Console, create an OAuth 2.0 Client ID under APIs & Services → Credentials.
• • Set the authorized redirect URI to the one Pangolin provides after you start the identity provider setup.
• • In Pangolin, select Google as the provider type and enter your Client ID and Client Secret.

The same process applies to Microsoft Entra ID, Authentik, Authelia, Keycloak, and any other OIDC-compliant provider. Pangolin's generic OIDC configuration accepts Authorization URL, Token URL, and Userinfo URL from any provider.

Step 3: Configure Per-Service Auth Policies

The real power of Pangolin's identity layer is the ability to set different access policies per resource. Not every service needs the same level of protection.

Example Access Policy Matrix

Setting Auth on a Resource

For each resource in the Pangolin dashboard:

1. Navigate to Resources and select the resource.
2. Under Authentication, toggle Use Platform SSO on or off.
3. When SSO is enabled, only users who are logged into Pangolin and have been assigned to the resource's organization can reach it.
4. For resources that should be publicly accessible, leave SSO disabled.

Shareable Links for Guest Access

Pangolin's shareable links feature is a zero-trust alternative to handing out VPN credentials. You can generate a link that:

• • Expires after a set time (hours, days, or a specific date).
• • Is limited to a specific number of uses.
• • Can be revoked instantly from the dashboard.

This is ideal for sharing a Jellyfin library with a friend for the weekend, giving a contractor temporary access to an internal tool, or sharing a Nextcloud folder without creating a full user account.

Step 4: Configure Roles and Organizations

Pangolin uses an organizational model to scope access. By default, the installer creates one organization. For a typical homelab, this single organization is sufficient, but Pangolin supports multiple organizations if you manage services for different groups.

Within each organization, you can assign users to roles:

• • Admin: Full access to all resources and the ability to manage users, sites, and configuration.
• • Member: Access only to resources explicitly assigned to them. Cannot modify configuration.

Step 5: Test Your Configuration

With auth configured, run through these verification steps:

Security Considerations

Pangolin's identity layer gives you significantly more control than exposing services behind basic auth or a VPN, but there are some important things to keep in mind:

What's Next