diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/1_create-provider-athentik.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/1_create-provider-athentik.png
new file mode 100644
index 00000000..621d61e2
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/1_create-provider-athentik.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/2_type-oauth2-athentik.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/2_type-oauth2-athentik.png
new file mode 100644
index 00000000..7f0c2061
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/2_type-oauth2-athentik.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/3_new-provider-auth-flow-athentik.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/3_new-provider-auth-flow-athentik.png
new file mode 100644
index 00000000..3bb186da
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/3_new-provider-auth-flow-athentik.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/4_create-application-athentik.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/4_create-application-athentik.png
new file mode 100644
index 00000000..fd89ea47
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/4_create-application-athentik.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/5_app-name-slug-athentik.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/5_app-name-slug-athentik.png
new file mode 100644
index 00000000..647120c2
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/5_app-name-slug-athentik.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/6_netbird-config-copy-url-athentik.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/6_netbird-config-copy-url-athentik.png
new file mode 100644
index 00000000..89d6bd9b
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/6_netbird-config-copy-url-athentik.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/7_providers-edit-uri.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/7_providers-edit-uri.png
new file mode 100644
index 00000000..678dbaa1
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/7_providers-edit-uri.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/8_add-uri-strict-athentik.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/8_add-uri-strict-athentik.png
new file mode 100644
index 00000000..889f8746
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/8_add-uri-strict-athentik.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/01_create-realm-keycloak.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/01_create-realm-keycloak.png
new file mode 100644
index 00000000..7ecbf532
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/01_create-realm-keycloak.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/02_realm-name-keycloak.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/02_realm-name-keycloak.png
new file mode 100644
index 00000000..d4202d50
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/02_realm-name-keycloak.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/03_create-user-keycloak.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/03_create-user-keycloak.png
new file mode 100644
index 00000000..c92fa354
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/03_create-user-keycloak.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/04_user-password-keycloak.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/04_user-password-keycloak.png
new file mode 100644
index 00000000..b92245c1
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/04_user-password-keycloak.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/05_create-client-keycloak.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/05_create-client-keycloak.png
new file mode 100644
index 00000000..cbfbfe14
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/05_create-client-keycloak.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/06_openid-clientid-keycloak.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/06_openid-clientid-keycloak.png
new file mode 100644
index 00000000..ad91d3fc
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/06_openid-clientid-keycloak.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/07_client-auth-on-keycloak.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/07_client-auth-on-keycloak.png
new file mode 100644
index 00000000..7c605397
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/07_client-auth-on-keycloak.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/08_copy-redirect-url-keycloak.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/08_copy-redirect-url-keycloak.png
new file mode 100644
index 00000000..e5ca7ee0
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/08_copy-redirect-url-keycloak.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/09_copy-client-secret-keycloak.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/09_copy-client-secret-keycloak.png
new file mode 100644
index 00000000..305ac75d
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/09_copy-client-secret-keycloak.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/10_netbird-config-keycloak.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/10_netbird-config-keycloak.png
new file mode 100644
index 00000000..2175d88b
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/10_netbird-config-keycloak.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/11_netbird-keycloak-login.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/11_netbird-keycloak-login.png
new file mode 100644
index 00000000..389f3aab
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/11_netbird-keycloak-login.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/1_add-oidc-client-pocketid.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/1_add-oidc-client-pocketid.png
new file mode 100644
index 00000000..831bb341
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/1_add-oidc-client-pocketid.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/2_save-oidc-client-pocketid.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/2_save-oidc-client-pocketid.png
new file mode 100644
index 00000000..55bce12c
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/2_save-oidc-client-pocketid.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/3_note-client-id-pocketid.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/3_note-client-id-pocketid.png
new file mode 100644
index 00000000..36ed27b5
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/3_note-client-id-pocketid.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/4_netbird-config-pocketid.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/4_netbird-config-pocketid.png
new file mode 100644
index 00000000..5a14ebd1
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/4_netbird-config-pocketid.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/5_copy-redirect-netbird-pocketid.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/5_copy-redirect-netbird-pocketid.png
new file mode 100644
index 00000000..3f9d3423
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/5_copy-redirect-netbird-pocketid.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/6_add-callback-url-pocketid.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/6_add-callback-url-pocketid.png
new file mode 100644
index 00000000..bcd5e153
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/6_add-callback-url-pocketid.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/7_add-user-group-pocketid.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/7_add-user-group-pocketid.png
new file mode 100644
index 00000000..5e641a1d
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/7_add-user-group-pocketid.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/8_add-group-to-user-pocketid.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/8_add-group-to-user-pocketid.png
new file mode 100644
index 00000000..32c1e2ae
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/8_add-group-to-user-pocketid.png differ
diff --git a/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/9_add-group-to-oidc-pocketid.png b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/9_add-group-to-oidc-pocketid.png
new file mode 100644
index 00000000..cd7d1588
Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/9_add-group-to-oidc-pocketid.png differ
diff --git a/src/pages/selfhosted/identity-providers/advanced/authentik.mdx b/src/pages/selfhosted/identity-providers/advanced/authentik.mdx
new file mode 100644
index 00000000..058bfe1d
--- /dev/null
+++ b/src/pages/selfhosted/identity-providers/advanced/authentik.mdx
@@ -0,0 +1,181 @@
+import {Note} from "@/components/mdx";
+
+# Authentik SSO with NetBird Self-Hosted (Advanced)
+
+[Authentik](https://goauthentik.io) is an open-source identity provider focused on flexibility and security. It serves as a self-hosted alternative to commercial solutions like Okta and Auth0, providing single sign-on (SSO), multi-factor authentication (MFA), access policies, user management, and support for SAML and OIDC protocols.
+
+## Standalone Setup (Advanced)
+
+
+NetBird includes built-in [local user management](/selfhosted/identity-providers/local) powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add **multiple external identity providers** alongside local users, giving users multiple login options.
+
+We highly recommend using the simpler setup that adds Authentik as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the [Management Setup (Recommended)](/selfhosted/identity-providers/authentik#management-setup-recommended) section in the main Authentik documentation.
+
+The standalone setup below replaces your embedded IdP entirely and is only recommended for experienced Authentik administrators who need full control over authentication and user management.
+
+
+Use Authentik as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced Authentik administrators as it also requires additional setup and ongoing maintenance.
+
+For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Management Setup (Recommended)](#management-setup-recommended) section above.
+
+
+If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like [Auth0](/selfhosted/identity-providers/managed/auth0).
+
+
+### Prerequisites
+
+- Authentik instance running with SSL
+- Docker and Docker Compose installed for NetBird
+
+### Step 1: Create OAuth2/OpenID Provider in Authentik
+
+1. Navigate to Authentik admin interface
+2. Click **Applications** on the left menu, then click **Providers**
+3. Click **Create** to create a new provider
+4. Select **OAuth2/OpenID Provider** and click **Next**
+
+
+
+
+
+5. Fill in the form with the following values:
+ - **Name**: `NetBird`
+ - **Authorization Flow**: `default-provider-authorization-explicit-consent (Authorize Application)`
+ - **Client type**: `Public`
+ - **Redirect URIs/Origins (RegEx)**:
+ - Regex: `https:///.*`
+ - Strict: `http://localhost:53000`
+ - **Advanced protocol settings**:
+ - Access code validity: `minutes=10`
+ - Subject mode: `Based on the User's ID`
+ - **Signing Key**: Select any cert present, e.g., `authentik Self-signed Certificate`
+
+
+
+
+
+6. Click **Finish**
+7. Note the **Client ID** for later use
+
+### Step 2: Create Application in Authentik
+
+1. Click **Applications** on the left menu, then click **Applications**
+2. Click **Create** to create a new application
+3. Fill in the form:
+ - **Name**: `NetBird`
+ - **Slug**: `netbird`
+ - **Provider**: Select the `NetBird` provider you created
+4. Click **Create**
+
+
+
+
+
+### Step 3: Create Service Account
+
+1. Navigate to Authentik admin interface
+2. Click **Directory** on the left menu, then click **Users**
+3. Click **Create Service Account**
+4. Fill in the form:
+ - **Username**: `Netbird`
+ - **Create Group**: Disable
+5. Click **Create**
+
+
+
+
+
+6. Note the service account username
+7. Create an app password: Go to **Directory** → **Tokens and App passwords**
+8. Create a new app password, selecting the NetBird service account as the **User**
+9. Save the app password for later use
+
+### Step 4: Add Service Account to Admin Group
+
+1. Click **Directory** on the left menu, then click **Groups**
+2. Click **authentik Admins** from the list and select **Users** tab
+3. Click **Add existing user** and click **+** button
+4. Select **Netbird** and click **Add**
+5. Disable **Hide service-accounts** and verify the user is added
+
+
+
+
+
+### Step 5: Create Device Code Flow
+
+1. Click **Flows and Stages** on the left menu, then click **Flows** → **Create**
+2. Fill in the form:
+ - **Name**: `default-device-code-flow`
+ - **Title**: `Device Code Flow`
+ - **Designation**: `Stage Configuration`
+ - **Authentication**: `Require authentication`
+3. Click **Create**
+
+
+
+
+
+4. Click **System** on the left menu, then click **Brands**
+5. Click edit on **authentik-default**
+6. Under **Default flows**, set **Device code flow** to `default-device-code-flow`
+7. Click **Update**
+
+
+
+
+
+### Step 6: Configure NetBird
+
+Your authority OIDC configuration will be available at:
+
+```bash
+https:///application/o/netbird/.well-known/openid-configuration
+```
+
+
+Double-check if the endpoint returns a JSON response by calling it from your browser.
+
+
+Set properties in the `setup.env` file:
+
+```shell
+NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///application/o/netbird/.well-known/openid-configuration"
+NETBIRD_USE_AUTH0=false
+NETBIRD_AUTH_CLIENT_ID=""
+NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
+NETBIRD_AUTH_AUDIENCE=""
+NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
+NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE=""
+NETBIRD_AUTH_REDIRECT_URI="/auth"
+NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
+
+NETBIRD_MGMT_IDP="authentik"
+NETBIRD_IDP_MGMT_CLIENT_ID=""
+NETBIRD_IDP_MGMT_EXTRA_USERNAME="Netbird"
+NETBIRD_IDP_MGMT_EXTRA_PASSWORD=""
+
+# Needs disabling due to issue with IdP. Learn more: https://github.com/netbirdio/netbird/issues/3654
+NETBIRD_AUTH_PKCE_DISABLE_PROMPT_LOGIN=true
+```
+
+### Step 7: Continue with NetBird Setup
+
+You've configured all required resources in Authentik. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
+
+---
+
+## Troubleshooting
+
+### Service account authentication fails
+
+- Ensure you're using the app password, not the account password
+- Verify the service account is in the authentik Admins group
+
+---
+
+## Related Resources
+
+- [Authentik Documentation](https://goauthentik.io/docs/)
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
+
diff --git a/src/pages/selfhosted/identity-providers/advanced/keycloak.mdx b/src/pages/selfhosted/identity-providers/advanced/keycloak.mdx
new file mode 100644
index 00000000..f53935e8
--- /dev/null
+++ b/src/pages/selfhosted/identity-providers/advanced/keycloak.mdx
@@ -0,0 +1,260 @@
+import {Note} from "@/components/mdx";
+
+# Keycloak SSO with NetBird Self-Hosted (Advanced)
+
+[Keycloak](https://www.keycloak.org/) is an open-source Identity and Access Management solution maintained by Red Hat. It provides single sign-on, social login, user federation, fine-grained authorization, and supports OpenID Connect, OAuth 2.0, and SAML 2.0 protocols.
+
+## Standalone Setup (Advanced)
+
+
+NetBird includes built-in [local user management](/selfhosted/identity-providers/local) powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add **multiple external identity providers** alongside local users, giving users multiple login options.
+
+We highly recommend using the simpler setup that adds Keycloak as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the [Management Setup (Recommended)](/selfhosted/identity-providers/keycloak#management-setup-recommended) section in the main Keycloak documentation.
+
+The standalone setup below replaces your embedded IdP entirely and is only recommended for experienced Keycloak administrators who need full control over authentication and user management.
+
+
+Use Keycloak as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced Keycloak administrators as it also requires additional setup and ongoing maintenance.
+
+For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Management Setup (Recommended)](#management-setup-recommended) section above.
+
+
+If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like [Auth0](/selfhosted/identity-providers/managed/auth0).
+
+
+### Expected Result
+
+After completing this guide, you can log in to your self-hosted NetBird Dashboard and add machines to your network using the [Interactive SSO Login feature](/get-started/install#running-net-bird-with-sso-login) over Keycloak.
+
+
+
+
+
+### Prerequisites
+
+- Keycloak instance running with SSL
+- Docker and Docker Compose for NetBird
+
+### Step 1: Check Your Keycloak Instance
+
+Ensure your Keycloak instance is available at `https://YOUR-KEYCLOAK-HOST-AND-PORT` with SSL enabled.
+
+### Step 2: Create a Realm
+
+1. Open the Keycloak Admin Console
+2. Hover over the dropdown in the top-left corner where it says `Master`
+3. Click **Create Realm**
+4. Fill in:
+ - **Realm name**: `netbird`
+5. Click **Create**
+
+
+
+
+
+### Step 3: Create a User
+
+1. Make sure the selected realm is `netbird`
+2. Click **Users** (left-hand menu)
+3. Click **Create new user**
+4. Fill in:
+ - **Username**: `netbird`
+5. Click **Create**
+
+
+
+
+
+6. Click **Credentials** tab
+7. Click **Set password**
+8. Fill in the password and set **Temporary** to `Off`
+9. Click **Save**
+
+
+
+5. Click **Save**
+6. Go to **Credentials** tab
+7. Copy the **Client secret**
+
+
+
+
+
+### Step 9: Add View-Users Role
+
+1. Go to **Clients** → **netbird-backend**
+2. Switch to **Service accounts roles** tab
+3. Click **Assign roles**
+4. Select **Filter by clients** and search for `view-users`
+
+
+
+
+
+5. Check the role checkbox and click **Assign**
+
+
+
+
+
+
+**Optional**: To enable automatic user deletion from Keycloak when deleted from NetBird, add the `--user-delete-from-idp` flag to the management startup command and assign the `manage-users` role instead.
+
+
+### Step 10: Configure NetBird
+
+Your authority OIDC configuration will be available at:
+
+```bash
+https:///realms/netbird/.well-known/openid-configuration
+```
+
+
+Double-check if the endpoint returns a JSON response by calling it from your browser.
+
+
+Set properties in the `setup.env` file:
+
+```shell
+NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///realms/netbird/.well-known/openid-configuration"
+NETBIRD_USE_AUTH0=false
+NETBIRD_AUTH_CLIENT_ID="netbird-client"
+NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
+NETBIRD_AUTH_AUDIENCE="netbird-client"
+
+NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="netbird-client"
+NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="netbird-client"
+
+NETBIRD_MGMT_IDP="keycloak"
+NETBIRD_IDP_MGMT_CLIENT_ID="netbird-backend"
+NETBIRD_IDP_MGMT_CLIENT_SECRET=""
+NETBIRD_IDP_MGMT_EXTRA_ADMIN_ENDPOINT="https:///admin/realms/netbird"
+```
+
+
+Make sure your Keycloak instance uses HTTPS. Otherwise, the setup won't work.
+
+
+### Step 11: Continue with NetBird Setup
+
+You've configured all required resources in Keycloak. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
+
+---
+
+## Troubleshooting
+
+### "Invalid token" errors
+
+- Verify the issuer URL includes `/realms/your-realm`
+- Ensure the client ID matches in both Keycloak and NetBird
+- Check clock synchronization between servers
+
+### Users not appearing in NetBird
+
+- Verify the backend client has `view-users` role
+
+---
+
+## Related Resources
+
+- [Keycloak Documentation](https://www.keycloak.org/documentation)
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
+
diff --git a/src/pages/selfhosted/identity-providers/advanced/pocketid.mdx b/src/pages/selfhosted/identity-providers/advanced/pocketid.mdx
new file mode 100644
index 00000000..a47e6f6a
--- /dev/null
+++ b/src/pages/selfhosted/identity-providers/advanced/pocketid.mdx
@@ -0,0 +1,128 @@
+import {Note} from "@/components/mdx";
+
+# PocketID SSO with NetBird Self-Hosted (Advanced)
+
+[PocketID](https://pocket-id.org/) is a simplified identity management solution designed for self-hosted environments, offering a lightweight and easy-to-deploy option for authentication.
+
+
+PocketID is secure and effective but makes some tradeoffs in terms of features. Notably, it does not allow scoping the access of API Tokens. Keep careful track of the token used by NetBird for management.
+
+
+## Standalone Setup (Advanced)
+
+
+NetBird includes built-in [local user management](/selfhosted/identity-providers/local) powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add **multiple external identity providers** alongside local users, giving users multiple login options.
+
+We highly recommend using the simpler setup that adds PocketID as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the [Management Setup (Recommended)](/selfhosted/identity-providers/pocketid#management-setup-recommended) section in the main PocketID documentation.
+
+The standalone setup below replaces your embedded IdP entirely and is only recommended for experienced PocketID administrators who need full control over authentication and user management.
+
+
+Use PocketID as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced PocketID administrators as it also requires additional setup and ongoing maintenance.
+
+For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Management Setup (Recommended)](#management-setup-recommended) section above.
+
+### Prerequisites
+
+- PocketID instance running with SSL
+- Docker and Docker Compose for NetBird
+
+### Step 1: Create and Configure PocketID Application
+
+1. Navigate to PocketID console
+2. Click the **Administration** dropdown, then select **OIDC Clients**
+3. Fill in the form:
+ - **Name**: `NetBird`
+ - **Client Launch URL**: `https://`
+ - **Callback URLs**:
+ - `http://localhost:53000`
+ - `https:///auth`
+ - `https:///silent-auth`
+ - **Logout Callback URL**: `https:///`
+ - **Public Client**: On
+ - **PKCE**: On
+4. Click **Save**
+
+
+
+
+
+5. Copy **Client ID** for later use
+
+### Step 2: Create API Token
+
+1. Click **Administration** dropdown, then select **API Keys**
+2. Click **Add API Key**
+3. Fill in:
+ - **Name**: `NetBird Management Token`
+ - **Expires At**: Pick a date in the future
+ - **Description**: `NetBird Management Token`
+4. Click **Save**
+
+
+
+
+
+5. Copy **API Key** for later use
+
+### Step 3: Configure NetBird
+
+Your authority OIDC configuration will be available at:
+
+```bash
+https:///.well-known/openid-configuration
+```
+
+
+Double-check if the endpoint returns a JSON response by calling it from your browser.
+
+
+Set properties in the `setup.env` file:
+
+```shell
+NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///.well-known/openid-configuration"
+NETBIRD_USE_AUTH0=false
+NETBIRD_AUTH_CLIENT_ID=""
+NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email groups"
+NETBIRD_AUTH_AUDIENCE=""
+NETBIRD_AUTH_REDIRECT_URI="/auth"
+NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
+NETBIRD_TOKEN_SOURCE="idToken"
+
+NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"
+NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
+NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE=""
+NETBIRD_AUTH_DEVICE_AUTH_SCOPE="openid profile email groups"
+NETBIRD_AUTH_DEVICE_AUTH_USE_ID_TOKEN=true
+
+NETBIRD_MGMT_IDP="pocketid"
+NETBIRD_IDP_MGMT_CLIENT_ID="netbird"
+NETBIRD_IDP_MGMT_EXTRA_MANAGEMENT_ENDPOINT="https://"
+NETBIRD_IDP_MGMT_EXTRA_API_TOKEN=""
+```
+
+### Step 4: Continue with NetBird Setup
+
+You've configured all required resources in PocketID. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
+
+---
+
+## Troubleshooting
+
+### API token not working
+
+- Verify the token hasn't expired
+- Ensure the token was created by an admin user
+
+### Device authorization not available
+
+- PocketID has limited device auth support
+- Set `NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"` if issues persist
+
+---
+
+## Related Resources
+
+- [PocketID Documentation](https://pocket-id.org/docs)
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
+
diff --git a/src/pages/selfhosted/identity-providers/advanced/zitadel.mdx b/src/pages/selfhosted/identity-providers/advanced/zitadel.mdx
new file mode 100644
index 00000000..fd56f039
--- /dev/null
+++ b/src/pages/selfhosted/identity-providers/advanced/zitadel.mdx
@@ -0,0 +1,232 @@
+import {Note} from "@/components/mdx";
+
+# Zitadel SSO with NetBird Self-Hosted (Advanced)
+
+[Zitadel](https://zitadel.com) is an open-source identity infrastructure platform designed for cloud-native environments. It provides multi-tenancy, customizable branding, passwordless authentication, and supports protocols like OpenID Connect, OAuth2, SAML2, and LDAP.
+
+
+Zitadel was previously used in the NetBird quickstart script. If you have an existing Zitadel deployment, you can continue using it as a standalone IdP or migrate to the embedded IdP with Zitadel as an external IdP directly in the NetBird Management Dashboard.
+
+
+## Standalone Setup (Advanced)
+
+
+NetBird includes built-in [local user management](/selfhosted/identity-providers/local) powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add **multiple external identity providers** alongside local users, giving users multiple login options.
+
+We highly recommend using the simpler setup that adds Zitadel as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the [Management Setup (Recommended)](/selfhosted/identity-providers/zitadel#management-setup-recommended) section in the main Zitadel documentation.
+
+The standalone setup below replaces your embedded IdP entirely and is only recommended for experienced Zitadel administrators who need full control over authentication and user management.
+
+
+Use Zitadel as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced Zitadel administrators as it also requires additional setup and ongoing maintenance.
+
+For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Management Setup (Recommended)](#management-setup-recommended) section above.
+
+
+If you prefer not to self-host, Zitadel offers a managed cloud option at [zitadel.com](https://zitadel.com/).
+
+
+### Prerequisites
+
+- Zitadel instance (cloud or self-hosted) with SSL
+- Docker and Docker Compose for NetBird
+
+### Step 1: Create and Configure Zitadel Application
+
+1. Navigate to Zitadel console
+2. Click **Projects** at the top menu, then click **Create New Project**
+3. Fill in:
+ - **Name**: `NETBIRD`
+
+
+
+
+
+4. Click **Projects** and select **NETBIRD** project
+5. Click **New** in **Applications** section
+6. Fill in:
+ - **Name**: `netbird`
+ - **Type of Application**: `User Agent`
+
+
+
+9. Click **Create** and then **Close**
+10. Under **Grant Types**, select `Authorization Code`, `Device Code`, and `Refresh Token`
+11. Click **Save**
+
+
+
+
+
+12. Copy **Client ID** for later use
+
+### Step 2: Configure Token Settings
+
+1. Select the **netbird** application
+2. Click **Token Settings** in the left menu
+3. Configure:
+ - **Auth Token Type**: `JWT`
+ - Check **Add user roles to the access token**
+4. Click **Save**
+
+
+
+
+
+### Step 3: Configure Redirect Settings (Development Only)
+
+
+This step is only for development mode without SSL.
+
+
+1. Click **Redirect Settings** in the left menu
+2. Toggle **Development Mode**
+3. Click **Save**
+
+
+
+
+
+### Step 4: Create Service User
+
+1. Click **Users** in the top menu
+2. Select **Service Users** tab
+3. Click **New**
+4. Fill in:
+ - **User Name**: `netbird`
+ - **Name**: `netbird`
+ - **Description**: `Netbird Service User`
+ - **Access Token Type**: `JWT`
+5. Click **Create**
+
+
+
+
+
+6. Click **Actions** in the top right corner
+7. Click **Generate Client Secret**
+8. Copy **ClientSecret** for later use
+
+
+
+
+
+### Step 5: Grant User Manager Role
+
+1. Click **Organization** in the top menu
+2. Click **+** in the top right corner
+3. Search for `netbird` service user
+4. Check **Org User Manager** checkbox
+5. Click **Add**
+
+
+
+
+
+### Step 6: Configure NetBird
+
+Your authority OIDC configuration will be available at:
+
+```bash
+https:///.well-known/openid-configuration
+```
+
+
+Double-check if the endpoint returns a JSON response by calling it from your browser.
+
+
+Set properties in the `setup.env` file:
+
+```shell
+NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///.well-known/openid-configuration"
+NETBIRD_USE_AUTH0=false
+NETBIRD_AUTH_CLIENT_ID=""
+NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
+NETBIRD_AUTH_AUDIENCE=""
+NETBIRD_AUTH_REDIRECT_URI="/auth"
+NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
+
+NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="hosted"
+NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
+NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE=""
+
+NETBIRD_MGMT_IDP="zitadel"
+NETBIRD_IDP_MGMT_CLIENT_ID="netbird"
+NETBIRD_IDP_MGMT_CLIENT_SECRET=""
+NETBIRD_IDP_MGMT_EXTRA_MANAGEMENT_ENDPOINT="https:///management/v1"
+NETBIRD_MGMT_IDP_SIGNKEY_REFRESH=true
+```
+
+### Step 7: Continue with NetBird Setup
+
+You've configured all required resources in Zitadel. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
+
+---
+
+## Migrating from Zitadel Quickstart
+
+If you deployed NetBird using the previous quickstart script with Zitadel:
+
+**Option A - Keep using Zitadel standalone**: Continue with your existing setup. No changes needed.
+
+**Option B - Add Zitadel as external IdP directly in NetBird Management Dashboard**:
+1. Deploy new NetBird version with embedded IdP
+2. Add your existing Zitadel as an external IdP directly in the NetBird Management Dashboard (follow Management Setup above)
+3. Users can continue logging in with Zitadel
+4. Optionally create local user accounts as fallback
+
+**Option C - Migrate fully to embedded IdP**:
+1. Export user list from Zitadel
+2. Deploy new NetBird version with embedded IdP
+3. Recreate users in NetBird Dashboard
+4. Decommission Zitadel when ready
+
+---
+
+## Troubleshooting
+
+### "Token validation failed" error
+
+- Verify the issuer URL is correct
+- Ensure **User Info inside ID Token** is enabled
+- Check that the audience matches your client ID
+
+### Service user authentication fails
+
+- Verify the client secret was copied correctly
+- Ensure the service user has **Org User Manager** role
+
+### Device auth not working
+
+- Ensure **Device Code** grant type is enabled
+- Verify PKCE is configured for the application
+
+---
+
+## Related Resources
+
+- [Zitadel Documentation](https://zitadel.com/docs)
+- [Zitadel GitHub](https://github.com/zitadel/zitadel)
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
+- [Migration Guide](/selfhosted/identity-providers#migration-guide)
+
diff --git a/src/pages/selfhosted/identity-providers/authentik.mdx b/src/pages/selfhosted/identity-providers/authentik.mdx
index 7b6220c3..efc1d7c8 100644
--- a/src/pages/selfhosted/identity-providers/authentik.mdx
+++ b/src/pages/selfhosted/identity-providers/authentik.mdx
@@ -18,40 +18,54 @@ Add Authentik as an external IdP directly in the NetBird Management Dashboard. T
1. Navigate to Authentik admin interface
2. Click **Applications** on the left menu, then click **Providers**
3. Click **Create** to create a new provider
+
+
+
+
+
4. Select **OAuth2/OpenID Provider** and click **Next**
-
+
5. Fill in the form with the following values:
- **Name**: `NetBird`
- - **Authentication Flow**: `default-authentication-flow (Welcome to authentik!)`
- **Authorization Flow**: `default-provider-authorization-explicit-consent (Authorize Application)`
- **Client type**: `Confidential`
- - **Redirect URIs/Origins**: Leave empty for now (you'll add this after adding the identity provider in NetBird)
+ - **Redirect URIs/Origins**: Leave empty for now (you'll add this in Step 5)
- **Signing Key**: Select any cert present, e.g., `authentik Self-signed Certificate`
+
+
+
+
6. Click **Finish**
-7. Note the **Client ID** and **Client Secret**
+7. Note the **Client ID** and **Client Secret** — you'll need these for Step 3
### Step 2: Create Application in Authentik
1. Click **Applications** on the left menu, then click **Applications**
2. Click **Create** to create a new application
+
+
+
+
+
3. Fill in the form:
- **Name**: `NetBird`
- **Slug**: `netbird`
- - **Provider**: Select the `NetBird` provider you created
-4. Click **Create**
+ - **Provider**: Select the `NetBird` provider you created in Step 1
-
+
-### Step 3: Add Identity Provider in NetBird
+4. Click **Create**
-1. Log in to your NetBird Dashboard
+### Step 3: Get Redirect URL from NetBird
+
+1. Open a new tab or window and log in to your NetBird Dashboard
2. Navigate to **Settings** → **Identity Providers**
3. Click **Add Identity Provider**
4. Fill in the fields:
@@ -60,22 +74,40 @@ Add Authentik as an external IdP directly in the NetBird Management Dashboard. T
|-------|-------|
| Type | Generic OIDC |
| Name | Authentik (or your preferred display name) |
-| Client ID | From Authentik provider |
-| Client Secret | From Authentik provider |
+| Client ID | From Authentik provider (from Step 1) |
+| Client Secret | From Authentik provider (from Step 1) |
| Issuer | `https://authentik.example.com/application/o/netbird/` |
-5. Click **Save**
+5. **Copy the Redirect URL** that NetBird displays (but don't click **Add Provider** yet)
-### Step 4: Configure Redirect URI
+
+
+
-After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Authentik provider:
+### Step 4: Configure Redirect URI in Authentik
1. Return to Authentik admin → **Providers** → **NetBird**
2. Click **Edit**
-3. Under **Redirect URIs/Origins**, add the redirect URL from NetBird
-4. Click **Update**
-### Step 5: Test the Connection
+
+
+
+
+3. Under **Redirect URIs/Origins**, add the redirect URL you copied from NetBird
+4. Select **Strict** (not Regex) to match the exact URL from NetBird
+
+
+
+
+
+5. Click **Update**
+
+### Step 5: Complete NetBird Setup
+
+1. Return to the NetBird tab
+2. Click **Add Provider**
+
+### Step 6: Test the Connection
1. Log out of NetBird Dashboard
2. On the login page, you should see an "Authentik" button
@@ -90,129 +122,12 @@ Use Authentik as your primary identity provider instead of NetBird's embedded Id
For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Management Setup (Recommended)](#management-setup-recommended) section above.
+For detailed instructions on the standalone setup, see the [Authentik SSO with NetBird Self-Hosted (Advanced)](/selfhosted/identity-providers/advanced/authentik) documentation.
+
If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like [Auth0](/selfhosted/identity-providers/managed/auth0).
-### Prerequisites
-
-- Authentik instance running with SSL
-- Docker and Docker Compose installed for NetBird
-
-### Step 1: Create OAuth2/OpenID Provider
-
-Follow steps 1-2 from the Management Setup above, but configure the provider as follows:
-
-- **Client type**: `Public`
-- **Redirect URIs/Origins (RegEx)**:
- - Regex: `https:///.*`
- - Strict: `http://localhost:53000`
-- **Advanced protocol settings**:
- - Access code validity: `minutes=10`
- - Subject mode: `Based on the User's ID`
-
-
-
-
-
-Take note of **Client ID** for later use.
-
-### Step 2: Create Application
-
-Follow step 2 from the Management Setup to create the NetBird application.
-
-### Step 3: Create Service Account
-
-1. Navigate to Authentik admin interface
-2. Click **Directory** on the left menu, then click **Users**
-3. Click **Create Service Account**
-4. Fill in the form:
- - **Username**: `Netbird`
- - **Create Group**: Disable
-5. Click **Create**
-
-
-
-
-
-6. Note the service account username
-7. Create an app password: Go to **Directory** → **Tokens and App passwords**
-8. Create a new app password, selecting the NetBird service account as the **User**
-9. Save the app password for later use
-
-### Step 4: Add Service Account to Admin Group
-
-1. Click **Directory** on the left menu, then click **Groups**
-2. Click **authentik Admins** from the list and select **Users** tab
-3. Click **Add existing user** and click **+** button
-4. Select **Netbird** and click **Add**
-5. Disable **Hide service-accounts** and verify the user is added
-
-
-
-
-
-### Step 5: Create Device Code Flow
-
-1. Click **Flows and Stages** on the left menu, then click **Flows** → **Create**
-2. Fill in the form:
- - **Name**: `default-device-code-flow`
- - **Title**: `Device Code Flow`
- - **Designation**: `Stage Configuration`
- - **Authentication**: `Require authentication`
-3. Click **Create**
-
-
-
-
-
-4. Click **System** on the left menu, then click **Brands**
-5. Click edit on **authentik-default**
-6. Under **Default flows**, set **Device code flow** to `default-device-code-flow`
-7. Click **Update**
-
-
-
-
-
-### Step 6: Configure NetBird
-
-Your authority OIDC configuration will be available at:
-
-```bash
-https:///application/o/netbird/.well-known/openid-configuration
-```
-
-
-Double-check if the endpoint returns a JSON response by calling it from your browser.
-
-
-Set properties in the `setup.env` file:
-
-```shell
-NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///application/o/netbird/.well-known/openid-configuration"
-NETBIRD_USE_AUTH0=false
-NETBIRD_AUTH_CLIENT_ID=""
-NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
-NETBIRD_AUTH_AUDIENCE=""
-NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
-NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE=""
-NETBIRD_AUTH_REDIRECT_URI="/auth"
-NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
-
-NETBIRD_MGMT_IDP="authentik"
-NETBIRD_IDP_MGMT_CLIENT_ID=""
-NETBIRD_IDP_MGMT_EXTRA_USERNAME="Netbird"
-NETBIRD_IDP_MGMT_EXTRA_PASSWORD=""
-
-# Needs disabling due to issue with IdP. Learn more: https://github.com/netbirdio/netbird/issues/3654
-NETBIRD_AUTH_PKCE_DISABLE_PROMPT_LOGIN=true
-```
-
-### Step 7: Continue with NetBird Setup
-
-You've configured all required resources in Authentik. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
-
---
## Troubleshooting
@@ -220,19 +135,13 @@ You've configured all required resources in Authentik. Continue with the [NetBir
### "Invalid redirect URI" error
- Ensure the redirect URI exactly matches what NetBird provides
-- For Management Setup: Copy the exact URL from the success modal
-- For standalone: Use regex pattern `https:///.*`
+- Copy the exact URL from the success modal
### Authentication fails silently
- Verify a signing key is selected in the provider configuration
- Check that the application is linked to the correct provider
-### Service account authentication fails
-
-- Ensure you're using the app password, not the account password
-- Verify the service account is in the authentik Admins group
-
---
## Related Resources
diff --git a/src/pages/selfhosted/identity-providers/keycloak.mdx b/src/pages/selfhosted/identity-providers/keycloak.mdx
index d054d324..88d4dd95 100644
--- a/src/pages/selfhosted/identity-providers/keycloak.mdx
+++ b/src/pages/selfhosted/identity-providers/keycloak.mdx
@@ -13,56 +13,131 @@ Add Keycloak as an external IdP directly in the NetBird Management Dashboard. Th
- NetBird self-hosted with embedded IdP enabled
- Keycloak instance running with SSL
-### Step 1: Create Client in Keycloak
+### Step 1: Create Realm in Keycloak
1. Open the Keycloak Admin Console
-2. Select your realm (or create a new one, e.g., `netbird`)
-3. Click **Clients** → **Create client**
-4. Fill in the form:
+2. Hover over the realm dropdown in the top-left corner (where it shows `Master` or your current realm)
+3. Click **Create Realm**
+
+
+
+
+
+4. Fill in:
+ - **Realm name**: `netbird`
+
+
+
+
+
+5. Click **Create**
+6. Verify that `netbird` is now selected in the realm dropdown
+
+### Step 2: Create User in Keycloak
+
+1. Make sure the `netbird` realm is selected
+2. Click **Users** (left-hand menu)
+3. Click **Create new user**
+
+
+
+
+
+4. Fill in:
+ - **Username**: `netbird` (or your preferred username)
+ - **Email**: Your email address
+5. Click **Create**
+6. Click the **Credentials** tab
+7. Click **Set password**
+8. Fill in the password and set **Temporary** to `Off`
+9. Click **Save**
+
+
+
+2. Fill in the form:
- **Client type**: `OpenID Connect`
- **Client ID**: `netbird`
-5. Click **Next**
-6. On Capability config:
+
+
+
+
+
+3. Click **Next**
+4. On Capability config:
- Enable **Client authentication**
-7. Click **Next**
-8. On Login settings:
- - Leave redirect URIs empty for now
-9. Click **Save**
-10. Go to the **Credentials** tab and copy the **Client secret**
-### Step 2: Add Identity Provider in NetBird
+
+
+
-1. Log in to your NetBird Dashboard
+5. Click **Next**
+6. On Login settings page, **don't click Save yet** — you'll add the redirect URI in Step 4
+
+### Step 4: Get Redirect URL from NetBird
+
+1. Open a new tab or window and log in to your NetBird Dashboard
2. Navigate to **Settings** → **Identity Providers**
3. Click **Add Identity Provider**
-4. Fill in the fields:
+4. Select **Keycloak** (or choose **Generic OIDC** if Keycloak is not listed)
+5. Fill in the fields (you can leave **Client Secret** empty for now):
| Field | Value |
|-------|-------|
-| Type | Generic OIDC |
+| Type | Generic OIDC (if not already selected) |
| Name | Keycloak (or your preferred display name) |
-| Client ID | `netbird` (from Step 1) |
-| Client Secret | From Keycloak Credentials tab |
-| Issuer | `https://keycloak.example.com/realms/your-realm` |
+| Client ID | `netbird` (from Step 3) |
+| Client Secret | Leave empty for now |
+| Issuer | `https://keycloak.example.com/realms/netbird` |
-5. Click **Save**
+6. NetBird will display a **Redirect URL** — **copy this URL** (but don't click **Add Provider** yet)
-### Step 3: Configure Redirect URI
+
+
+
-After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Keycloak client:
+### Step 5: Complete Client Configuration in Keycloak
-1. Return to Keycloak Admin Console
-2. Go to your client → **Settings** tab
-3. Under **Valid redirect URIs**, add the redirect URL from NetBird
-4. Click **Save**
+1. Return to the Keycloak Admin Console tab
+2. On the Login settings page:
+ - Under **Valid redirect URIs**, paste the redirect URL you copied from NetBird
+3. Click **Save**
+4. Go to the **Credentials** tab and copy the **Client secret** — you'll need this for Step 6
-### Step 4: Test the Connection
+
+
+
+
+### Step 6: Complete NetBird Setup
+
+1. Return to the NetBird tab
+2. In the identity provider form, paste the **Client secret** you copied from Step 5
+3. Click **Add Provider**
+
+
+
+
+
+### Step 7: Test the Connection
1. Log out of NetBird Dashboard
2. On the login page, you should see a "Keycloak" button
-3. Click it and authenticate with your Keycloak credentials
+3. Click it and authenticate with the user credentials you created in Step 2
4. You should be redirected back to NetBird and logged in
+
+
+
+
Users who authenticate via Keycloak will appear in your NetBird Users list with a Keycloak badge next to their name.
@@ -75,225 +150,12 @@ Use Keycloak as your primary identity provider instead of NetBird's embedded IdP
For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Management Setup (Recommended)](#management-setup-recommended) section above.
+For detailed instructions on the standalone setup, see the [Keycloak SSO with NetBird Self-Hosted (Advanced)](/selfhosted/identity-providers/advanced/keycloak) documentation.
+
If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like [Auth0](/selfhosted/identity-providers/managed/auth0).
-### Expected Result
-
-After completing this guide, you can log in to your self-hosted NetBird Dashboard and add machines to your network using the [Interactive SSO Login feature](/get-started/install#running-net-bird-with-sso-login) over Keycloak.
-
-
-
-
-
-### Prerequisites
-
-- Keycloak instance running with SSL
-- Docker and Docker Compose for NetBird
-
-### Step 1: Check Your Keycloak Instance
-
-Ensure your Keycloak instance is available at `https://YOUR-KEYCLOAK-HOST-AND-PORT` with SSL enabled.
-
-### Step 2: Create a Realm
-
-1. Open the Keycloak Admin Console
-2. Hover over the dropdown in the top-left corner where it says `Master`
-3. Click **Create Realm**
-4. Fill in:
- - **Realm name**: `netbird`
-5. Click **Create**
-
-
-
-
-
-### Step 3: Create a User
-
-1. Make sure the selected realm is `netbird`
-2. Click **Users** (left-hand menu)
-3. Click **Create new user**
-4. Fill in:
- - **Username**: `netbird`
-5. Click **Create**
-
-
-
-
-
-6. Click **Credentials** tab
-7. Click **Set password**
-8. Fill in the password and set **Temporary** to `Off`
-9. Click **Save**
-
-
-
-5. Click **Save**
-6. Go to **Credentials** tab
-7. Copy the **Client secret**
-
-
-
-
-
-### Step 9: Add View-Users Role
-
-1. Go to **Clients** → **netbird-backend**
-2. Switch to **Service accounts roles** tab
-3. Click **Assign roles**
-4. Select **Filter by clients** and search for `view-users`
-
-
-
-
-
-5. Check the role checkbox and click **Assign**
-
-
-
-
-
-
-**Optional**: To enable automatic user deletion from Keycloak when deleted from NetBird, add the `--user-delete-from-idp` flag to the management startup command and assign the `manage-users` role instead.
-
-
-### Step 10: Configure NetBird
-
-Your authority OIDC configuration will be available at:
-
-```bash
-https:///realms/netbird/.well-known/openid-configuration
-```
-
-
-Double-check if the endpoint returns a JSON response by calling it from your browser.
-
-
-Set properties in the `setup.env` file:
-
-```shell
-NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///realms/netbird/.well-known/openid-configuration"
-NETBIRD_USE_AUTH0=false
-NETBIRD_AUTH_CLIENT_ID="netbird-client"
-NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
-NETBIRD_AUTH_AUDIENCE="netbird-client"
-
-NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="netbird-client"
-NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="netbird-client"
-
-NETBIRD_MGMT_IDP="keycloak"
-NETBIRD_IDP_MGMT_CLIENT_ID="netbird-backend"
-NETBIRD_IDP_MGMT_CLIENT_SECRET=""
-NETBIRD_IDP_MGMT_EXTRA_ADMIN_ENDPOINT="https:///admin/realms/netbird"
-```
-
-
-Make sure your Keycloak instance uses HTTPS. Otherwise, the setup won't work.
-
-
-### Step 11: Continue with NetBird Setup
-
-You've configured all required resources in Keycloak. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
-
---
## Troubleshooting
@@ -301,19 +163,17 @@ You've configured all required resources in Keycloak. Continue with the [NetBird
### "Invalid redirect URI" error
- Ensure the redirect URI matches exactly what's configured
-- For Management Setup: Use the exact URL from the NetBird success modal
-- For standalone: Include both `https://YOUR_DOMAIN/*` and `http://localhost:53000`
+- Use the exact URL from the NetBird success modal
### "Invalid token" errors
-- Verify the issuer URL includes `/realms/your-realm`
+- Verify the issuer URL includes `/realms/netbird` (or your realm name)
- Ensure the client ID matches in both Keycloak and NetBird
- Check clock synchronization between servers
### Users not appearing in NetBird
-- For Management Setup: Users appear after their first successful login
-- For standalone: Verify the backend client has `view-users` role
+- Users appear after their first successful login
---
diff --git a/src/pages/selfhosted/identity-providers/managed/advanced/auth0.mdx b/src/pages/selfhosted/identity-providers/managed/advanced/auth0.mdx
new file mode 100644
index 00000000..fc3bb22a
--- /dev/null
+++ b/src/pages/selfhosted/identity-providers/managed/advanced/auth0.mdx
@@ -0,0 +1,202 @@
+import {Note} from "@/components/mdx";
+
+# Auth0 SSO with NetBird Self-Hosted (Legacy)
+
+[Auth0](https://auth0.com/) is a flexible, drop-in solution to add authentication and authorization services to your applications. It's a managed service that handles identity infrastructure so you don't have to.
+
+## Standalone Setup (Advanced)
+
+
+NetBird includes built-in [local user management](/selfhosted/identity-providers/local) powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add **multiple external identity providers** alongside local users, giving users multiple login options.
+
+We highly recommend using the simpler setup that adds Auth0 as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the [Management Setup (Recommended)](/selfhosted/identity-providers/managed/auth0#management-setup-recommended) section in the main Auth0 documentation.
+
+The standalone setup below replaces your embedded IdP entirely and is only recommended for experienced Auth0 administrators who need full control over authentication and user management.
+
+
+Use Auth0 as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced Auth0 administrators as it also requires additional setup and ongoing maintenance.
+
+For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Management Setup (Recommended)](#management-setup-recommended) section above.
+
+
+If you prefer to have full control over authentication, consider self-hosted alternatives like [PocketID](/selfhosted/identity-providers/pocketid).
+
+
+### Prerequisites
+
+- Auth0 account (sign up at https://auth0.com/)
+- Docker and Docker Compose for NetBird
+
+### Configuration Properties
+
+You will configure these properties in `setup.env`:
+
+- `NETBIRD_AUTH_CLIENT_ID`
+- `NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT`
+- `NETBIRD_USE_AUTH0`
+- `NETBIRD_AUTH_AUDIENCE`
+- `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID` (Optional)
+- `NETBIRD_MGMT_IDP`
+- `NETBIRD_IDP_MGMT_CLIENT_ID`
+- `NETBIRD_IDP_MGMT_CLIENT_SECRET`
+- `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE`
+
+### Step 1: Create Dashboard Application
+
+This application authorizes access to NetBird Dashboard.
+
+1. Follow the [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0) up to "Install the Auth0 React SDK"
+2. Set **Allowed Callback URLs**: `https://YOUR_DOMAIN` and `http://localhost:53000`
+3. Set **Allowed Logout URLs**, **Allowed Web Origins**, **Allowed Origins (CORS)**: `https://YOUR_DOMAIN` and `http://localhost`
+
+
+Ensure **Token Endpoint Authentication Method** is set to **None**.
+
+
+4. Use **Client ID** for `NETBIRD_AUTH_CLIENT_ID`
+5. Use **Domain** to configure `NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT`:
+
+```bash
+https:///.well-known/openid-configuration
+```
+
+
+Double-check if the endpoint returns a JSON response by calling it from your browser.
+
+
+### Step 2: Create API
+
+This API is used to access NetBird Management Service.
+
+1. Follow the [Auth0 Create An API](https://auth0.com/docs/quickstart/backend/golang#create-an-api) guide
+2. Use the API **Identifier** for `NETBIRD_AUTH_AUDIENCE`
+3. Set `NETBIRD_USE_AUTH0=true`
+
+### Step 3: Enable Interactive SSO Login (Optional)
+
+This enables machine authorization via your Identity Provider as an alternative to [setup keys](/manage/peers/register-machines-using-setup-keys).
+
+1. Go to **Applications**
+2. Click **Create Application**
+3. Fill in:
+ - **Name**: `Interactive Login`
+ - **Application type**: `Native`
+4. Click **Create**
+
+
+
+
+**Optional**: To enable automatic user deletion from Auth0 when deleted from NetBird, add the `--user-delete-from-idp` flag to the management startup command and assign the `delete:users` permission.
+
+
+7. Click **Settings** tab
+8. Copy values:
+ - **Client ID** → `NETBIRD_IDP_MGMT_CLIENT_ID`
+ - **Client Secret** → `NETBIRD_IDP_MGMT_CLIENT_SECRET`
+ - **Domain** → `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE` (format: `https:///api/v2/`)
+
+
+
+
+
+### Step 5: Configure NetBird
+
+Set properties in the `setup.env` file:
+
+```shell
+NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///.well-known/openid-configuration"
+NETBIRD_USE_AUTH0=true
+NETBIRD_AUTH_CLIENT_ID=""
+NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api email_verified"
+NETBIRD_AUTH_AUDIENCE=""
+NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
+
+NETBIRD_MGMT_IDP="auth0"
+NETBIRD_IDP_MGMT_CLIENT_ID=""
+NETBIRD_IDP_MGMT_CLIENT_SECRET=""
+NETBIRD_IDP_MGMT_EXTRA_AUDIENCE="https:///api/v2/"
+```
+
+### Step 6: Continue with NetBird Setup
+
+You've configured all required resources in Auth0. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
+
+---
+
+## Troubleshooting
+
+### "Invalid redirect URI" error
+
+- Ensure all callback URLs are configured in Auth0
+- Check for trailing slashes
+- Verify URLs match exactly
+
+### "Unauthorized" errors for Management API
+
+- Verify the Machine to Machine application has correct permissions
+- Check that `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE` includes `/api/v2/`
+
+### Device authorization not working
+
+- Ensure Device Code grant is enabled in Advanced Settings
+- Verify the native application Client ID is used
+
+### Token validation errors
+
+- Verify `NETBIRD_USE_AUTH0=true` is set
+- Check the audience matches the API identifier
+
+---
+
+
+NetBird includes built-in [local user management](/selfhosted/identity-providers/local) powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add **multiple external identity providers** alongside local users, giving users multiple login options.
+
+We highly recommend using the simpler setup that adds Auth0 as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the [Management Setup (Recommended)](/selfhosted/identity-providers/managed/auth0#management-setup-recommended) section in the main Auth0 documentation.
+
+
+## Related Resources
+
+- [Auth0 Documentation](https://auth0.com/docs/)
+- [Auth0 Dashboard](https://manage.auth0.com/)
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/advanced/google-workspace.mdx b/src/pages/selfhosted/identity-providers/managed/advanced/google-workspace.mdx
new file mode 100644
index 00000000..7617d85f
--- /dev/null
+++ b/src/pages/selfhosted/identity-providers/managed/advanced/google-workspace.mdx
@@ -0,0 +1,230 @@
+import {Note} from "@/components/mdx";
+
+# Google Workspace SSO with NetBird Self-Hosted (Legacy)
+
+Use Google accounts for authentication with NetBird. This supports both personal Google accounts and Google Workspace (formerly G Suite) organizations.
+
+## Standalone Setup (Advanced)
+
+
+NetBird includes built-in [local user management](/selfhosted/identity-providers/local) powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add **multiple external identity providers** alongside local users, giving users multiple login options.
+
+We highly recommend using the simpler setup that adds Google as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the [Management Setup (Recommended)](/selfhosted/identity-providers/managed/google-workspace#management-setup-recommended) section in the main Google Workspace documentation.
+
+The standalone setup below replaces your embedded IdP entirely and is only recommended for experienced Google Workspace administrators who need full control over authentication and user management.
+
+
+Use Google Workspace as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced Google Workspace administrators as it also requires additional setup and ongoing maintenance.
+
+For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Management Setup (Recommended)](#management-setup-recommended) section above.
+
+
+Beginning with NetBird version v0.23.6 and onwards, the Google Workspace IdP manager no longer requires the custom admin role called `User and Schema Management`. We now use a read-only role for user information.
+
+
+### Prerequisites
+
+- A Google Workspace account (not just personal Google)
+- Admin permissions in Google Workspace
+- A project in [Google Cloud Console](https://console.cloud.google.com)
+- Enable **Admin SDK API** for your project at https://console.cloud.google.com/apis/library/admin.googleapis.com
+
+### Step 1: Configure OAuth Consent Screen
+
+1. Navigate to [OAuth consent](https://console.cloud.google.com/apis/credentials/consent)
+2. Select **Internal** User Type and click **Create**
+
+
+
+
+
+3. Fill in the form:
+ - **App name**: `Netbird`
+ - **User support email**: ``
+ - **Authorized domain**: ``
+ - **Developer contact information**: ``
+4. Click **SAVE AND CONTINUE**
+5. Click **ADD OR REMOVE SCOPES**
+6. Select `/auth/userinfo.email`, `/auth/userinfo.profile`, and `openid`
+7. Click **UPDATE**
+
+
+
+
+
+8. Click **SAVE AND CONTINUE**
+9. Review the summary and click **BACK TO DASHBOARD**
+
+
+
+5. Note **Client ID** and **Client Secret**
+
+
+
+
+
+### Step 3: Create Service Account
+
+1. Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials)
+2. Click **CREATE CREDENTIALS** → **Service account**
+3. Fill in:
+ - **Service account name**: `netbird`
+ - **Service account ID**: `netbird`
+4. Note the service account email address
+5. Click **DONE**
+
+
+
+
+
+### Step 4: Create Service Account Keys
+
+1. Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials)
+2. Under **Service Accounts**, click **netbird** to edit
+
+
+
+
+
+3. Click the **Keys** tab
+4. Click **Add key** → **Create new key**
+5. Select **JSON** and click **Create**
+
+
+The key file downloads automatically. Store it securely. Read about [managing service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys#temp-locations).
+
+
+6. Open the downloaded JSON file and note the `client_id` (Service Account Client ID)
+
+### Step 5: Grant User Management Admin Role
+
+1. Navigate to [Admin Console](https://admin.google.com/ac/home)
+2. Select **Account** → **Admin Roles**
+3. Click **Create new role**
+4. Fill in:
+ - **Name**: `User Management ReadOnly`
+ - **Description**: `User Management ReadOnly`
+5. Click **CONTINUE**
+
+
+
+
+
+6. Scroll to **Admin API privileges** and add:
+ - **Users**: `Read`
+7. Click **CONTINUE**
+
+
+
+
+
+8. Click **CREATE ROLE**
+9. Click **Assign service accounts**
+10. Add the service account email address
+11. Click **ADD** then **ASSIGN ROLE**
+
+
+
+
+
+
+
+
+
+12. Navigate to [Account Settings](https://admin.google.com/ac/accountsettings/profile) and note the **Customer ID**
+
+### Step 6: Encode Service Account Key
+
+```bash
+base64 -i
+```
+
+### Step 7: Configure NetBird
+
+Set properties in the `setup.env` file:
+
+```shell
+NETBIRD_DOMAIN=""
+NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://accounts.google.com/.well-known/openid-configuration"
+NETBIRD_USE_AUTH0=false
+NETBIRD_AUTH_AUDIENCE=""
+NETBIRD_AUTH_CLIENT_ID=""
+NETBIRD_AUTH_CLIENT_SECRET=""
+NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email"
+NETBIRD_AUTH_REDIRECT_URI="/auth"
+NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
+NETBIRD_TOKEN_SOURCE="idToken"
+
+NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"
+
+NETBIRD_MGMT_IDP="google"
+NETBIRD_MGMT_IDP_SIGNKEY_REFRESH=true
+NETBIRD_IDP_MGMT_EXTRA_SERVICE_ACCOUNT_KEY=""
+NETBIRD_IDP_MGMT_EXTRA_CUSTOMER_ID=""
+```
+
+### Step 8: Continue with NetBird Setup
+
+You've configured all required resources in Google Workspace. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
+
+---
+
+## Troubleshooting
+
+### "Access blocked" error
+
+- Ensure OAuth consent screen is configured correctly
+- For external apps, you may need to submit for verification or add test users
+- Check that required scopes are added
+
+### "Invalid redirect URI" error
+
+- Verify the redirect URI exactly matches what's in Google Cloud Console
+- Check for trailing slashes or HTTP vs HTTPS mismatches
+- Google is case-sensitive for redirect URIs
+
+### Users from wrong domain signing in
+
+- For Workspace, use **Internal** user type in OAuth consent screen
+- Verify domain restrictions in consent screen settings
+
+### Service account not syncing users
+
+- Verify Admin SDK API is enabled
+- Check that the service account has the User Management ReadOnly role
+- Ensure the Customer ID is correct
+
+---
+
+
+NetBird includes built-in [local user management](/selfhosted/identity-providers/local) powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add **multiple external identity providers** alongside local users, giving users multiple login options.
+
+We highly recommend using the simpler setup that adds Google as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the [Management Setup (Recommended)](/selfhosted/identity-providers/managed/google-workspace#management-setup-recommended) section in the main Google Workspace documentation.
+
+
+## Related Resources
+
+- [Google Cloud Console](https://console.cloud.google.com/)
+- [Google OAuth 2.0 Documentation](https://developers.google.com/identity/protocols/oauth2)
+- [Google Workspace Admin Console](https://admin.google.com/)
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/advanced/jumpcloud.mdx b/src/pages/selfhosted/identity-providers/managed/advanced/jumpcloud.mdx
new file mode 100644
index 00000000..e481c083
--- /dev/null
+++ b/src/pages/selfhosted/identity-providers/managed/advanced/jumpcloud.mdx
@@ -0,0 +1,281 @@
+import {Note} from "@/components/mdx";
+
+# JumpCloud SSO with NetBird Self-Hosted (Legacy)
+
+[JumpCloud](https://jumpcloud.com/) is a cloud-based directory platform that provides identity, access, and device management. It offers single sign-on (SSO), multi-factor authentication (MFA), and centralized user management.
+
+## Standalone Setup (Advanced)
+
+
+NetBird includes built-in [local user management](/selfhosted/identity-providers/local) powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add **multiple external identity providers** alongside local users, giving users multiple login options.
+
+We highly recommend using the simpler setup that adds JumpCloud as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the [Management Setup (Recommended)](/selfhosted/identity-providers/managed/jumpcloud#management-setup-recommended) section in the main JumpCloud documentation.
+
+The standalone setup below replaces your embedded IdP entirely and is only recommended for experienced JumpCloud administrators who need full control over authentication and user management.
+
+
+Use JumpCloud as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced JumpCloud administrators as it also requires additional setup and ongoing maintenance.
+
+For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Management Setup (Recommended)](#management-setup-recommended) section above.
+
+### Prerequisites
+
+- JumpCloud account with admin permissions (sign up at https://jumpcloud.com/)
+- Docker and Docker Compose for NetBird
+
+### Step 1: Create and Configure SSO Application
+
+1. Navigate to [Admin Portal](https://console.jumpcloud.com/)
+2. Click **SSO Applications** under **USER AUTHENTICATION**
+3. Click **Add New Application** → **Custom Application**
+
+
+
+12. Click **User Groups** tab and select groups that can access the application
+
+
+
+
+
+13. Click **Activate**
+
+
+
+
+
+14. Note the **Client ID**
+
+### Step 2: Create Administrator for Integration
+
+The NetBird management system requires an API token to get user information from JumpCloud.
+
+
+If you already have an integration user, confirm it has the required role and skip to Step 3.
+
+
+1. Navigate to [Admin Portal](https://console.jumpcloud.com/)
+2. Go to **Settings** and click the add button (+)
+3. Fill in:
+ - **First Name**: `NetBird`
+ - **Last Name**: `Integration`
+ - **Administrator Email**: `netbird-user@`
+ - **Role**: `Read Only`
+4. Click **Save**
+
+
+
+
+
+
+**Optional**: To enable automatic user deletion from JumpCloud when deleted from NetBird, add the `--user-delete-from-idp` flag to the management startup command and assign the `Help Desk` role instead.
+
+
+5. Check email for login instructions and set a password
+
+### Step 3: Generate API Token
+
+1. Log in to [Admin Portal](https://console.jumpcloud.com/) with the integration user
+2. Click the account initials (top-right) → **My API Key**
+
+
+
+
+
+3. If no key exists, click **Generate New API Key**
+4. Copy the API token
+
+
+
+
+
+### Step 4: Configure NetBird
+
+Set properties in the `setup.env` file:
+
+```shell
+NETBIRD_DOMAIN=""
+NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://oauth.id.jumpcloud.com/.well-known/openid-configuration"
+NETBIRD_USE_AUTH0=false
+NETBIRD_DASH_AUTH_USE_AUDIENCE=false
+NETBIRD_AUTH_AUDIENCE=""
+NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access"
+NETBIRD_AUTH_CLIENT_ID=""
+NETBIRD_AUTH_REDIRECT_URI="/auth"
+NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
+NETBIRD_TOKEN_SOURCE="idToken"
+
+NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"
+
+NETBIRD_MGMT_IDP="jumpcloud"
+NETBIRD_IDP_MGMT_EXTRA_API_TOKEN=""
+```
+
+### Step 5: Continue with NetBird Setup
+
+You've configured all required resources in JumpCloud. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-5-run-configuration-script).
+
+---
+
+## Troubleshooting
+
+### "Issuer did not match" or "Unauthenticated" error
+
+If you see an error like:
+
+```
+FATL ... oidc: issuer did not match the issuer returned by provider, expected "https://oauth.id.jumpcloud.com" got "https://oauth.id.jumpcloud.com/"
+```
+
+This means there's a trailing slash mismatch in the Issuer URL. OIDC validation is strictly character-for-character.
+
+**The Cause:**
+- **Configured in NetBird:** `https://oauth.id.jumpcloud.com` (missing trailing slash)
+- **Returned by JumpCloud:** `https://oauth.id.jumpcloud.com/` (has trailing slash)
+
+Because the service fails to initialize the IDP manager, the Management container will often crash or restart loop, making it impossible to fix this via the Web UI.
+
+**Resolution:**
+
+If you can still access NetBird Dashboard:
+1. Navigate to **Settings** → **Identity Providers**
+2. Edit the JumpCloud identity provider
+3. Change the **Issuer** field to exactly `https://oauth.id.jumpcloud.com/` (with trailing slash)
+4. Click **Save**
+5. Restart the management container: `docker restart netbird-management`
+
+If you cannot access the dashboard (locked out), you must fix it directly in the SQLite database:
+
+1. **Locate the Volume:**
+ ```bash
+ docker volume inspect root_netbird_management
+ # Look for "Mountpoint", e.g., /var/lib/docker/volumes/root_netbird_management/_data
+ ```
+
+2. **Access the Database:**
+ ```bash
+ cd /var/lib/docker/volumes/root_netbird_management/_data
+
+ # Backup the database first!
+ cp idp.db idp.db.bak
+
+ # Open the database
+ sqlite3 idp.db
+ ```
+
+3. **Update the Issuer URL:**
+ Inside the SQLite prompt, run the following:
+ ```sql
+ -- Check current config to confirm missing slash
+ SELECT config FROM connector;
+
+ -- Update the config to add trailing slash to match JumpCloud
+ UPDATE connector
+ SET config = replace(config, 'jumpcloud.com"', 'jumpcloud.com/"')
+ WHERE config LIKE '%jumpcloud.com"%';
+
+ -- Verify the change
+ SELECT config FROM connector;
+
+ -- Exit
+ .quit
+ ```
+
+4. **Restart Service:**
+ ```bash
+ docker restart netbird-management
+ ```
+
+The service should now start successfully, and the error should be resolved.
+
+
+### "Connector failed to initialize" error
+
+- Ensure **Attribute Mapping** has both **Email** and **Profile** scopes enabled
+- Verify at least one **User Group** is assigned to the application before activation
+- Check that **Redirect URIs** exactly matches the URL from NetBird (no trailing slashes)
+- Ensure **Client Authentication Type** is set to `Client Secret POST`
+- Verify **Login URL** matches your NetBird domain exactly
+- Make sure the application is **Activated** and you have the correct **Client ID** and **Client Secret**
+- Remove any duplicate attributes in **Attribute Mapping** (e.g., `email` and `email_verified`)
+
+### "Invalid redirect URI" error
+
+- Ensure all redirect URIs are configured in JumpCloud
+- Check for trailing slashes
+- Verify URLs match exactly
+
+### Users can't access NetBird
+
+- Verify the user belongs to an assigned user group
+- Check that the user group is assigned to the NetBird application
+
+### API token not working
+
+- Verify the integration user has appropriate permissions
+- Generate a new API token if the current one is invalid
+
+### Device authorization not available
+
+- JumpCloud has limited device auth support
+- Set `NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"`
+
+---
+
+
+NetBird includes built-in [local user management](/selfhosted/identity-providers/local) powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add **multiple external identity providers** alongside local users, giving users multiple login options.
+
+We highly recommend using the simpler setup that adds JumpCloud as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the [Management Setup (Recommended)](/selfhosted/identity-providers/managed/jumpcloud#management-setup-recommended) section in the main JumpCloud documentation.
+
+
+## Related Resources
+
+- [JumpCloud Documentation](https://jumpcloud.com/support)
+- [JumpCloud Admin Console](https://console.jumpcloud.com/)
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/advanced/microsoft-entra-id.mdx b/src/pages/selfhosted/identity-providers/managed/advanced/microsoft-entra-id.mdx
new file mode 100644
index 00000000..25d2ea7e
--- /dev/null
+++ b/src/pages/selfhosted/identity-providers/managed/advanced/microsoft-entra-id.mdx
@@ -0,0 +1,212 @@
+import {Note} from "@/components/mdx";
+
+# Microsoft and Entra ID SSO with NetBird Self-Hosted (Legacy)
+
+Use Microsoft accounts for authentication with NetBird. This supports both personal Microsoft accounts and Microsoft Entra ID (formerly Azure AD) for work and school accounts.
+
+## Standalone Setup (Advanced)
+
+
+NetBird includes built-in [local user management](/selfhosted/identity-providers/local) powered by an embedded IdP, allowing you to create and manage users directly without requiring an external identity provider. You can also add **multiple external identity providers** alongside local users, giving users multiple login options.
+
+We highly recommend using the simpler setup that adds Microsoft as an external IdP directly in the NetBird Management Dashboard. This approach requires minimal configuration, works alongside local users, and doesn't require replacing your embedded IdP. See the [Management Setup (Recommended)](/selfhosted/identity-providers/managed/microsoft-entra-id#management-setup-recommended) section in the main Microsoft Entra ID documentation.
+
+The standalone setup below replaces your embedded IdP entirely and is only recommended for experienced Microsoft Entra ID administrators who need full control over authentication and user management.
+
+
+Use Microsoft Entra ID as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced Microsoft Entra ID administrators as it also requires additional setup and ongoing maintenance.
+
+For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Management Setup (Recommended)](#management-setup-recommended) section above.
+
+
+If you prefer to have full control over authentication, consider self-hosted alternatives like [PocketID](/selfhosted/identity-providers/pocketid).
+
+
+### Prerequisites
+
+- An Azure account with appropriate permissions
+- Docker and Docker Compose for NetBird
+
+### Step 1: Create and Configure Azure AD Application
+
+1. Navigate to [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)
+2. Click **App Registrations** → **+ New registration**
+3. Fill in:
+ - **Name**: `Netbird`
+ - **Supported account types**: `Accounts in this organizational directory only (Default Directory only - Single tenant)`
+ - **Redirect URI**: Select `Single-page application (SPA)` and enter `https:///silent-auth`
+4. Click **Register**
+5. After registration, note the **Application (client) ID** from the Overview page (you'll need this in Step 3)
+
+
+
+
+
+### Step 2: Configure Platform Settings
+
+1. Click **Authentication** on the left menu
+2. Under **Single-page application**, add another URI: `https:///auth`
+
+
+
+
+
+3. Scroll down and configure options as shown:
+
+
+
+
+
+4. Click **Add a Platform** → **Mobile and desktop applications**
+5. Add custom redirect URI: `http://localhost:53000`
+6. Click **Configure**
+
+### Step 3: Create Application Scope
+
+1. Click **Expose an API** on the left menu
+2. Under **Application ID URI**, click **Set** then **Save**
+3. Click **+ Add a Scope**
+4. Fill in:
+ - **Scope name**: `api`
+5. Click **Add scope**
+
+
+
+
+
+6. Under **Authorized client applications**, click **+ Add a client application**
+7. Enter your **Client ID** (the Application (client) ID you noted when creating the app registration in Step 1)
+8. Click **Add application**
+
+
+
+
+
+### Step 4: Add API Permissions
+
+1. Click **API permissions** on the left menu
+2. Click **Add a permission**
+3. Select **My APIs** tab → **Netbird** → check `api` permission → **Add permissions**
+
+
+
+
+
+4. Click **Add a permission** again
+5. Select **Microsoft Graph** → **Application permissions**
+6. Search for `User.Read` and select `User.Read.All`
+7. Click **Add permissions**
+
+
+
+### Step 5: Update Token Version
+
+1. Click **Manifest** on the left menu
+2. Find `accessTokenAcceptedVersion` and change from `null` to `2`
+3. Click **Save**
+
+### Step 6: Generate Client Secret
+
+1. Click **Certificates & secrets** on the left menu
+2. Click **New client secret**
+3. Fill in:
+ - **Description**: `Netbird`
+4. Click **Add**
+5. Copy the **Value** immediately
+
+
+
+
+
+6. Click **Overview** and note:
+ - **Application (client) ID**
+ - **Object ID**
+ - **Directory (tenant) ID**
+
+### Step 7: Configure NetBird
+
+Your authority OIDC configuration will be available at:
+
+```bash
+https://login.microsoftonline.com//v2.0/.well-known/openid-configuration
+```
+
+
+Double-check if the endpoint returns a JSON response by calling it from your browser.
+
+
+Set properties in the `setup.env` file:
+
+```shell
+NETBIRD_DOMAIN=""
+NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://login.microsoftonline.com//v2.0/.well-known/openid-configuration"
+NETBIRD_USE_AUTH0=false
+NETBIRD_AUTH_CLIENT_ID=""
+NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access User.Read api:///api"
+NETBIRD_AUTH_AUDIENCE=""
+NETBIRD_AUTH_REDIRECT_URI="/auth"
+NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
+NETBIRD_AUTH_USER_ID_CLAIM="oid"
+NETBIRD_TOKEN_SOURCE="idToken"
+
+NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"
+
+NETBIRD_MGMT_IDP="azure"
+NETBIRD_IDP_MGMT_CLIENT_ID=""
+NETBIRD_IDP_MGMT_CLIENT_SECRET=""
+NETBIRD_IDP_MGMT_EXTRA_OBJECT_ID="
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+