docs: add new Access Control and Logs documentation pages

- Documented Access Control features (e.g., Device Approvals, Password Rotation, 2FA, Custom Login Pages).
- Added detailed descriptions for Logs & Analytics (Access Logs, Request Logs, Action Logs).
- Included configuration instructions and feature-specific notes for Pangolin Cloud and Enterprise Edition.

Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
This commit is contained in:
2026-03-11 11:24:24 +01:00
parent a70f132fd9
commit aa157e82f8
87 changed files with 13163 additions and 0 deletions
@@ -0,0 +1,130 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Add Identity Providers
> Configure external identity providers for user authentication to resources and the organization
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
Identity providers allow your users to log into Pangolin and Pangolin resources using their existing accounts from
external identity systems like Google, Microsoft Azure, or Okta. Instead of creating separate Pangolin accounts, users
can authenticate with their familiar work or personal credentials.
Here is an example using Microsoft Azure Entra ID as SSO for Pangolin:
<iframe className="w-full aspect-video rounded-xl mb-10" src="https://www.youtube.com/embed/41OWI8uHPZg?si=VYGGAerzsIDe6wUx" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
**This feature is for you if:**
* Your organization already uses an identity provider like Google Workspace, Microsoft Entra ID, Okta, or similar
systems
* You want to centralize user management and avoid maintaining separate Pangolin accounts
* You need to control who can access Pangolin resources through your existing user directory
* You want users to access Pangolin using their existing credentials without creating new passwords
<Frame>
<img src="https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp.png?fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=7842df2fca1c9fb330e214dd17a91ad7" data-og-width="3128" width="3128" data-og-height="2532" height="2532" data-path="images/create-idp.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp.png?w=280&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=e7c1c8ea6a857d99ed635ba77d802407 280w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp.png?w=560&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=03d178870ef346b3298255e2b51acf7b 560w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp.png?w=840&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=9a1087aa00b414043a2cf5861bdc7696 840w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp.png?w=1100&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=822832141e3935d3a7307745abd932b8 1100w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp.png?w=1650&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=4293b058d4db25dd9a7d771629627e84 1650w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp.png?w=2500&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=4b4af690c71f3d1d0ffb7b0e59601707 2500w" />
</Frame>
## Identity Provider Types
### Organization Identity Providers
Organization identity providers are configured per organization and only apply to that specific organization. Each org
can have its own identity providers, allowing for authentication methods based on the organization's needs.
<Note>
Available in Pangolin Cloud and [Enterprise Edition](/self-host/enterprise-edition). For [Enterprise Edition](/self-host/enterprise-edition), you must set `app.identity_provider_mode: "org"` in the [private config file](/self-host/advanced/private-config-file#param-identity-provider-mode) `privateConfig.yml`.
</Note>
### Global Identity Providers
Global identity providers are managed at the server level and not the individual organization. They can apply to all or
some organizations on the server. This means you must define policies per organization to map users to specific
organizations and roles within those organizations.
<Tip>
Global identity providers are the only supported method in Pangolin Community.
</Tip>
## Supported Identity Providers
### OAuth2/OIDC
This can be used to connect to any external identity provider that supports the OpenID Connect protocol such as:
* Authentik
* Keycloak
* Okta
* Other OIDC-compliant providers
### Google
<Note>
Google IdP is only available in Pangolin Cloud or self-hosted [Enterprise Edition](/self-host/enterprise-edition) with organization identity providers. See above to enable.
</Note>
Easily set up Google Workspace authentication for your organization. Users can sign in with their Google accounts and
access Pangolin resources using their existing Google credentials. Perfect for organizations already using Google
Workspace for email, calendar, and other services.
### Azure Entra ID
<Note>
Azure Entra ID IdP is only available in Pangolin Cloud or self-hosted [Enterprise Edition](/self-host/enterprise-edition) with organization identity providers. See above to enable.
</Note>
Integrate with Microsoft's enterprise identity platform to allow users to authenticate using their Azure Active
Directory accounts. Ideal for organizations using Microsoft 365 or other Azure services, providing seamless single
sign-on across your Microsoft ecosystem.
## How to Add an Identity Provider
<Note>
When using global IDPs, identity providers are created and managed via the Server Admin UI rather than the organization settings.
</Note>
<Steps>
<Step title="Navigate to Identity Providers">
In the Pangolin organization, select the "Identity Providers" section in the sidebar.
</Step>
<Step title="Add New Provider">
Click on the "Add Identity Provider" button.
</Step>
<Step title="Select Type">
Select the type of identity provider you want to add (OAuth2/OIDC, Google, Azure Entra ID).
</Step>
<Step title="Set up Auto Provisioning (Optional)">
Select the "Auto Provision Users" checkbox to automatically provision users and assign roles in Pangolin when they log in using an external identity provider. See [Auto Provision](/manage/identity-providers/auto-provisioning) for more information.
If this is disabled, you will need to pre-provision a user in Pangolin before they can log in using an external identity provider.
</Step>
<Step title="Configure Settings">
Fill in the required fields for the selected identity provider type.
</Step>
</Steps>
## Custom Login Page
You can [configure a custom login page](/manage/access-control/login-page) for your organization to be served at a
domain of your choice. The log in page for every resource will be served at this URL. Additionally, you can visit this
url to log in to the organization itself to access the Pangolin dashboard. This is particularly useful for identity
providers because it creates a place for your users to go to select the identity provider of choice to access the
Pangolin dashboard.
## Auto Provisioning
See [Auto Provision](/manage/identity-providers/auto-provisioning) for more information on how to automatically
provision users and assign orgs and roles in Pangolin when they log in using an external identity provider.
@@ -0,0 +1,236 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Auto Provisioning
> Automatically create and manage user accounts from external identity providers
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
Auto provisioning is a feature that allows you to automatically create and manage user accounts in Pangolin when they
log in using an external identity provider rather than pre-provisioning a user with a role. This is useful for
organizations that want to streamline the onboarding process for new users and ensure that their user accounts are
always up-to-date.
You will be able to programmatically decide the roles and organizations for new users based on the information provided
by the identity provider.
## Enable Auto Provision
Toggle the "Auth Provision Users" switch when creating or editing an identity provider.
<Frame>
<img src="https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/auto-provision.png?fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=44c247dc30f7a5266dc340e47fc470ef" data-og-width="1954" width="1954" data-og-height="808" height="808" data-path="images/auto-provision.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/auto-provision.png?w=280&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=777cd3d25925145c92e0fca2cf809b8d 280w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/auto-provision.png?w=560&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=fca86ed2900a9dacbf40041867657891 560w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/auto-provision.png?w=840&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=cc7c17cc0e79b8da71d68c72bb841b47 840w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/auto-provision.png?w=1100&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=c6147e183bd9c6d2b441ef69cde24001 1100w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/auto-provision.png?w=1650&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=264b1f08eba2bd8683f4516f43982c37 1650w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/auto-provision.png?w=2500&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=593e490b8391eed55361ddf3827df229 2500w" />
</Frame>
## What if Auto Provisioning is Disabled?
If auto provision is disabled, organization admins will need to manually create the user accounts and select the role
for each user. When creating a user, you can select the identity provider that the user will be associated with. A user
will not be able to log in using the identity provider if a user is not pre-provisioned in the system.
<Frame>
<img src="https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp-user.png?fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=313f47df0e17b9c26d626e6c96215737" data-og-width="3106" width="3106" data-og-height="1294" height="1294" data-path="images/create-idp-user.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp-user.png?w=280&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=54088316452b1708c95c43b2bec3cf1a 280w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp-user.png?w=560&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=09349719035c649e5d000510c9586d82 560w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp-user.png?w=840&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=451f020c34593555d8ccb7cfc131b672 840w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp-user.png?w=1100&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=0614dfb4ba3c6d0df4c9f4244878bf78 1100w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp-user.png?w=1650&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=93623e0cd07d06bafc34e3b9cff34d6d 1650w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-idp-user.png?w=2500&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=ec6a9ecbb66432375cd0af57c112095d 2500w" />
</Frame>
## Configuration Options
## Selecting Roles
You can choose between "Select a Role" and "Expression". Selecting a role will apply that role to all auto provisioned
users. The expression will be evaluated against the token response from the IdP on each login (see examples below). You
can always manually change the role of the user after they're provisioned.
### Expressions
Use JMESPath to map attributes from the identity provider to roles in Pangolin. See [JMESPath](https://jmespath.org/)
for more information on how to use JMESPath.
The expression will be matched against each organization. Meaning:
* The result of the expression must return the exact string of the role name as it is defined in the organization.
* If no matching role is found, the user will not be added to the organization.
### Example: Role Selection
**Expression:**
<Note>
When entering in a string, JMESPatch requires it be surrounded by `'` (single quotes). See below:
</Note>
```
contains(groups, 'admin') && 'Admin' || 'Member'
```
**Identity Provider Data:**
```json theme={null}
{
...
"sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
"aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
"exp": 1745790819,
"iat": 1745789019,
"auth_time": 1745789019,
"email": "user@example.com",
"email_verified": true,
"name": "Example User",
"groups": [
"home-lab",
"admin"
]
}
```
This example will return the string "Admin". If the user is not a member of the "admin" group, it will return "Member".
## Global Identity Providers
After you create an IdP, on the edit page, you can manage organization policies via the "Organization Policies" tab. You
can set default (fallback) policies, or define them on a per org basis.
### How Organization Policies Are Evaluated
It is helpful to think of the auto provisioning process as follows:
<Steps>
<Step title="User Login">
User successfully logs in using an identity provider.
</Step>
<Step title="Account Creation">
Pangolin creates a user account for the user.
</Step>
<Step title="Organization Evaluation">
Pangolin will loop through each organization and evaluate the JMESPath expression for the organization. If the expression does not return true or the same ID as the current organization, the user will not be added to the organization.
</Step>
<Step title="Role Assignment">
For each organization, Pangolin will evaluate the JMESPath expression for the role. If no role is found with the exact name in that organization, the user will not be added to the organization.
</Step>
</Steps>
### Selecting Roles
See above examples.
### Selecting Organizations
Use JMESPath to map attributes from the identity provider to organizations in Pangolin.
See [JMESPath](https://jmespath.org/) for more information on how to use JMESPath.
The expression will be matched against each organization. Meaning:
* The result of the expression must return true or the organization ID as it is defined in the system.
* If no matching organization is found, the user will not be added to the organization.
You can insert the template variable `{{orgId}}` in the expression. This will be replaced with the organization ID when
the expression is evaluated.
### Example 1: Group-based Selection
**Expression:**
```
contains(groups, 'home-lab')
```
**Identity Provider Data:**
```json theme={null}
{
...
"sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
"aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
"exp": 1745790819,
"iat": 1745789019,
"auth_time": 1745789019,
"email": "user@example.com",
"email_verified": true,
"name": "Example User",
"groups": [
"home-lab",
"admin"
]
}
```
This example will return true since the user is a member of the "home-lab" group.
### Example 2: Fixed Organization
<Note>
When entering in a string, JMESPatch requires it be surrounded by `'` (single quotes). See below:
</Note>
**Expression:**
```
'home-lab'
```
**Identity Provider Data:**
```json theme={null}
{
...
"sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
"aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
"exp": 1745790819,
"iat": 1745789019,
"auth_time": 1745789019,
"email": "user@example.com",
"email_verified": true,
"name": "Example User",
"groups": [
"home-lab",
"admin"
]
}
```
### Default (Fallback) Policy
You can optionally configure a default policy for all organizations. This will be used if the organization does not have
its own policy configured.
This example will always return 'home-lab' meaning the user will always be added to the "home-lab" organization.
### Example 1: Dynamic Organization Selection
**Expression:**
```
contains(groups, '{{orgId}}')
```
**Identity Provider Data:**
```json theme={null}
{
...
"sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
"aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
"exp": 1745790819,
"iat": 1745789019,
"auth_time": 1745789019,
"email": "user@example.com",
"email_verified": true,
"name": "Example User",
"groups": [
"home-lab",
"admin"
]
}
```
When Pangolin evaluates this expression against the "home-lab" organization, it will replace `{{orgId}}` with "
home-lab". The result of the expression will return true since the user is a member of the "home-lab" group.
@@ -0,0 +1,76 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Azure Entra ID
> Configure Azure Entra ID Single Sign-On
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
<Note>
Azure SSO is only available on Pangolin Cloud and [Enterprise Edition](/self-host/enterprise-edition) deployments. In [Enterprise Edition](/self-host/enterprise-edition), you must set `app.identity_provider_mode: "org"` in your [private config file](/self-host/advanced/private-config-file) `privateConfig.yml`.
</Note>
The following steps will integrate Microsoft SSO using the built in Azure Entra ID identity provider in Pangolin.
<iframe className="w-full aspect-video rounded-xl mb-10" src="https://www.youtube.com/embed/41OWI8uHPZg?si=VYGGAerzsIDe6wUx" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
<Accordion title="How to create and set up an App Registration in Microsoft Azure from scratch">
#### Create an App Registration
In Azure, go to "Microsoft Entra ID". Under "Manage", click "App registrations". On the "All applications" tab, select "
Register an application".
Give it a name like "Pangolin", select your preferred supported account types, and click "Register". Leave the redirect
URI blank for now; we will come back to this.
#### Copy Credentials
On the new app registration, select the "Overview" tab. Here, you can copy the "Application (client) ID" and save for
later.
Now we need to generate the client secret. Click "Add a certificate or secret". Then click "New client secret". Enter a
description like "Pangolin credentials" and choose an expiration time. Note that once this secret expires, you will need
to generate a new one and replace it in the Pangolin dashboard for the associated IdP.
Copy the "Value" field and save for later.
<Note>
We will revisit the **Authorised redirect URIs** field later, as we do not have Pangolin set up for Azure yet.
</Note>
</Accordion>
## Creating an Azure Entra ID IdP in Pangolin
In Pangolin, go to "Identity Providers" and click "Add Identity Provider". Select the Azure Entra ID provider option.
<Frame>
<img src="https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-azure-idp.png?fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=d82e3eb69d195194cf6a5bc189ddfbd4" data-og-width="3128" width="3128" data-og-height="2348" height="2348" data-path="images/create-azure-idp.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-azure-idp.png?w=280&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=3b573a3690e4a6e2188a58e05bc8ebc3 280w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-azure-idp.png?w=560&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=deba9e186c12bd56dd298ec1324f3399 560w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-azure-idp.png?w=840&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=b9772050c50b43d6d31af8f55f4c9f9b 840w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-azure-idp.png?w=1100&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=7a809bd35cb64fc1f1a2dbcbc3cf8458 1100w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-azure-idp.png?w=1650&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=b22b0541b5afa86f7af2e17ca257ee03 1650w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-azure-idp.png?w=2500&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=07a87b291f582745c948373dca573ab1 2500w" />
</Frame>
In the OAuth2/OIDC Configuration, you'll need the following fields:
<ResponseField name="Client ID" type="string" required>
The application (client) ID from the "Overview" section of your app registration
</ResponseField>
<ResponseField name="Client Secret" type="string" required>
The client secret value from the "Certificates and secrets" section of your app registration
</ResponseField>
## Token Configuration
When you're done, click "Create Identity Provider". Then, copy the Redirect URL in the "General" tab as you will now
need this for your app registration.
## Returning to Azure
Lastly, you'll need to return to your app registration in order to add the redirect URI created by Pangolin. On the "
Overview" tab, click "Add a Redirect URI". The click "Add a platform", and select "Web". Here, you can add the redirect
URL from Pangolin and click "Configure". Your configuration should now be complete. You'll now need to add an external
user to Pangolin, or if you have "Auto Provision Users" enabled, you can now log in using Azure SSO.
@@ -0,0 +1,89 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Google
> Configure Google Single Sign-On
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
<Note>
Google SSO is only available on Pangolin Cloud and [Enterprise Edition](/self-host/enterprise-edition) deployments. In [Enterprise Edition](/self-host/enterprise-edition), you must set `app.identity_provider_mode: "org"` in your [private config file](/self-host/advanced/private-config-file#param-use-org-only-idp) `privateConfig.yml`.
</Note>
The following steps will integrate Google SSO using the built in Google identity provider in Pangolin.
<iframe className="w-full aspect-video rounded-xl mb-10" src="https://www.youtube.com/embed/Xh4sl-9wK2I?si=hQvKusR-YPzGnP73" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
<Accordion title="How to create and set up a Google Project from scratch">
[Create a new Project](https://console.cloud.google.com/projectcreate), or use an [existing Project](https://console.developers.google.com/) you've already created in the Google Developers Console. Setting the organization isn't required, unless you intend to use SSO for [more than 100 users](https://support.google.com/cloud/answer/13464323) externally (not via Google Workspace).
Once created, or you've opened an existing Project, you may be on the project dashboard, where you will need to open the
sidebar. If you are on the welcome page, continue by
selecting [OAuth consent screen](https://console.cloud.google.com/auth/overview) in "APIs and services".
You should see that Google Auth Platform is not configured. Press "Get started" and fill in the relevant information,
such as your "App name" and "User support email". These will be visible when the user is authenticating.
After continuing, you can select an "Audience". If you are using Pangolin for friends and family, use the "External"
Audience. You can only have 100 users authenticated with a "Testing" status.
<Note>
Depending on your use case, you may want to use the "Internal" Audience if you are utilising Google Workspace SSO.
</Note>
Once completed, you will then need to open the [Branding](https://console.cloud.google.com/auth/branding) tab.
Locate "Authorized domains", then press "Add domain" to add an authorized domain. You'll need to authorize the top
private (root) domain here, such as `example.com`. Your SSO *may* function without an authorized domain, though setting
this field should guarantee functionality.
### Creating an OAuth client ID in your Project
Go to the [Clients](https://console.cloud.google.com/auth/clients) tab, and click "Create client" below the top bar.
For "Application type", select `Web application`. Any "Name" can be set. Leave "Authorised JavaScript origins" and "
Authorised redirect URIs" empty.
<Note>
We will revisit the "Authorised redirect URIs" field later, as we do not have Pangolin set up for Google yet.
</Note>
After hitting "Create", you will be able to see the "Client ID" and "Client secret", you may want to copy these
somewhere as these will be needed momentarily, though they will still be accessible in the future.
</Accordion>
## Creating a Google IdP in Pangolin
In Pangolin, go to "Identity Providers" and click "Add Identity Provider". Select the Google provider option.
<Frame>
<img src="https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-google-idp.png?fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=182addb05d1e71f3b069269d446a83bd" data-og-width="3134" width="3134" data-og-height="2172" height="2172" data-path="images/create-google-idp.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-google-idp.png?w=280&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=dafd9e50a8011cf1232e0acf87eb529f 280w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-google-idp.png?w=560&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=eb114b65669e5b441bae2e83496a237e 560w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-google-idp.png?w=840&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=383ae2ab8dd29ceec41c51c4fbf85d18 840w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-google-idp.png?w=1100&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=2f0ff2c22053611973341a33cdd3231e 1100w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-google-idp.png?w=1650&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=24de4c0c0b89522abd00819d98e29019 1650w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-google-idp.png?w=2500&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=8a99fc714f891f3a686ca93664d907c1 2500w" />
</Frame>
In the "Google Configuration", you'll need the following fields:
<ResponseField name="Client ID" type="string" required>
The Client ID from your Web application client.
</ResponseField>
<ResponseField name="Client Secret" type="string" required>
The Client secret from your Web application client.
</ResponseField>
## Token Configuration
When you're done, click "Create Identity Provider". Then, copy the Redirect URL in the "General" tab as you will now
need this for your **Web application client**.
## Returning to Google Developers Console
Lastly, you'll need to return to your "Web application client" in order to add the redirect URI created by Pangolin. Add
the URI to "Authorized redirect URIs", then hit "Save"! Your configuration should now be complete. You'll now need to
add an external user to Pangolin, or if you have "Auto Provision Users" enabled, you can now log in using Google SSO.
@@ -0,0 +1,79 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# OAuth2/OIDC
> Configure OpenID Connect identity provider for external authentication
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
This identity provider follows the OpenID Connect protocol. This means that it can be used to connect to any external
identity provider that supports the OpenID Connect protocol such as Authentik, Keycloak, Okta, etc.
## Creating a Generic OAuth2/OIDC IdP in Pangolin
In Pangolin, go to "Identity Providers" and click "Add Identity Provider". Select the OAuth2/OIDC provider option.
<Frame>
<img src="https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-oidc-idp.png?fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=dd9f3bbf95d4738c53d23e4144b921ca" data-og-width="2822" width="2822" data-og-height="2508" height="2508" data-path="images/create-oidc-idp.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-oidc-idp.png?w=280&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=959cc28c788c6fff1bff7a6420f24bf5 280w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-oidc-idp.png?w=560&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=4dde5daded22ab9671a17f1073f1e0ac 560w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-oidc-idp.png?w=840&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=8de3000d3d8c866f8492ed914a18be36 840w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-oidc-idp.png?w=1100&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=ae516f0c2759471c604211d55a46e232 1100w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-oidc-idp.png?w=1650&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=90192ca25fc10e2f87cc44cde256abc9 1650w, https://mintcdn.com/fossorial/46uJdNaFUIDsUEAs/images/create-oidc-idp.png?w=2500&fit=max&auto=format&n=46uJdNaFUIDsUEAs&q=85&s=4bd191c42e6c5e44de86766cb522da66 2500w" />
</Frame>
In the OAuth2/OIDC Configuration, you'll need the following fields:
<ResponseField name="Client ID" type="string" required>
The client identifier provided by your identity provider.
</ResponseField>
<ResponseField name="Client Secret" type="string" required>
The client secret provided by your identity provider.
</ResponseField>
<ResponseField name="Authorization URL" type="string" required>
The authorization endpoint URL from your identity provider.
</ResponseField>
<ResponseField name="Token URL" type="string" required>
The token endpoint URL from your identity provider.
</ResponseField>
## Token Configuration
Use JMESPath to select attributes from the claims token. See [JMESPath](https://jmespath.org/) for more information on
how to use JMESPath.
Determine how to access information from the claims token returned by the identity provider. This is used to map the
user information from the identity provider to the user information in Pangolin.
<ResponseField name="Identifier Path" type="string" required>
This must be unique for each user within an identity provider.
**Example**: `sub` or `user_id`
</ResponseField>
<ResponseField name="Email Path" type="string">
Path to the user's email address in the claims token.
**Example**: `email`
</ResponseField>
<ResponseField name="Name Path" type="string">
Path to the user's display name in the claims token.
**Example**: `name` or `preferred_username`
</ResponseField>
<ResponseField name="Scopes" type="string">
The scopes to request from the identity provider (not JMESPath; must be space-delimited strings).
**Default**: `openid profile email`
<Note>
Generally, `openid profile email` is sufficient for most use cases.
</Note>
</ResponseField>
@@ -0,0 +1,94 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Pocket ID
> Configure Pocket ID Single Sign-On using OpenID Connect
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
The following steps will integrate Pocket ID with Pangolin SSO using OpenID Connect (OIDC).
## Prerequisites
Before you can start, you'll need to have Pocket ID accessible and ensure it's not secured with Pangolin SSO.
### Creating an OIDC Client in Pocket ID
In Pocket ID, create a new OIDC Client.
<Steps>
<Step title="Set Name">
Set the name to something memorable (eg. Pangolin).
</Step>
<Step title="Configure Callback URL">
Leave blank or set a placeholder. We will come back to this step after creating the IdP and we know the redirect URL.
</Step>
<Step title="Keep Defaults">
All other values can be kept as default.
</Step>
</Steps>
<Note>
The callback URL is displayed in the IdP settings after you create the IdP in Pangolin.
</Note>
After you have created the OIDC Client, take note of the following fields from the top of the page (click "Show more
details" to see all of them):
* **Client ID**
* **Client secret**
* **Authorization URL**
* **Token URL**
## Configuring Identity Providers in Pangolin
In Pangolin, go to “Identity Providers” and click “Add Identity Provider”. Select the OAuth2/OIDC provider option.
"Name" should be set to something memorable (eg. Pocket ID). The "Provider Type" should be set to the default
`OAuth2/OIDC`.
### OAuth2/OIDC Configuration (Provider Credentials and Endpoints)
In the OAuth2/OIDC Configuration, you'll need the following fields:
<ResponseField name="Client ID" type="string" required>
The Client ID from your Pocket ID OIDC client.
</ResponseField>
<ResponseField name="Client Secret" type="string" required>
The Client secret from your Pocket ID OIDC client.
</ResponseField>
<ResponseField name="Authorization URL" type="string" required>
The Authorization URL from your Pocket ID OIDC client.
</ResponseField>
<ResponseField name="Token URL" type="string" required>
The Token URL from your Pocket ID OIDC client.
</ResponseField>
## Token Configuration
You should leave all of the paths default. In the "Scopes" field, add `openid profile email`.
<Note>
Set the "Identifier Path" to `preferred_username` for Pocket ID integration.
</Note>
When you're done, click "Create Identity Provider"! Then, copy the Redirect URL in the "General" tab as you will now
need this for your Pocket ID OIDC client.
## Returning to Pocket ID
Lastly, you'll need to return to your Pocket ID OIDC client in order to add the redirect URI created by Pangolin. Add
the URI to "Callback URLs", then save your changes! Your configuration should now be complete. You'll now need to add an
external user to Pangolin, or if you have "Auto Provision Users" enabled, you can now log in using Pocket ID SSO.
@@ -0,0 +1,113 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Zitadel
> Configure Zitadel Single Sign-On using OpenID Connect
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
The following steps will integrate Zitadel with Pangolin SSO using OpenID Connect (OIDC).
## Prerequisites
These instructions assume you have a working Zitadel organization and project setup already.
### Creating an Application in Zitadel
You need to configure an application in Zitadel:
<Steps>
<Step title="Create New Application">
Open an existing project and in `Applications` click `New`.
</Step>
<Step title="Configure Application">
Set the name to something memorable (eg. Pangolin).
</Step>
<Step title="Set Application Type">
For `Type of application` choose `Web`.
</Step>
<Step title="Set Authentication Method">
For `Authentication Method` choose `Code`.
</Step>
<Step title="Leave Redirect URIs Blank">
Leave `Redirect URIs` blank for now. We'll come back to this once the IdP is created.
</Step>
</Steps>
<Note>
When you click create, you'll be shown the `ClientSecret` and `ClientId`. Make sure to save these somewhere secure - you won't be able to see the Client Secret again.
</Note>
<Steps>
<Step title="Configure Token Settings">
Click `Token settings` then change `Auth Token Type` to `JWT` and check the `User Info inside ID Token` box finally hit `Save`.
</Step>
<Step title="Enable User Claims in ID Token">
Still in `Token settings`, check the box for `Include user's roles in the ID Token`. This enables Zitadel to include necessary user profile claims (including `preferred_username`) in the ID token, which Pangolin requires for user identification.
</Step>
<Step title="Note Endpoints">
Open `URLs` and make note of:
* `Authorization Endpoint`
* `Token Endpoint`
</Step>
</Steps>
## Configuring Identity Providers in Pangolin
In Pangolin, go to “Identity Providers” and click “Add Identity Provider”. Select the OAuth2/OIDC provider option.
"Name" should be set to something memorable (eg. Zitadel). The "Provider Type" should be set to the default
`OAuth2/OIDC`.
### OAuth2/OIDC Configuration (Provider Credentials and Endpoints)
In the OAuth2/OIDC Configuration, you'll need the following fields:
<ResponseField name="Client ID" type="string" required>
The Client ID from your Zitadel application.
</ResponseField>
<ResponseField name="Client Secret" type="string" required>
The Client Secret from your Zitadel application.
</ResponseField>
<ResponseField name="Authorization URL" type="string" required>
Use the `Authorization Endpoint` from your Zitadel application.
</ResponseField>
<ResponseField name="Token URL" type="string" required>
Use the `Token Endpoint` from your Zitadel application.
</ResponseField>
## Token Configuration
You should leave all of the paths default. In the "Scopes" field, add `openid profile email`.
<Note>
Set the "Identifier Path" to `preferred_username` for Zitadel integration.
</Note>
When you're done, click "Create Identity Provider"! Then, copy the Redirect URL in the "General" tab as you will now
need this for your **Zitadel application**.
## Returning to Zitadel
Lastly, you need to edit your `Redirect Settings` in your Zitadel application. Add the URL you copied to the
`Redirect URIs`, then hit the `+` button and finally `Save`. Your configuration should now be complete. You'll now need
to add an external user] to Pangolin, or if you have "Auto Provision Users" enabled, you can now log in using Zitadel
SSO.