pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-02-08 05:56:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

test deploy

Browse Source
This commit is contained in:
miloschwartz
2025-07-31 21:44:10 -07:00
parent b918f105b5
commit 647080c1d5
33 changed files with 2045 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
manage/identity-providers/add-an-idp.mdx Normal file
View File

@@ -0,0 +1,58 @@
---
title: "Add Identity Providers"
description: "Configure external identity providers for user authentication"
---
<Note>
Identity providers are only available in self-hosted Pangolin instances.
</Note>
Identity providers let you authenticate Pangolin users using external identity providers. This is useful for organizations that want to use their existing identity provider infrastructure to manage user authentication.
For example, you may have users defined in Authentik, and you want these users to be able to log in to Pangolin using their existing credentials.
<CardGroup cols={2}>
<Card title="What it does" icon="users">
Allows users to authenticate using external identity providers instead of Pangolin's built-in authentication.
</Card>
<Card title="When to use" icon="gear">
Useful for organizations with existing identity infrastructure like Authentik, Keycloak, or Okta.
</Card>
</CardGroup>
## 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**
## How to Add an Identity Provider
<Steps>
<Step title="Access Server Admin">
Select the "Identity Providers" tab in the Server Admin UI.
</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).
</Step>
<Step title="Configure Settings">
Fill in the required fields for the selected identity provider type.
</Step>
</Steps>
## 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.

191
manage/identity-providers/auto-provisioning.mdx Normal file
View File

@@ -0,0 +1,191 @@
---
title: "Auto Provisioning"
description: "Automatically create and manage user accounts from external identity providers"
---
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. 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.
<CardGroup cols={2}>
<Card title="What it does" icon="users">
Automatically creates user accounts when users log in through external identity providers.
</Card>
<Card title="Benefits" icon="bolt">
Streamlines onboarding and keeps user accounts up-to-date with external identity systems.
</Card>
</CardGroup>
## Enable Auto Provision
Toggle the "Auth Provision Users" switch when creating or editing an identity provider.
## 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.
## How Auto Provisioning Works
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>
## Configuration Options
### Organization Policies
You can configure policy for each organization with its own roles selector expression and organization selector expression.
### 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.
## Selecting Roles
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
**Expression:**
```
contains(groups, 'admin') && 'Admin' || 'Member'
```
**Identity Provider Data:**
```json
{
...
"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".
## 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
{
...
"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
**Expression:**
```
'home-lab'
```
**Identity Provider Data:**
```json
{
...
"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 always return 'home-lab' meaning the user will always be added to the "home-lab" organization.
### Example 3: Dynamic Organization Selection
**Expression:**
```
contains(groups, '{{orgId}}')
```
**Identity Provider Data:**
```json
{
...
"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.

92
manage/identity-providers/google.mdx Normal file
View File

@@ -0,0 +1,92 @@
---
title: "Google SSO"
description: "Configure Google Single Sign-On using OpenID Connect"
---
The following steps will integrate **Google SSO** using **OpenID Connect (OIDC)**.
## Prerequisites
Before you can start, you'll need to create or edit a **Project** in [Google Developers Console](https://console.developers.google.com/).
### Setting up your Project
[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 and paying for access to the [Professional Edition](https://docs.fossorial.io/professional-edition).
</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.
<Steps>
<Step title="Select Application Type">
For **Application type**, select `Web application`.
</Step>
<Step title="Set Name">
Any **Name** can be set.
</Step>
<Step title="Leave Redirect URIs Empty">
Leave **Authorised JavaScript origins** and **Authorised redirect URIs** empty.
</Step>
</Steps>
<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.
## Configuring Identity Providers in Pangolin
In Pangolin, go to the **Server Admin** section. Select "Identity Providers" before proceeding with the "Add Identity Provider" button.
**Name** should be set to something memorable. 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 Web application client.
</ResponseField>
<ResponseField name="Client Secret" type="string" required>
The Client secret from your Web application client.
</ResponseField>
<ResponseField name="Authorization URL" type="string" required>
Set to `https://accounts.google.com/o/oauth2/v2/auth`.
</ResponseField>
<ResponseField name="Token URL" type="string" required>
Set to `https://oauth2.googleapis.com/token`.
</ResponseField>
## Token Configuration
You should leave all of the paths default. In the **Scopes** field, add `openid profile email`.
<Warning>
Currently, the only way to obtain your `sub` identifier attribute via Google is through direct API access. For now, set the **Identifier Path** to `email` and in the **Username** field, and use the associated account's email. We highly recommend increasing the resilience of your Google SSO by setting the optional **Name** field to match the account's (full name attached to their Google account).
</Warning>
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.

70
manage/identity-providers/openid-connect.mdx Normal file
View File

@@ -0,0 +1,70 @@
---
title: "OAuth2/OIDC"
description: "Configure OpenID Connect identity provider for external authentication"
---
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.
<CardGroup cols={2}>
<Card title="What it supports" icon="shield">
Any external identity provider that follows the OpenID Connect standard.
</Card>
<Card title="Common providers" icon="users">
Authentik, Keycloak, Okta, and other OIDC-compliant identity providers.
</Card>
</CardGroup>
## Configuration
You will need to configure the following common settings:
<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>

79
manage/identity-providers/pocket-id.mdx Normal file
View File

@@ -0,0 +1,79 @@
---
title: "Pocket ID SSO"
description: "Configure Pocket ID Single Sign-On using OpenID Connect"
---
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">
Set "Callback URLs" to `https://<your-pangolin-domain>/auth/idp/<idp-id>/oidc/callback`.
</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 the **Server Admin** section. Select "Identity Providers" before proceeding with the "Add Identity Provider" button.
**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.

92
manage/identity-providers/zitadel.mdx Normal file
View File

@@ -0,0 +1,92 @@
---
title: "Zitadel SSO"
description: "Configure Zitadel Single Sign-On using OpenID Connect"
---
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.
</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="Note Endpoints">
Open `URLs` and make note of:
- `Authorization Endpoint`
- `Token Endpoint`
</Step>
</Steps>
## Configuring Identity Providers in Pangolin
In Pangolin, go to the **Server Admin** section. Select "Identity Providers" before proceeding with the "Add Identity Provider" button.
**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.