diff --git a/docs.json b/docs.json index a9f772c..212a365 100644 --- a/docs.json +++ b/docs.json @@ -69,6 +69,7 @@ "manage/identity-providers/auto-provisioning", "manage/identity-providers/openid-connect", "manage/identity-providers/google", + "manage/identity-providers/azure", "manage/identity-providers/pocket-id", "manage/identity-providers/zitadel" ] diff --git a/images/auto-provision.png b/images/auto-provision.png new file mode 100644 index 0000000..a00aec4 Binary files /dev/null and b/images/auto-provision.png differ diff --git a/images/create-azure-idp.png b/images/create-azure-idp.png new file mode 100644 index 0000000..142670a Binary files /dev/null and b/images/create-azure-idp.png differ diff --git a/images/create-google-idp.png b/images/create-google-idp.png new file mode 100644 index 0000000..2ca5830 Binary files /dev/null and b/images/create-google-idp.png differ diff --git a/images/create-idp-user.png b/images/create-idp-user.png new file mode 100644 index 0000000..3a33a96 Binary files /dev/null and b/images/create-idp-user.png differ diff --git a/images/create-idp.png b/images/create-idp.png new file mode 100644 index 0000000..7deb06a Binary files /dev/null and b/images/create-idp.png differ diff --git a/images/create-oidc-idp.png b/images/create-oidc-idp.png new file mode 100644 index 0000000..02bdde9 Binary files /dev/null and b/images/create-oidc-idp.png differ diff --git a/manage/identity-providers/add-an-idp.mdx b/manage/identity-providers/add-an-idp.mdx index a3c113f..be0f2b9 100644 --- a/manage/identity-providers/add-an-idp.mdx +++ b/manage/identity-providers/add-an-idp.mdx @@ -1,25 +1,19 @@ --- title: "Add Identity Providers" -description: "Configure external identity providers for user authentication" +description: "Configure external identity providers for user authentication to resources and the organization" --- - -Identity providers are only available in Community Edition Pangolin instances. - +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. -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. +**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 -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. - - - - Allows users to authenticate using external identity providers instead of Pangolin's built-in authentication. - - - - Useful for organizations with existing identity infrastructure like Authentik, Keycloak, or Okta. - - + + + ## Supported Identity Providers @@ -27,16 +21,32 @@ For example, you may have users defined in Authentik, and you want these users t 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** +- Authentik +- Keycloak +- Okta +- Other OIDC-compliant providers + +### Google + + +Google IdP is only available in Pangolin Cloud and Managed Self-hosted. + + +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 + + +Azure Entra ID IdP is only available in Pangolin Cloud and Managed Self-hosted. + + +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 - - Select the "Identity Providers" tab in the Server Admin UI. + + In the Pangolin organization, select the "Identity Providers" section in the sidebar. @@ -44,7 +54,13 @@ This can be used to connect to any external identity provider that supports the - Select the type of identity provider you want to add (OAuth2/OIDC). + Select the type of identity provider you want to add (OAuth2/OIDC, Google, Azure Entra ID). + + + + 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. @@ -52,7 +68,8 @@ This can be used to connect to any external identity provider that supports the +In the Community Edition, identity providers are created and managed via the Server Admin UI rather than the organization settings. + ## 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. - +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. diff --git a/manage/identity-providers/auto-provisioning.mdx b/manage/identity-providers/auto-provisioning.mdx index ec39ee2..30441f0 100644 --- a/manage/identity-providers/auto-provisioning.mdx +++ b/manage/identity-providers/auto-provisioning.mdx @@ -3,62 +3,34 @@ 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. +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. - - - Automatically creates user accounts when users log in through external identity providers. - - - - Streamlines onboarding and keeps user accounts up-to-date with external identity systems. - - - ## 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: - - - - User successfully logs in using an identity provider. - - - - Pangolin creates a user account for the user. - - - - 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. - - - - 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. - - + + + ## 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 +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: @@ -66,7 +38,7 @@ 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 +### Example: Role Selection **Expression:** ``` @@ -94,7 +66,33 @@ contains(groups, 'admin') && 'Admin' || 'Member' This example will return the string "Admin". If the user is not a member of the "admin" group, it will return "Member". -## Selecting Organizations +## Community Edition + +In the Community Edition, identity providers are managed at the server level and not the individual organization. This means you must define policies per organization to map users to specific organizations and roles within those organizations. 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 Evalutated + +It is helpful to think of the auto provisioning process as follows: + + + + User successfully logs in using an identity provider. + + + + Pangolin creates a user account for the user. + + + + 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. + + + + 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. + + + +### 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. @@ -159,9 +157,13 @@ This example will return true since the user is a member of the "home-lab" group } ``` +### 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 3: Dynamic Organization Selection +### Example 1: Dynamic Organization Selection **Expression:** ``` @@ -188,4 +190,3 @@ contains(groups, '{{orgId}}') ``` 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. - diff --git a/manage/identity-providers/azure.mdx b/manage/identity-providers/azure.mdx new file mode 100644 index 0000000..01c10dc --- /dev/null +++ b/manage/identity-providers/azure.mdx @@ -0,0 +1,54 @@ +--- +title: "Azure Entra ID" +description: "Configure Azure Entra ID Single Sign-On" +--- + +The following steps will integrate Microsoft SSO using the built in Azure Entra ID identity provider in Pangolin. + + + +#### 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. + + +We will revisit the **Authorised redirect URIs** field later, as we do not have Pangolin set up for Azure yet. + + + + +## Creating an Azure Entra ID IdP in Pangolin + +In Pangolin, go to "Identity Providers" and click "Add Indentity Provider". Select the Azure Entra ID provider option. + + + + + +In the OAuth2/OIDC Configuration, you'll need the following fields: + + + The application (client) ID from the "Overview" section of your app registration + + + + The client secret value from the "Certificates and secrets" section of your app registration + + +## 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 Google Developers Console + +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 Google SSO. diff --git a/manage/identity-providers/google.mdx b/manage/identity-providers/google.mdx index 30ff842..4044a2a 100644 --- a/manage/identity-providers/google.mdx +++ b/manage/identity-providers/google.mdx @@ -1,65 +1,50 @@ --- -title: "Google SSO" -description: "Configure Google Single Sign-On using OpenID Connect" +title: "Google" +description: "Configure Google Single Sign-On" --- -The following steps will integrate **Google SSO** using **OpenID Connect (OIDC)**. +The following steps will integrate Google SSO using the built in Google identity provider in Pangolin. -## 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**. +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. +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. +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. -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). +Depending on your use case, you may want to use the "Internal" Audience if you are utilising Google Workspace SSO. 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. +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. - - +For "Application type", select `Web application`. Any "Name" can be set. Leave "Authorised JavaScript origins" and "Authorised redirect URIs" empty. -We will revisit the **Authorised redirect URIs** field later, as we do not have Pangolin set up for Google yet. +We will revisit the "Authorised redirect URIs" field later, as we do not have Pangolin set up for Google yet. -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. +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 +## Creating a Google IdP in Pangolin -In Pangolin, go to the **Server Admin** section. Select "Identity Providers" before proceeding with the "Add Identity Provider" button. +In Pangolin, go to "Identity Providers" and click "Add Indentity Provider". Select the Google provider option. -**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: +In the "Google Configuration", you'll need the following fields: The Client ID from your Web application client. @@ -69,24 +54,10 @@ In the OAuth2/OIDC Configuration, you'll need the following fields: The Client secret from your Web application client. - - Set to `https://accounts.google.com/o/oauth2/v2/auth`. - - - - Set to `https://oauth2.googleapis.com/token`. - - ## Token Configuration -You should leave all of the paths default. In the **Scopes** field, add `openid profile email`. - - -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). - - -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**. +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. +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. diff --git a/manage/identity-providers/openid-connect.mdx b/manage/identity-providers/openid-connect.mdx index f37f472..e6dbf77 100644 --- a/manage/identity-providers/openid-connect.mdx +++ b/manage/identity-providers/openid-connect.mdx @@ -5,19 +5,15 @@ description: "Configure OpenID Connect identity provider for external authentica 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. - - - Any external identity provider that follows the OpenID Connect standard. - +## Creating a Generic OAuth2/OIDC IdP in Pangolin - - Authentik, Keycloak, Okta, and other OIDC-compliant identity providers. - - +In Pangolin, go to "Identity Providers" and click "Add Indentity Provider". Select the OAuth2/OIDC provider option. -## Configuration + + + -You will need to configure the following common settings: +In the OAuth2/OIDC Configuration, you'll need the following fields: The client identifier provided by your identity provider. diff --git a/manage/identity-providers/pocket-id.mdx b/manage/identity-providers/pocket-id.mdx index d7e9c5f..1f63924 100644 --- a/manage/identity-providers/pocket-id.mdx +++ b/manage/identity-providers/pocket-id.mdx @@ -1,9 +1,9 @@ --- -title: "Pocket ID SSO" +title: "Pocket ID" description: "Configure Pocket ID Single Sign-On using OpenID Connect" --- -The following steps will integrate **Pocket ID** with **Pangolin SSO** using OpenID Connect (OIDC). +The following steps will integrate Pocket ID with Pangolin SSO using OpenID Connect (OIDC). ## Prerequisites @@ -19,7 +19,7 @@ In Pocket ID, create a new OIDC Client. - Set "Callback URLs" to `https:///auth/idp//oidc/callback`. + Leave blank or set a placeholder. We will come back to this step after creating the IdP and we know the redirect URL. @@ -40,9 +40,9 @@ After you have created the OIDC Client, take note of the following fields from t ## Configuring Identity Providers in Pangolin -In Pangolin, go to the **Server Admin** section. Select "Identity Providers" before proceeding with the "Add Identity Provider" button. +In Pangolin, go to “Identity Providers” and click “Add Indentity 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`. +"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) @@ -66,14 +66,14 @@ In the OAuth2/OIDC Configuration, you'll need the following fields: ## Token Configuration -You should leave all of the paths default. In the **Scopes** field, add `openid profile email`. +You should leave all of the paths default. In the "Scopes" field, add `openid profile email`. -Set the **Identifier Path** to "preferred_username" for Pocket ID integration. +Set the "Identifier Path" to `preferred_username` for Pocket ID integration. -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**. +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. +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. diff --git a/manage/identity-providers/zitadel.mdx b/manage/identity-providers/zitadel.mdx index 631e4ea..a470825 100644 --- a/manage/identity-providers/zitadel.mdx +++ b/manage/identity-providers/zitadel.mdx @@ -1,9 +1,9 @@ --- -title: "Zitadel SSO" +title: "Zitadel" description: "Configure Zitadel Single Sign-On using OpenID Connect" --- -The following steps will integrate **Zitadel** with **Pangolin SSO** using OpenID Connect (OIDC). +The following steps will integrate Zitadel with Pangolin SSO using OpenID Connect (OIDC). ## Prerequisites @@ -31,7 +31,7 @@ You need to configure an application in Zitadel: - Leave `Redirect URIs` blank for now. + Leave `Redirect URIs` blank for now. We'll come back to this once the IdP is created. @@ -53,9 +53,9 @@ When you click create, you'll be shown the `ClientSecret` and `ClientId`. Make s ## Configuring Identity Providers in Pangolin -In Pangolin, go to the **Server Admin** section. Select "Identity Providers" before proceeding with the "Add Identity Provider" button. +In Pangolin, go to “Identity Providers” and click “Add Indentity 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`. +"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) @@ -79,10 +79,10 @@ In the OAuth2/OIDC Configuration, you'll need the following fields: ## Token Configuration -You should leave all of the paths default. In the **Scopes** field, add `openid profile email`. +You should leave all of the paths default. In the "Scopes" field, add `openid profile email`. -Set the **Identifier Path** to "preferred_username" for Zitadel integration. +Set the "Identifier Path" to `preferred_username` for Zitadel integration. 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**.