+ Check if the instance requires initial setup. This endpoint is only available when embedded IdP is enabled and no accounts exist. It is **unauthenticated** and only works before setup is complete.
+
+
+
+ Create the initial owner account. This endpoint is only available when embedded IdP is enabled and no accounts exist. It is **unauthenticated** and only works before setup is complete.
+
+ ### Request-Body Parameters
+
+
+
+ Email address for the owner account
+
+
+
+
+ Password for the owner account (minimum 8 characters)
+
+
+
+
+ Display name for the owner account
+
+
+
+
+
+ After setup is complete, accessing this endpoint returns a 412 error and redirects to login.
+
+
+
+
+
+ Returns a list of all configured identity provider connectors. These endpoints are only available when embedded IdP is enabled (`account.settings.extra.embedded_idp_enabled: true`).
+
+
+ Client secrets are never returned in API responses for security.
+
+
+
+
+ Update an existing identity provider connector. The `type` cannot be changed after creation.
+
+ ### Path Parameters
+
+
+
+ The unique identifier of an identity provider
+
+
+
+ ### Request-Body Parameters
+
+
+
+ Display name on login page
+
+
+
+
+ OAuth client ID from your identity provider
+
+
+
+
+ OAuth client secret. If empty or omitted, the existing secret is preserved.
+
+
+
+
+ Issuer URL. Only applicable for `okta`, `zitadel`, `pocketid`, and `oidc` types.
+
+
+
+
+
+ Include only fields you want to update. If `client_secret` is empty or omitted, the existing secret is preserved.
+
+
+
+
+
+
+ Remove an identity provider connector.
+
+ ### Path Parameters
+
+
+
+ The unique identifier of an identity provider
+
+
+
+
+ **Warning:** Deleting an identity provider will prevent users who authenticate exclusively through that provider from logging in.
+
+
+
+
- Creates a new service user or sends an invite to a regular user
+ Creates a new service user or sends an invite to a regular user. When embedded IdP is enabled (`account.settings.extra.embedded_idp_enabled: true`), this endpoint creates a local user with a generated password that is returned in the response.
### Request-Body Parameters
@@ -295,6 +295,9 @@ echo $response;
+
+ **Embedded IdP Behavior:** When embedded IdP is enabled, the response includes a `password` field containing the generated password. This password is only returned once at creation time and cannot be retrieved later. Store it securely or share it with the user immediately. Users authenticated through external identity provider connectors will have an `idp_id` field linking them to the provider.
+
@@ -532,6 +535,8 @@ echo $response;
"is_service_user": false,
"is_blocked": false,
"issued": "api",
+ "password": "generated-password-here",
+ "idp_id": "idp-def456",
"permissions": {
"is_restricted": {
"type": "boolean",
@@ -569,6 +574,8 @@ echo $response;
"is_service_user": "boolean",
"is_blocked": "boolean",
"issued": "string",
+ "password": "string",
+ "idp_id": "string",
"permissions": {
"is_restricted": "boolean",
"modules": {
diff --git a/src/pages/selfhosted/identity-providers/api-reference.mdx b/src/pages/selfhosted/identity-providers/api-reference.mdx
new file mode 100644
index 000000000..2311925c5
--- /dev/null
+++ b/src/pages/selfhosted/identity-providers/api-reference.mdx
@@ -0,0 +1,490 @@
+# Identity Provider API Reference
+
+This page documents the API endpoints for managing identity providers when using the [embedded IdP](/selfhosted/identity-providers/embedded-idp).
+
+## Base URL
+
+All endpoints are relative to your NetBird Management API:
+
+```
+https://netbird.example.com/api
+```
+
+## Authentication
+
+Most endpoints require authentication via Bearer token:
+
+```
+Authorization: Bearer
+```
+
+## Permissions
+
+Identity provider management requires administrator privileges. The following permission is required:
+
+- `identity_providers` permission - For managing identity provider configurations
+- `settings:read` - For viewing the Identity Providers tab
+
+---
+
+## Instance Setup
+
+These endpoints handle the initial setup when embedded IdP is enabled and no accounts exist. Both endpoints are **unauthenticated** and only work before setup is complete.
+
+### Get Instance Status
+
+Check if the instance requires initial setup.
+
+```http
+GET /instance
+```
+
+**Authentication:** None required (public endpoint)
+
+**Response:**
+
+```json
+{
+ "setup_required": true
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `setup_required` | boolean | `true` if no accounts exist and setup is needed |
+
+### Complete Setup
+
+Create the initial owner account.
+
+```http
+POST /instance/setup
+```
+
+**Authentication:** None required (only available during setup)
+
+**Request Body:**
+
+```json
+{
+ "email": "admin@example.com",
+ "password": "securepassword123",
+ "name": "Admin User"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `email` | string | Yes | Email address for the owner account |
+| `password` | string | Yes | Password (minimum 8 characters) |
+| `name` | string | No | Display name |
+
+**Response:**
+
+```json
+{
+ "user_id": "user-abc123",
+ "account_id": "account-xyz789"
+}
+```
+
+**Errors:**
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | `invalid_request` | Missing required fields or invalid format |
+| 412 | `precondition_failed` | Setup already completed (redirects to login) |
+| 503 | `idp_unavailable` | Embedded IdP is not enabled |
+
+---
+
+## Identity Providers (Connectors)
+
+Manage external identity provider connectors. The Identity Providers tab is visible in Settings when `embedded_idp_enabled` is `true` in account settings.
+
+### List Identity Providers
+
+Get all configured identity providers.
+
+```http
+GET /identity-providers
+```
+
+**Response:**
+
+```json
+[
+ {
+ "id": "idp-abc123",
+ "type": "google",
+ "name": "Google Workspace",
+ "client_id": "123456789.apps.googleusercontent.com",
+ "issuer": "",
+ "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
+ },
+ {
+ "id": "idp-def456",
+ "type": "oidc",
+ "name": "Corporate SSO",
+ "client_id": "netbird-client",
+ "issuer": "https://sso.example.com",
+ "redirect_url": "https://netbird.example.com/api/idp/callback/idp-def456"
+ }
+]
+```
+
+
+Client secrets are never returned in API responses for security.
+
+
+### Get Identity Provider
+
+Get details for a specific identity provider.
+
+```http
+GET /identity-providers/{id}
+```
+
+**Path Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | string | Identity provider ID |
+
+**Response:**
+
+```json
+{
+ "id": "idp-abc123",
+ "type": "google",
+ "name": "Google Workspace",
+ "client_id": "123456789.apps.googleusercontent.com",
+ "issuer": "",
+ "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
+}
+```
+
+### Create Identity Provider
+
+Add a new identity provider connector.
+
+```http
+POST /identity-providers
+```
+
+**Request Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | Yes | Provider type (see below) |
+| `name` | string | Yes | Display name on login page |
+| `client_id` | string | Yes | OAuth client ID |
+| `client_secret` | string | Yes | OAuth client secret |
+| `issuer` | string | Conditional | Issuer URL (required for oidc, okta, zitadel, pocketid) |
+
+**Provider Types:**
+
+| Type | Description | Requires Issuer |
+|------|-------------|-----------------|
+| `google` | Google accounts / Google Workspace | No |
+| `microsoft` | Microsoft personal accounts | No |
+| `entra` | Microsoft Entra ID (Azure AD) | No |
+| `okta` | Okta SSO | Yes |
+| `zitadel` | Zitadel IdP | Yes |
+| `pocketid` | PocketID | Yes |
+| `oidc` | Generic OIDC provider | Yes |
+
+#### Google Configuration
+
+```json
+{
+ "type": "google",
+ "name": "Google Workspace",
+ "client_id": "123456789.apps.googleusercontent.com",
+ "client_secret": "GOCSPX-xxxxx"
+}
+```
+
+
+Google and Microsoft types do not require an `issuer` field - the issuer is determined automatically.
+
+
+#### Microsoft / Entra ID Configuration
+
+```json
+{
+ "type": "entra",
+ "name": "Microsoft Entra ID",
+ "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+ "client_secret": "xxxxx"
+}
+```
+
+Use `microsoft` for personal Microsoft accounts, or `entra` for Azure AD / work accounts.
+
+#### Okta Configuration
+
+```json
+{
+ "type": "okta",
+ "name": "Okta SSO",
+ "client_id": "0oaxxxxxxxxxx",
+ "client_secret": "xxxxx",
+ "issuer": "https://yourcompany.okta.com/oauth2/default"
+}
+```
+
+#### Zitadel Configuration
+
+```json
+{
+ "type": "zitadel",
+ "name": "Zitadel",
+ "client_id": "123456789",
+ "client_secret": "xxxxx",
+ "issuer": "https://zitadel.example.com"
+}
+```
+
+#### PocketID Configuration
+
+```json
+{
+ "type": "pocketid",
+ "name": "PocketID",
+ "client_id": "netbird",
+ "client_secret": "xxxxx",
+ "issuer": "https://pocketid.example.com"
+}
+```
+
+#### Generic OIDC Configuration
+
+```json
+{
+ "type": "oidc",
+ "name": "Custom SSO",
+ "client_id": "netbird-client",
+ "client_secret": "xxxxx",
+ "issuer": "https://sso.example.com"
+}
+```
+
+The issuer URL must have a valid `/.well-known/openid-configuration` endpoint.
+
+**Response:**
+
+On successful creation, the response includes a `redirect_url` that must be configured in your identity provider:
+
+```json
+{
+ "id": "idp-abc123",
+ "type": "google",
+ "name": "Google Workspace",
+ "client_id": "123456789.apps.googleusercontent.com",
+ "issuer": "",
+ "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
+}
+```
+
+
+**Important:** After creating an identity provider, you must configure the `redirect_url` in your IdP's OAuth application settings. The Dashboard shows a modal with copy functionality after successful creation.
+
+
+**Errors:**
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | `invalid_request` | Missing required fields |
+| 400 | `invalid_type` | Unknown provider type |
+| 403 | `permission_denied` | Insufficient permissions |
+
+### Update Identity Provider
+
+Update an existing identity provider.
+
+```http
+PUT /identity-providers/{id}
+```
+
+**Path Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | string | Identity provider ID |
+
+**Request Body:**
+
+Include only fields you want to update. The `type` cannot be changed.
+
+```json
+{
+ "name": "Updated Name",
+ "client_id": "new-client-id",
+ "client_secret": "new-secret"
+}
+```
+
+
+If `client_secret` is empty or omitted, the existing secret is preserved. The help text in the Dashboard says: "Leave empty to keep the existing secret."
+
+
+**Response:**
+
+```json
+{
+ "id": "idp-abc123",
+ "type": "google",
+ "name": "Updated Name",
+ "client_id": "new-client-id",
+ "issuer": "",
+ "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
+}
+```
+
+### Delete Identity Provider
+
+Remove an identity provider connector.
+
+```http
+DELETE /identity-providers/{id}
+```
+
+**Path Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | string | Identity provider ID |
+
+**Response:**
+
+```
+204 No Content
+```
+
+**Errors:**
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 404 | `not_found` | Identity provider not found |
+| 403 | `permission_denied` | Insufficient permissions |
+
+
+Deleting an identity provider will prevent users who authenticate exclusively through that provider from logging in.
+
+
+---
+
+## Users (Embedded IdP)
+
+When embedded IdP is enabled, the Dashboard shows a **"Create User"** button instead of "Invite User". Created users receive a generated password that is shown only once.
+
+### Create User
+
+Create a new local user. In the Dashboard, after creation, a modal displays the generated password with a copy button and the warning: *"This password will only be shown once. Please copy it now."*
+
+```http
+POST /users
+```
+
+**Request Body:**
+
+```json
+{
+ "email": "user@example.com",
+ "name": "New User",
+ "role": "user",
+ "auto_groups": ["group-id-1", "group-id-2"]
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `email` | string | Yes | User's email address |
+| `name` | string | Yes | Display name |
+| `role` | string | No | Role: `admin`, `user` (default: `user`) |
+| `auto_groups` | string[] | No | Groups to automatically assign |
+
+**Response:**
+
+```json
+{
+ "id": "user-abc123",
+ "email": "user@example.com",
+ "name": "New User",
+ "role": "user",
+ "status": "active",
+ "password": "generated-password-here"
+}
+```
+
+
+The `password` field is only included in the response when creating a user with embedded IdP enabled. It is never returned in subsequent API calls. Store it securely or share it with the user immediately.
+
+
+### User IdP Association
+
+When users authenticate through an external identity provider connector, their user record includes an `idp_id` field linking them to the provider. The Dashboard displays an IdP badge (with the provider's icon) next to the user's name in the Users table.
+
+```json
+{
+ "id": "user-abc123",
+ "email": "user@example.com",
+ "name": "User Name",
+ "role": "user",
+ "status": "active",
+ "idp_id": "idp-def456"
+}
+```
+
+
+This endpoint is only available when embedded IdP is enabled (`account.settings.extra.embedded_idp_enabled: true`). With external IdPs, users are provisioned through the IdP.
+
+
+---
+
+## Error Responses
+
+All error responses follow this format:
+
+```json
+{
+ "error": {
+ "code": "error_code",
+ "message": "Human-readable error message",
+ "details": {}
+ }
+}
+```
+
+### Common Error Codes
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| `invalid_request` | 400 | Request body is malformed or missing required fields |
+| `invalid_config` | 400 | Provider configuration is invalid |
+| `unauthorized` | 401 | Missing or invalid authentication token |
+| `permission_denied` | 403 | Insufficient permissions for this operation |
+| `not_found` | 404 | Requested resource not found |
+| `duplicate` | 409 | Resource already exists |
+| `idp_unavailable` | 503 | Embedded IdP is not enabled or unavailable |
+
+---
+
+## Rate Limits
+
+API requests are subject to rate limiting:
+
+| Endpoint Category | Rate Limit |
+|-------------------|------------|
+| Read operations | 100 requests/minute |
+| Write operations | 20 requests/minute |
+| Onboarding | 5 requests/minute |
+
+Rate limit headers are included in responses:
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1642089600
+```
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/authentik.mdx b/src/pages/selfhosted/identity-providers/authentik.mdx
index 448f6ae82..1291e61b7 100644
--- a/src/pages/selfhosted/identity-providers/authentik.mdx
+++ b/src/pages/selfhosted/identity-providers/authentik.mdx
@@ -1,135 +1,192 @@
import {Note} from "@/components/mdx";
-# Authentik with NetBird Self-Hosted
+# Authentik
-This guide is a part of the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide) and explains how to integrate
-**self-hosted** NetBird with [Authentik](https://goauthentik.io).
+[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.
-
- If you prefer not to self-host an Identity and Access Management solution, then you could use a managed alternative like
- [Auth0](/selfhosted/identity-providers#auth0).
-
+## Connector Setup (Recommended)
-## Step 1: Create OAuth2/OpenID Provider
-In this step, we will create OAuth2/OpenID Provider in Authentik.
+Add Authentik as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments.
-- Navigate to authentik admin interface
-- Click `Applications` on the left menu, then click `Providers`
-- Click `Create` to create new provider
-- Fill in the form with the following values and click `Next`
- - type: `OAuth2/OpenID Provider`
+### Prerequisites
-
-
-
+- NetBird self-hosted with embedded IdP enabled
+- Authentik instance with admin access
+
+### 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**
-- Fill in the form with the following values and click `Finish`
- - Name: `Netbird`
- - Authentication Flow: `default-authentication-flow (Welcome to authentik!)`
- - Authorization Flow: `default-provider-authorization-explicit-consent (Authorize Application)`
- - Protocol Settings:
- - Client type: `Public`
- - Redirect URIs/Origins (RegEx):
- - Regex: `https:///.*`
- - Strict: `http://localhost:53000`
- - Signing Key: Must be selected! Can be any cert present, e.g. `authentik Self-signed Certificate`
- - Advanced protocol settings:
- - Access code validity: `minutes=10`
- - Subject mode: `Based on the User's ID`
-
-Take note of `Client ID`, we will use it later
-
+
-## Step 2: Create external applications
-In this step, we will create external applications in Authentik.
+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 creating the connector in NetBird)
+ - **Signing Key**: Select any cert present, e.g., `authentik Self-signed Certificate`
-- Navigate to authentik admin interface
-- Click `Applications` on the left menu, then click `Applications`
-- Click `Create` to create new application
-- Fill in the form with the following values and click `Create`
- - Name: `Netbird`
- - Slug: `netbird`
- - Provider: `Netbird`
+6. Click **Finish**
+7. Note the **Client ID** and **Client Secret**
+
+### 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
-In this step, we will create service account.
+### Step 3: Add Connector in NetBird
+
+1. Log in to your NetBird Dashboard
+2. Navigate to **Settings** → **Identity Providers**
+3. Click **Add Identity Provider**
+4. Fill in the fields:
+
+| Field | Value |
+|-------|-------|
+| Type | Generic OIDC |
+| Name | Authentik (or your preferred display name) |
+| Client ID | From Authentik provider |
+| Client Secret | From Authentik provider |
+| Issuer | `https://authentik.example.com/application/o/netbird/` |
+
+5. Click **Save**
+
+### Step 4: Configure Redirect URI
+
+After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Authentik provider:
+
+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
+
+1. Log out of NetBird Dashboard
+2. On the login page, you should see an "Authentik" button
+3. Click it and authenticate with your Authentik credentials
+4. You should be redirected back to NetBird and logged in
+
+---
+
+## Standalone Setup (Advanced)
+
+Use Authentik as your primary identity provider instead of the embedded IdP. This approach gives you full control over identity management but requires more configuration.
+
+
+If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like [Auth0](/selfhosted/identity-providers/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 connector 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`
-- Navigate to authentik admin interface
-- Click `Directory` on the left menu, then click `Users`
-- Click `Create Service Account` to create service account
-- Fill in the form with the following values and click `Create`
- - Username: `Netbird`
- - Create Group: `Disable`
-
-
+
-- Take note of the NetBird service account `username`, we will need it later.
-- N.B. The `password` defined when creating the NetBird service account is not required.
-Users should instead create an app password for the NetBird service account within `Directory > Tokens and App passwords` in authentik's `Admin interface.
-Be sure to select the NetBird Service account object as the `User` when creating the app password.
-Take note of the app password as we will need it later.
+Take note of **Client ID** for later use.
+
+### Step 2: Create Application
+
+Follow step 2 from the connector 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**
-
+
-## Step 4: Add service account to admin group
-In this step, we will add `Netbird` service account to `authentik Admins` group.
+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
-- Navigate to authentik admin interface
-- Click `Directory` on the left menu, then click `Groups`
-- Click `authentik Admins` from list of groups and select `Users` tab at the top
-- Click `Add existing user` and click `+` button to add user
-- Select `Netbird` and click `Add`
-- Disable `Hide service-accounts` and verify if user `Netbird` is added to the 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 a authentication flow for device token authentication
+### Step 5: Create Device Code Flow
-- Navigate to authentik admin interface
-- Click `Flows and Stages` on the left menu, then click `Flows` then `Create`
-- Fill in the form with the following values and click `Create`
- - Name: `default-device-code-flow`
- - Title: `Device Code Flow`
- - Designation: `Stage Configuration`
- - Authentication: `Require authentication`
+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**
-
+
-- Navigate to authentik admin interface
-- Click `System` on the left menu, then click `Brands`
-- Click on the edit button of domain `authentik-default`
-- Under Default flows set Device code flow to `default-device-code-flow`
-- Click `Update`
+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**
-
+
-Your authority OIDC configuration will be available under:
+### Step 6: Configure NetBird
+
+Your authority OIDC configuration will be available at:
```bash
-https://< YOUR_AUTHENTIK_HOST_AND_PORT >/application/o/netbird/.well-known/openid-configuration
+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:
+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
@@ -146,10 +203,38 @@ 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 [here](https://github.com/netbirdio/netbird/issues/3654)
+# Needs disabling due to issue with IdP. Learn more: https://github.com/netbirdio/netbird/issues/3654
NETBIRD_AUTH_PKCE_DISABLE_PROMPT_LOGIN=true
-
```
-## Step 6: Continue with the NetBird Self-hosting Guide
-You've configured all required resources in Authentik. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
\ No newline at end of file
+### 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
+
+### "Invalid redirect URI" error
+
+- Ensure the redirect URI exactly matches what NetBird provides
+- For connector setup: Copy the exact URL from the success modal
+- For standalone: Use regex pattern `https:///.*`
+
+### 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
+
+- [Authentik Documentation](https://goauthentik.io/docs/)
+- [Embedded IdP Overview](/selfhosted/identity-providers/embedded-idp)
+- [API Reference](/selfhosted/identity-providers/api-reference)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/connectors.mdx b/src/pages/selfhosted/identity-providers/connectors.mdx
new file mode 100644
index 000000000..4231da17f
--- /dev/null
+++ b/src/pages/selfhosted/identity-providers/connectors.mdx
@@ -0,0 +1,121 @@
+# Identity Provider Connectors
+
+When using the [embedded IdP](/selfhosted/identity-providers/embedded-idp), you can add identity provider **connectors** to enable Single Sign-On (SSO). This allows users to sign in with their existing accounts from services like Google, Microsoft, or your corporate identity provider—while still maintaining the simplicity of the embedded IdP.
+
+## Why Use Connectors?
+
+Connectors provide:
+
+- **Single Sign-On (SSO)** - Users authenticate with familiar credentials
+- **Federation** - Multiple identity sources, single NetBird account
+- **Flexibility** - Mix local users with SSO authentication
+- **Gradual adoption** - Start with local users, add SSO later
+
+## Supported Providers
+
+| Provider | Type | Best For |
+|----------|------|----------|
+| [**Google**](/selfhosted/identity-providers/google) | `google` | Google Workspace, personal Google accounts |
+| [**Microsoft**](/selfhosted/identity-providers/microsoft) | `microsoft` / `entra` | Personal accounts, Azure AD / Entra ID |
+| [**Okta**](/selfhosted/identity-providers/okta) | `okta` | Enterprise SSO |
+| [**Zitadel**](/selfhosted/identity-providers/zitadel) | `zitadel` | Self-hosted Zitadel |
+| [**Keycloak**](/selfhosted/identity-providers/keycloak) | `oidc` | Self-hosted Keycloak |
+| [**Authentik**](/selfhosted/identity-providers/authentik) | `oidc` | Self-hosted Authentik |
+| [**PocketID**](/selfhosted/identity-providers/pocketid) | `pocketid` | Lightweight self-hosted IdP |
+| [**Generic OIDC**](/selfhosted/identity-providers/generic-oidc) | `oidc` | Any OIDC-compliant provider |
+
+## Adding a Connector
+
+### Via Dashboard
+
+1. Log in to your NetBird Dashboard
+2. Navigate to **Settings** → **Identity Providers**
+3. Click **Add Identity Provider**
+4. Select your provider type and fill in the required fields
+5. Click **Save**
+6. Copy the **Redirect URL** and configure it in your identity provider
+
+
+The Identity Providers tab is only visible when the embedded IdP is enabled.
+
+
+### Via API
+
+```bash
+curl -X POST "https://netbird.example.com/api/identity-providers" \
+ -H "Authorization: Bearer ${TOKEN}" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "type": "oidc",
+ "name": "My SSO Provider",
+ "client_id": "your-client-id",
+ "client_secret": "your-client-secret",
+ "issuer": "https://sso.example.com"
+ }'
+```
+
+See the [API Reference](/selfhosted/identity-providers/api-reference) for complete documentation.
+
+## Common Configuration Fields
+
+All connectors require:
+
+| Field | Description |
+|-------|-------------|
+| **Name** | Display name shown on the login button |
+| **Client ID** | OAuth client identifier from your provider |
+| **Client Secret** | OAuth client secret from your provider |
+
+Some providers also require:
+
+| Field | Required For | Description |
+|-------|--------------|-------------|
+| **Issuer** | Okta, Zitadel, PocketID, OIDC | The OIDC issuer URL |
+
+## How It Works
+
+1. User clicks the provider button on the login page
+2. User is redirected to the identity provider to authenticate
+3. After successful authentication, user is redirected back to NetBird
+4. NetBird validates the token and creates/updates the user account
+5. User is logged in and can access the Dashboard
+
+Users who authenticate via a connector appear in your Users list with a badge showing their identity provider.
+
+## Multiple Connectors
+
+You can configure multiple connectors simultaneously:
+
+- All enabled providers appear as buttons on the login page
+- "Continue with Email" (local authentication) is always available
+- Users can authenticate with any configured provider
+- Each user's provider is tracked and displayed in the Dashboard
+
+## Best Practices
+
+1. **Start simple** - Begin with local users, add connectors as needed
+2. **Test thoroughly** - Verify the connector works before announcing to users
+3. **Communicate changes** - Let users know about new login options
+4. **Keep a fallback** - Local authentication remains available if a connector has issues
+
+## Troubleshooting
+
+### Provider not appearing on login page
+
+- Verify the connector was saved successfully in Settings → Identity Providers
+- Check that the connector is enabled
+- Clear browser cache and reload the login page
+
+### "Invalid redirect URI" error
+
+- Copy the exact Redirect URL from NetBird after creating the connector
+- Ensure no trailing slashes or typos
+- Some providers are case-sensitive
+
+### Authentication succeeds but user not created
+
+- Check Management service logs for errors
+- Verify the token contains required claims (email, name)
+- Ensure the user's email domain is not blocked by any policies
+
+For provider-specific troubleshooting, see the individual provider pages.
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/embedded-idp.mdx b/src/pages/selfhosted/identity-providers/embedded-idp.mdx
new file mode 100644
index 000000000..ac41d177b
--- /dev/null
+++ b/src/pages/selfhosted/identity-providers/embedded-idp.mdx
@@ -0,0 +1,408 @@
+# Embedded Identity Provider
+
+The embedded identity provider is NetBird's built-in authentication system, powered by [Dex](https://dexidp.io/). It runs directly within the Management service, eliminating the need for external IdP containers or complex configuration.
+
+## Overview
+
+The embedded IdP provides:
+
+- **Local user management** - Create users with email/password authentication directly in NetBird
+- **External connector support** - Optionally integrate Google, GitHub, OIDC, or SAML providers
+- **Device authentication** - CLI authentication via device authorization flow
+- **Secure storage** - AES-256-GCM encryption for sensitive user data at rest
+
+## When to Use Embedded IdP
+
+The embedded IdP is ideal for:
+
+| Use Case | Why Embedded IdP Works |
+|----------|----------------------|
+| **Homelabs** | Simple setup, minimal resources, no external dependencies |
+| **Small teams** | Easy user management, quick onboarding |
+| **Proof of concept** | Get started in minutes, upgrade path available |
+| **Air-gapped environments** | No external service dependencies |
+| **Development/testing** | Fast iteration, simple reset |
+
+Consider an [external IdP](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp) if you need:
+
+- SCIM user provisioning (Enterprise feature)
+- Complex user lifecycle management
+- Integration with existing enterprise SSO infrastructure
+- Specific IdP features not available in connectors
+
+## Architecture
+
+With the embedded IdP enabled, the architecture is simplified:
+
+```
+ NetBird Management
+ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐
+ │ Management │ │ Embedded Dex │ │ Dashboard │
+ │ Service │◄─┤ IdP Server │◄─┤ API │
+ └─────────────────┘ └─────────────────┘ └─────────────┘
+ │ │
+ ▼ ▼
+ ┌─────────────────────────────────────────────────────────┐
+ │ SQLite/Postgres Database │
+ │ (Users, Accounts, IdP Connectors) │
+ └─────────────────────────────────────────────────────────┘
+```
+
+Compare this to the external IdP architecture which requires separate containers for the IdP and its database.
+
+## Configuration
+
+### Enabling Embedded IdP
+
+The embedded IdP is enabled by default when using the new `getting-started.sh` quickstart script. For manual configuration, update your `management.json`:
+
+```json
+{
+ "EmbeddedIdP": {
+ "Enabled": true,
+ "DataDir": "/var/lib/netbird/idp"
+ },
+ "EncryptionKey": ""
+}
+```
+
+### Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `EmbeddedIdP.Enabled` | Enable/disable the embedded IdP | `true` (quickstart) |
+| `EmbeddedIdP.DataDir` | Directory for IdP data storage | `/var/lib/netbird/idp` |
+| `EncryptionKey` | Base64-encoded AES-256 key for encrypting user data | Auto-generated |
+
+### Environment Variables
+
+When using docker-compose, you can configure these via environment variables:
+
+```yaml
+environment:
+ - NETBIRD_EMBEDDED_IDP_ENABLED=true
+ - NETBIRD_EMBEDDED_IDP_DATA_DIR=/var/lib/netbird/idp
+ - NETBIRD_ENCRYPTION_KEY=${ENCRYPTION_KEY}
+```
+
+### Generating an Encryption Key
+
+If you need to generate an encryption key manually:
+
+```bash
+openssl rand -base64 32
+```
+
+
+**Warning:** Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures.
+
+
+## User Management
+
+### Creating Users via Dashboard
+
+When embedded IdP is enabled, the Dashboard shows a **"Create User"** button (instead of "Invite User" shown for cloud-hosted NetBird):
+
+1. Navigate to **Team** → **Users**
+2. Click **Create User**
+3. Fill in the user details:
+ - **Email** (required) - User's email address for login
+ - **Name** (required) - Display name
+ - **Groups** (optional) - Auto-assign to groups
+4. Click **Create**
+
+After creation, a modal displays with:
+- The **generated password** with a copy button
+- Warning: *"This password will only be shown once. Please copy it now."*
+- **Copy & Close** button to copy password and dismiss
+
+
+**Warning:** The generated password is only shown once at creation time. It cannot be retrieved later. Make sure to copy it and share it securely with the user.
+
+
+### User IdP Badges
+
+In the Users table, each user shows a badge indicating their identity provider:
+- Users created locally show no badge (or "Local" badge)
+- Users who authenticated via an external connector show that provider's icon (Google, Microsoft, etc.)
+- The badge links to the `idp_id` field in the user record
+
+### Creating Users via API
+
+```bash
+curl -X POST "https://netbird.example.com/api/users" \
+ -H "Authorization: Bearer ${TOKEN}" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "email": "user@example.com",
+ "name": "New User",
+ "auto_groups": ["group-id-1"]
+ }'
+```
+
+Response includes the generated password:
+
+```json
+{
+ "id": "user-abc123",
+ "email": "user@example.com",
+ "name": "New User",
+ "role": "user",
+ "status": "active",
+ "password": "generated-password-here"
+}
+```
+
+
+The `password` field is only included when creating users with embedded IdP. Store it immediately—it won't be returned in subsequent API calls.
+
+
+### User Roles
+
+Users created through the embedded IdP can be assigned roles:
+
+| Role | Permissions |
+|------|-------------|
+| **Owner** | Full administrative access, cannot be demoted |
+| **Admin** | Manage users, peers, policies, and settings |
+| **User** | Connect devices, view assigned resources |
+
+## Instance Setup (First Run)
+
+When NetBird starts with the embedded IdP and no existing accounts, the Dashboard redirects to the `/setup` route and displays the **Instance Setup Wizard**:
+
+1. The Dashboard checks `GET /instance` for `setup_required: true`
+2. If setup is required, users are redirected to `/setup`
+3. The wizard collects:
+ - **Email address** (required)
+ - **Password** (required, minimum 8 characters)
+ - **Name** (optional)
+4. On submit, the owner account is created via `POST /instance/setup`
+5. User is redirected to login with the credentials they just created
+
+
+The `/setup` route is unauthenticated and only accessible when `setup_required` is true. Once setup is complete, accessing `/setup` returns a 412 error and redirects to login.
+
+
+### Setup API
+
+For automated deployments, you can complete setup via API:
+
+```bash
+# Check if setup is required
+curl "https://netbird.example.com/api/instance"
+
+# Response when setup is needed:
+{
+ "setup_required": true
+}
+
+# Complete setup
+curl -X POST "https://netbird.example.com/api/instance/setup" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "email": "admin@example.com",
+ "password": "securepassword123",
+ "name": "Admin User"
+ }'
+
+# Response:
+{
+ "user_id": "user-abc123",
+ "account_id": "account-xyz789"
+}
+```
+
+## Adding Identity Provider Connectors
+
+The embedded IdP supports adding identity provider [**connectors**](/selfhosted/identity-providers/connectors) to enable SSO. This allows users to sign in with existing accounts from:
+
+- Google
+- Microsoft (personal accounts)
+- Microsoft Entra ID (Azure AD / work accounts)
+- Okta
+- Zitadel
+- PocketID
+- Any OIDC-compliant provider
+
+### Managing Connectors via Dashboard
+
+1. Navigate to **Settings** → **Identity Providers**
+2. Click **Add Identity Provider**
+3. Select your provider type from the dropdown
+4. Configure the required fields:
+ - **Name** - Display name for the login button
+ - **Client ID** - From your identity provider
+ - **Client Secret** - From your identity provider
+ - **Issuer** - Required for Okta, Zitadel, PocketID, and generic OIDC
+5. Click **Save**
+
+After saving, a modal displays the **Redirect URL** that you must configure in your identity provider's OAuth settings. Copy this URL before closing.
+
+
+The Identity Providers tab is only visible when `embedded_idp_enabled` is `true` in your account settings.
+
+
+For detailed setup instructions for each provider, see the individual provider pages:
+- [Google](/selfhosted/identity-providers/google)
+- [Microsoft](/selfhosted/identity-providers/microsoft)
+- [Keycloak](/selfhosted/identity-providers/keycloak)
+- [Zitadel](/selfhosted/identity-providers/zitadel)
+- [All Providers →](/selfhosted/identity-providers)
+
+### Managing Connectors via API
+
+```bash
+# List configured connectors
+curl "https://netbird.example.com/api/identity-providers" \
+ -H "Authorization: Bearer ${TOKEN}"
+
+# Add a Google connector
+curl -X POST "https://netbird.example.com/api/identity-providers" \
+ -H "Authorization: Bearer ${TOKEN}" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "type": "google",
+ "name": "Google Workspace",
+ "client_id": "your-client-id.apps.googleusercontent.com",
+ "client_secret": "your-client-secret"
+ }'
+
+# Response includes redirect_url to configure in Google:
+{
+ "id": "idp-abc123",
+ "type": "google",
+ "name": "Google Workspace",
+ "client_id": "your-client-id.apps.googleusercontent.com",
+ "issuer": "",
+ "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
+}
+
+# Update a connector
+curl -X PUT "https://netbird.example.com/api/identity-providers/{id}" \
+ -H "Authorization: Bearer ${TOKEN}" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Updated Name"
+ }'
+
+# Delete a connector
+curl -X DELETE "https://netbird.example.com/api/identity-providers/{id}" \
+ -H "Authorization: Bearer ${TOKEN}"
+```
+
+## Login Flow
+
+When embedded IdP is enabled with external connectors, the login page displays:
+
+1. **"Continue with Email"** - Local username/password authentication (always shown first)
+2. **External provider buttons** - One for each configured connector
+
+Users can choose their preferred authentication method.
+
+## Data Encryption
+
+The embedded IdP encrypts sensitive user data at rest:
+
+| Field | Encryption |
+|-------|------------|
+| Email | AES-256-GCM |
+| Name | AES-256-GCM |
+| Password | bcrypt hash (via Dex) |
+
+The encryption key is configured in `management.json` and should be:
+
+- Generated using a cryptographically secure random generator
+- Stored securely (not in version control)
+- Included in backup procedures
+- Rotated according to your security policies
+
+## Troubleshooting
+
+### "Embedded IdP not available" error
+
+Ensure `EmbeddedIdP.Enabled` is `true` in `management.json` and the Management service has been restarted.
+
+### Users can't log in
+
+1. Check Management service logs: `docker compose logs management`
+2. Verify the encryption key hasn't changed
+3. Confirm the user exists: Check **Team** → **Users** in Dashboard
+
+### External connector not working
+
+1. Verify Client ID and Secret are correct
+2. Check redirect URIs are properly configured in the external IdP
+3. Review Management logs for OIDC/SAML errors
+
+### Password reset
+
+Use the management CLI:
+
+```bash
+docker compose exec management /go/bin/netbird-mgmt users reset-password \
+ --email user@example.com \
+ --new-password "newpassword123"
+```
+
+## Security Considerations
+
+### Password Requirements
+
+Default password requirements for local users:
+
+- Minimum 8 characters
+- No specific complexity requirements (consider your security policy)
+
+### Session Management
+
+- JWT tokens are issued upon successful authentication
+- Token expiration follows OIDC best practices
+- Device authorization flow available for CLI clients
+
+### Audit Logging
+
+User authentication events are logged in the activity log:
+
+- Login attempts (successful and failed)
+- User creation/deletion
+- Connector configuration changes
+- Password resets
+
+## Comparison with External IdP
+
+| Feature | Embedded IdP | External IdP |
+|---------|--------------|--------------|
+| Setup complexity | Minimal | Moderate to High |
+| Resource requirements | Low (~1GB RAM) | Higher (2-4GB+ RAM) |
+| Additional containers | None | IdP + Database |
+| User management | Dashboard/API | External IdP console |
+| External SSO | Via connectors | Native |
+| SCIM provisioning | Not available | Available (Enterprise) |
+| MFA | Via external connectors | Native IdP feature |
+| Backup complexity | Single database | Multiple databases |
+
+## Disabling Embedded IdP
+
+To switch from embedded IdP to an external IdP:
+
+1. Configure your external IdP following the [Advanced guide](/selfhosted/selfhosted-guide)
+2. Update `management.json`:
+
+ ```json
+ {
+ "EmbeddedIdP": {
+ "Enabled": false
+ },
+ "HttpConfig": {
+ "OIDCConfigEndpoint": "https://your-idp.example.com/.well-known/openid-configuration"
+ }
+ }
+ ```
+
+3. Restart the Management service
+4. Users will need to re-authenticate with the new IdP
+
+
+**Warning:** Disabling the embedded IdP will invalidate all local user accounts. Ensure users have accounts in the external IdP before switching.
+
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/index.mdx b/src/pages/selfhosted/identity-providers/index.mdx
index c383f83bb..bff8ebc28 100644
--- a/src/pages/selfhosted/identity-providers/index.mdx
+++ b/src/pages/selfhosted/identity-providers/index.mdx
@@ -1,90 +1,123 @@
-import { Note, Button } from '@/components/mdx'
-
# Supported Identity Providers (IdPs)
-NetBird’s self-hosted implementation (Community Edition) uses the OpenID Connect (OIDC) protocol for authentication, an
-industry-standard identity layer built on top of OAuth 2.0. OIDC is used both for user authentication to access the
-Management Service Dashboard and for user device authorization when accessing internal resources.
+NetBird's self-hosted implementation uses the OpenID Connect (OIDC) protocol for authentication, an industry-standard identity layer built on top of OAuth 2.0. OIDC is used both for user authentication to access the Management Service Dashboard and for user device authorization when accessing internal resources.
+
+## Embedded IdP (Recommended)
+
+Starting with version X.XX, NetBird includes a **built-in identity provider** powered by [Dex](https://dexidp.io/). This is now the default for new deployments and eliminates the need for separate IdP infrastructure.
+
+With the embedded IdP, you can:
-There are several Identity Provider (IdP) options available for running a self-hosted version of NetBird. This document provides
-an overview of each option along with links to detailed setup guides.
+- **Create local users** directly from the NetBird Dashboard
+- **Add SSO connectors** (Google, Microsoft, Okta, etc.) through the Dashboard UI
+- **Simplify your deployment** with fewer containers and reduced resource requirements
+- **Get started faster** with automatic configuration and no additional setup
- In addition to OIDC-based authentication, NetBird supports provisioning users and groups through SCIM and the API.
- However, this functionality is not available in the open source Community Edition. It is offered only in the cloud-managed
- version of NetBird or through a [Commercial License](https://netbird.io/pricing#on-prem) for enterprise self-hosted deployments.
+The embedded IdP uses [Dex](https://dexidp.io/), a lightweight, portable OIDC identity provider that supports federated authentication. Dex runs embedded within the NetBird Management service, requiring no additional containers or databases.
-## Our Approach
+[Get Started →](/selfhosted/selfhosted-quickstart)
-When a user attempts to access the NetBird network, the Management Service redirects them to your configured Identity Provider for authentication. After successful authentication, the IdP issues a JSON Web Token (JWT) that contains the user's identity and claims. NetBird's Management Service validates this token and uses it to authenticate the user without ever storing passwords or sensitive credentials.
+## How Authentication Works
-This approach provides several key benefits: it leverages your existing identity infrastructure, enables Single Sign-On (SSO) across your organization, maintains security through token-based authentication, and allows NetBird to cache user information like names and email addresses without storing sensitive data.
+When a user attempts to access the NetBird network, the Management Service handles authentication through the configured identity provider. After successful authentication, a JSON Web Token (JWT) is issued containing the user's identity and claims. NetBird's Management Service validates this token and uses it to authenticate the user without ever storing passwords or sensitive credentials.
-## Self-hosted IdPs
+This approach provides several key benefits:
-Self-hosted Identity Providers give you full control over authentication and authorization of your NetBird network. You manage and maintain the IdP infrastructure yourself.
+- **Simplified setup** with the embedded IdP—no separate infrastructure required
+- **Flexibility to integrate** with your existing identity infrastructure
+- **Single Sign-On (SSO)** across your organization through connectors
+- **Security through token-based authentication**
+- **Privacy-conscious caching** of user information without storing sensitive data
-### Zitadel
+## Choosing Your Authentication Approach
-[Zitadel](https://github.com/zitadel/zitadel) 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 offers features such as passkeys (FIDO2), OTP, SCIM 2.0 server, and unlimited audit trails.
+| Approach | Best For | Setup Complexity |
+|----------|----------|------------------|
+| **Embedded IdP Only** | Homelabs, small teams, quick deployments | Minimal |
+| **Embedded IdP + Connectors** | Organizations wanting SSO with existing providers | Low |
+| **Standalone IdP (Advanced)** | Enterprises with existing IdP investments, SCIM requirements | Moderate to High |
-
+### Embedded IdP Only
-### Authentik
+The simplest approach—create and manage users directly in NetBird:
-[Authentik](https://github.com/goauthentik/authentik) 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. Authentik includes audit logging, password policies, and full API access for automation.
+- Local username/password authentication
+- No additional services required
+- User management through the Dashboard
+- Ideal for homelabs, small teams, and proof-of-concept deployments
-
+[Setup Guide →](/selfhosted/identity-providers/embedded-idp)
-### Keycloak
+### Embedded IdP with Connectors
-[Keycloak](https://github.com/keycloak/keycloak) is an open-source Identity and Access Management solution aimed at modern applications and services. It's one of the most popular self-hosted IdP solutions with extensive documentation and community support. Keycloak provides single sign-on, social login, user federation, fine-grained authorization, and supports OpenID Connect, OAuth 2.0, and SAML 2.0 protocols.
+Combine the simplicity of embedded IdP with your existing identity providers:
-
+- Keep local user management as a fallback
+- Add Google, Microsoft, Okta, or other SSO for convenience
+- Configure connectors directly from the Dashboard UI
+- Best of both worlds
-### PocketID
+[About Connectors →](/selfhosted/identity-providers/connectors)
-[PocketID](https://pocket-id.org/) is a simplified identity management solution designed for self-hosted environments. It provides authentication and authorization services with a focus on security and effectiveness, making it a lightweight and easy-to-deploy option for organizations seeking a straightforward identity management solution.
+### Standalone IdP (Advanced)
-
+For organizations with specific requirements or existing IdP investments:
-## Managed IdPs
+- Full control over identity infrastructure
+- Required for SCIM provisioning (Enterprise)
+- Complex user lifecycle management needs
+- Separate IdP container deployment
-Managed Identity Providers are third-party cloud services that handle the infrastructure and maintenance of your identity provider. These are ideal if you don't want to manage an IdP instance yourself.
+[Advanced IdP Setup →](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp)
-### Microsoft Entra ID
+---
-[Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) (formerly Azure AD) is an enterprise identity service that provides single sign-on and multifactor authentication to your applications. It's a managed service that integrates seamlessly with Microsoft's ecosystem, offering conditional access policies, identity protection, and privileged identity management. Ideal for organizations already using Microsoft services.
+## Identity Provider Options
-
+Each provider page includes both **connector setup** (recommended, for use with embedded IdP) and **standalone setup** (advanced) instructions.
-### Okta
+### Self-Hosted Providers
-[Okta](https://www.okta.com/) is a cloud-based identity and access management service designed for enterprise use. It provides single sign-on, multifactor authentication, user management, and lifecycle management capabilities. Okta offers extensive integration options with thousands of pre-built connectors, adaptive authentication, and comprehensive API access management.
+Self-hosted Identity Providers give you full control over authentication and authorization.
-
+| Provider | Description |
+|----------|-------------|
+| [**Zitadel**](/selfhosted/identity-providers/zitadel) | Open-source identity platform with multi-tenancy, passwordless auth, and OIDC/SAML support |
+| [**Keycloak**](/selfhosted/identity-providers/keycloak) | Popular open-source IAM with extensive documentation and community support |
+| [**Authentik**](/selfhosted/identity-providers/authentik) | Flexible open-source IdP with SSO, MFA, and policy management |
+| [**PocketID**](/selfhosted/identity-providers/pocketid) | Lightweight, easy-to-deploy identity solution for self-hosted environments |
-### Google Workspace
+### Cloud/Managed Providers
-[Google Workspace](https://workspace.google.com/) (formerly G Suite) provides identity management through Google's cloud infrastructure. It offers single sign-on capabilities, multi-factor authentication, and seamless integration with Google services. It's an excellent choice for organizations already using Google Workspace for their business operations, providing unified identity across Google and third-party applications.
+Managed Identity Providers handle infrastructure and maintenance for you.
-
+| Provider | Description |
+|----------|-------------|
+| [**Google**](/selfhosted/identity-providers/google) | Google accounts and Google Workspace authentication |
+| [**Microsoft**](/selfhosted/identity-providers/microsoft) | Microsoft personal accounts and Entra ID (Azure AD) for work accounts |
+| [**Okta**](/selfhosted/identity-providers/okta) | Enterprise identity and access management with extensive integrations |
+| [**Auth0**](/selfhosted/identity-providers/auth0) | Flexible authentication service with customization options |
+| [**JumpCloud**](/selfhosted/identity-providers/jumpcloud) | Cloud directory platform with identity and device management |
-### JumpCloud
+---
-[JumpCloud](https://jumpcloud.com/) is a cloud-based directory platform that provides identity, access, and device management in a unified solution. It offers single sign-on, multi-factor authentication, directory services, device management, and network access control. JumpCloud provides a comprehensive approach to managing users, devices, and applications from a single platform.
+## User Provisioning
-
+In addition to OIDC-based authentication, NetBird supports provisioning users and groups through SCIM and the API. However, this functionality is not available in the open source Community Edition. It is offered only in the cloud-managed version of NetBird or through a [Commercial License](https://netbird.io/pricing#on-prem) for enterprise self-hosted deployments.
-### Keycloak (Managed)
+## Migration Guide
-[Keycloak](https://www.keycloak.org/) can also be deployed as a managed service through various cloud providers, providing the same open-source features with the convenience of cloud hosting and management. This option offers the flexibility and features of Keycloak without the operational overhead of self-hosting.
+If you have an existing NetBird deployment using a standalone IdP (like Zitadel from the previous quickstart), you can continue using it. To migrate to the embedded IdP:
-
+1. Export your user list from your current IdP
+2. Deploy the new version with embedded IdP enabled
+3. Recreate users through the Dashboard or API
+4. (Optional) Add your previous IdP as a connector for SSO
-### Auth0
-
-[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's ideal if you don't want to manage an Identity Provider instance on your own. Auth0 offers extensive customization options, developer-friendly APIs, universal login, social identity providers, and advanced security features like anomaly detection and breached password detection.
+
+User data and network configurations are preserved during migration. Only authentication changes—users may need to re-authenticate after the switch.
+
-
\ No newline at end of file
+[Detailed Migration Guide →](/selfhosted/identity-providers/migration)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/keycloak.mdx b/src/pages/selfhosted/identity-providers/keycloak.mdx
index c14748593..16248c335 100644
--- a/src/pages/selfhosted/identity-providers/keycloak.mdx
+++ b/src/pages/selfhosted/identity-providers/keycloak.mdx
@@ -1,265 +1,322 @@
import {Note} from "@/components/mdx";
-# Keycloak with NetBird Self-Hosted
+# Keycloak
-This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate
-**self-hosted** NetBird with [Keycloak](https://www.keycloak.org/).
+[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.
-Keycloak is an open source software product to allow single sign-on with Identity and Access Management aimed at modern applications and services.
+## Connector Setup (Recommended)
-
- If you prefer not to self-host an Identity and Access Management solution, then you could use a managed alternative like
- [Auth0](/selfhosted/identity-providers#auth0).
-
+Add Keycloak as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments.
-The following guide is an adapted version of the original
-[Keycloak on Docker](https://www.keycloak.org/getting-started/getting-started-docker) guide from the official website.
+### Prerequisites
-## Expected Result
+- NetBird self-hosted with embedded IdP enabled
+- Keycloak instance running with SSL
-After completing this guide, you can log in to your self-hosted NetBird Dashboard and add your machines
-to your network using the [Interactive SSO Login feature](/get-started/install#running-net-bird-with-sso-login)
-over Keycloak.
+### Step 1: Create Client 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:
+ - **Client type**: `OpenID Connect`
+ - **Client ID**: `netbird`
+5. Click **Next**
+6. 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 Connector in NetBird
+
+1. Log in to your NetBird Dashboard
+2. Navigate to **Settings** → **Identity Providers**
+3. Click **Add Identity Provider**
+4. Fill in the fields:
-## Step 1: Check your Keycloak Instance
+| Field | Value |
+|-------|-------|
+| Type | Generic OIDC |
+| 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` |
-For this guide, you need a fully configured Keycloak instance running with SSL.
+5. Click **Save**
-We assume that your Keycloak instance is available at **`https://YOUR-KEYCLOAK-HOST-AND_PORT`**.
-Feel free to change the port if you have configured Keycloak with a different one.
+### Step 3: Configure Redirect URI
-Most of the OIDC software requires SSL for production use.
-We encourage you to comply with this requirement to make the world more secure 😊.
+After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Keycloak client:
+
+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**
+
+### Step 4: 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
+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.
+
-## Step 2: Create a realm
+---
-To create a realm you need to:
+## Standalone Setup (Advanced)
-- Open the Keycloak Admin Console
-- Hover the mouse over the dropdown in the top-left corner where it says `Master`, then click on `Create Realm`
-- Fill in the form with the following values:
-- Realm name: `netbird`
-- Click `Create`
+Use Keycloak as your primary identity provider instead of the embedded IdP. This approach gives you full control but requires more configuration.
+
+
+If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like [Auth0](/selfhosted/identity-providers/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 3: Create a user
+### Step 1: Check Your Keycloak Instance
-In this step we will create a NetBird administrator user.
+Ensure your Keycloak instance is available at `https://YOUR-KEYCLOAK-HOST-AND-PORT` with SSL enabled.
-- Open the Keycloak Admin Console
-- Make sure, that the selected realm is `Netbird`
-- Click `Users` (left-hand menu)
-- Click `Create new user`
-- Fill in the form with the following values:
-- Username: `netbird`
-- Click `Create`
+### 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**
-
+
-The user will need an initial password set to be able to log in. To do this:
-- Click `Credentials` tab
-- Click `Set password` button
-- Fill in the password form with a password
-- Set the `Temporary` field to `Off` to prevent having to update password on first login
-- Click `Save`
+### 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**
-
+
-## Step 4: Create a NetBird client
+6. Click **Credentials** tab
+7. Click **Set password**
+8. Fill in the password and set **Temporary** to `Off`
+9. Click **Save**
+
+
+
+
-In this step we will create NetBird application client and register with the Keycloak instance.
+### Step 4: Create NetBird Client
-- Open the Keycloak Admin Console
-- Make sure, that the selected realm is `Netbird`
-- Click `Clients`
-- Click `Create client` button
-- Fill in the form with the following values and click Next:
-- Client Type: `OpenID Connect`
-- Client ID: `netbird-client`
-- Your newly client `netbird-client` will be used later to set `NETBIRD_AUTH_CLIENT_ID` in the `setup.env`
+1. Click **Clients** → **Create client**
+2. Fill in:
+ - **Client Type**: `OpenID Connect`
+ - **Client ID**: `netbird-client`
+3. Click **Next**
-
+
-
-- Check the checkboxes as on the screenshot below and click Save
+4. Enable the authentication options as shown:
-
+
-## Step 5: Adjust NetBird client access settings
+5. Click **Save**
-In this step we will configure NetBird application client access with the NetBird URLs.
+### Step 5: Configure Client Access Settings
-- Open the Keycloak Admin Console
-- Make sure, that the selected realm is `Netbird`
-- Click `Clients`
-- Choose `netbird-client` from the list
-- Go to `Access Settings` section
-- Fill in the fields with the following values:
-- Root URL: `https://YOUR DOMAIN/` (this is the NetBird Dashboard root URL)
-- Valid redirect URIs: `https://YOUR DOMAIN/*` and `http://localhost:53000`
-- Valid post logout redirect URIs: `https://YOUR DOMAIN/*`
-- Web origins: `+`
-- Click `Save`
+1. Go to **Clients** → **netbird-client**
+2. In **Access Settings**, fill in:
+ - **Root URL**: `https://YOUR_DOMAIN/`
+ - **Valid redirect URIs**: `https://YOUR_DOMAIN/*` and `http://localhost:53000`
+ - **Valid post logout redirect URIs**: `https://YOUR_DOMAIN/*`
+ - **Web origins**: `+`
+3. Click **Save**
-
+
-## Step 6: Create a NetBird client scope
-
-In this step, we will create and configure the NetBird client audience for Keycloak to add it to the generated JWT tokens.
+### Step 6: Create Client Scope
-- Open the Keycloak Admin Console
-- Make sure, that the selected realm is `Netbird`
-- Click `Client scopes` (left-hand menu)
-- Click `Create client scope` button
-- Fill in the form with the following values:
-- Name: `api`
-- Type: `Default`
-- Protocol: `OpenID Connect`
-- Click `Save`
+1. Click **Client scopes** (left-hand menu)
+2. Click **Create client scope**
+3. Fill in:
+ - **Name**: `api`
+ - **Type**: `Default`
+ - **Protocol**: `OpenID Connect`
+4. Click **Save**
-
+
-- While in the newly created Client Scope, switch to the `Mappers` tab
-- Click `Configure a new mapper`
-- Choose the `Audience` mapping
+5. Switch to the **Mappers** tab
+6. Click **Configure a new mapper**
+7. Choose **Audience** mapping
-
+
-- Fill in the form with the following values:
-- Name: `Audience for NetBird Management API`
-- Included Client Audience: `netbird-client`
-- Add to access token: `On`
-- Click `Save`
+8. Fill in:
+ - **Name**: `Audience for NetBird Management API`
+ - **Included Client Audience**: `netbird-client`
+ - **Add to access token**: `On`
+9. Click **Save**
-
+
-## Step 7: Add client scope to NetBird client
+### Step 7: Add Client Scope to NetBird Client
-- Open the Keycloak Admin Console
-- Make sure, that the selected realm is `Netbird`
-- Click `Clients`
-- Choose `netbird-client` from the list
-- Switch to `Client scopes` tab
-- Click `Add client scope` button
-- Choose `api`
-- Click `Add` choosing `Default`
-- The value `netbird-client` will be used as audience
+1. Go to **Clients** → **netbird-client**
+2. Switch to **Client scopes** tab
+3. Click **Add client scope**
+4. Choose `api`
+5. Click **Add** choosing `Default`
-
+
-## Step 8: Create a NetBird-Backend client
-
-In this step we will create NetBird backend client and register with the Keycloak instance.
+### Step 8: Create NetBird-Backend Client
-- Open the Keycloak Admin Console
-- Make sure, that the selected realm is `Netbird`
-- Click `Clients`
-- Click `Create client` button
-- Fill in the form with the following values and click Next:
-- Client Type: `OpenID Connect`
-- Client ID: `netbird-backend`
-- Your newly client `netbird-backend` will be used later to set `NETBIRD_IDP_MGMT_CLIENT_ID` in the `setup.env`
+1. Click **Clients** → **Create client**
+2. Fill in:
+ - **Client Type**: `OpenID Connect`
+ - **Client ID**: `netbird-backend`
+3. Click **Next**
-
+
-- Check the checkboxes as on the screenshot below and click Save
+4. Enable authentication as shown:
-
+
-The client will need secret to authenticate. To do this:
-- Click `Credentials` tab
-- Copy `client secret` will be used later to set `NETBIRD_IDP_MGMT_CLIENT_SECRET` in the `setup.env`
+5. Click **Save**
+6. Go to **Credentials** tab
+7. Copy the **Client secret**
-
+
-## Step 9: Add view-users role to netbird-backend
+### Step 9: Add View-Users Role
-- Open the Keycloak Admin Console
-- Make sure, that the selected realm is `Netbird`
-- Click `Clients`
-- Choose `netbird-backend` from the list
-- Switch to `Service accounts roles` tab
-- Click `Assign roles` button
-- Select `Filter by clients` and search for `view-users`
+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`
-
+
-- Check the role checkbox and click assign
+5. Check the role checkbox and click **Assign**
-
+
-Optional
-
-NetBird offers the ability to automatically delete a user from the Keycloak side when the user is deleted from the associated account.
- To enable this functionality, simply include the `--user-delete-from-idp` flag in the management startup command within your Docker Compose configuration. If you choose to enable this feature,
- please ensure that you assign the `manage-users` role to the `netbird-backend` following the steps outlined above.
+**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.
-Your authority OIDC configuration will be available under:
+### 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.
+Double-check if the endpoint returns a JSON response by calling it from your browser.
-- Set properties in the `setup.env` file:
+Set properties in the `setup.env` file:
+
```shell
-NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=`https:///realms/netbird/.well-known/openid-configuration`.
+NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///realms/netbird/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
-NETBIRD_AUTH_CLIENT_ID=`netbird-client`
+NETBIRD_AUTH_CLIENT_ID="netbird-client"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
-NETBIRD_AUTH_AUDIENCE=`netbird-client`
+NETBIRD_AUTH_AUDIENCE="netbird-client"
-NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=`netbird-client`
-NETBIRD_AUTH_DEVICE_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 that your Keycloak instance use HTTPS. Otherwise, the setup won't work.
+Make sure your Keycloak instance uses HTTPS. Otherwise, the setup won't work.
-#### Step 10: Continue with the NetBird Self-hosting Guide
-You've configured all required resources in Keycloak. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
\ No newline at end of file
+### 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 redirect URI" error
+
+- Ensure the redirect URI matches exactly what's configured
+- For connector: Use the exact URL from the NetBird success modal
+- For standalone: Include both `https://YOUR_DOMAIN/*` and `http://localhost:53000`
+
+### "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
+
+- For connector: Users appear after their first successful login
+- For standalone: Verify the backend client has `view-users` role
+
+---
+
+## Related Resources
+
+- [Keycloak Documentation](https://www.keycloak.org/documentation)
+- [Embedded IdP Overview](/selfhosted/identity-providers/embedded-idp)
+- [API Reference](/selfhosted/identity-providers/api-reference)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/auth0.mdx b/src/pages/selfhosted/identity-providers/managed/auth0.mdx
index 23a650829..407b9d462 100644
--- a/src/pages/selfhosted/identity-providers/managed/auth0.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/auth0.mdx
@@ -1,22 +1,83 @@
import {Note} from "@/components/mdx";
-# Auth0 with NetBird Self-Hosted
+# Auth0
-This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate **self-hosted** NetBird with [Auth0](https://auth0.com/).
+[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.
-Auth0 is a flexible, drop-in solution to add authentication and authorization services to your applications.
-It is a 3rd party managed service and can't be self-hosted. Auth0 is the right choice if you don't want to manage an Identity Provider (IDP)
-instance on your own.
+## Connector Setup (Recommended)
+
+Add Auth0 as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments.
+
+### Prerequisites
+
+- NetBird self-hosted with embedded IdP enabled
+- Auth0 account (sign up at https://auth0.com/)
+
+### Step 1: Create Application in Auth0
+
+1. Log in to your Auth0 dashboard at https://manage.auth0.com/
+2. Go to **Applications** → **Applications**
+3. Click **Create Application**
+4. Fill in:
+ - **Name**: `NetBird`
+ - **Application type**: `Regular Web Application`
+5. Click **Create**
+6. Go to **Settings** tab
+7. Note the **Client ID** and **Client Secret**
+8. Note the **Domain** (e.g., `your-tenant.auth0.com`)
+
+### Step 2: Add Connector in NetBird
+
+1. Log in to your NetBird Dashboard
+2. Navigate to **Settings** → **Identity Providers**
+3. Click **Add Identity Provider**
+4. Fill in the fields:
+
+| Field | Value |
+|-------|-------|
+| Type | Generic OIDC |
+| Name | Auth0 (or your preferred display name) |
+| Client ID | From Auth0 application |
+| Client Secret | From Auth0 application |
+| Issuer | `https://your-tenant.auth0.com` |
+
+5. Click **Save**
+
+### Step 3: Configure Redirect URI
+
+After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Auth0 application:
+
+1. Return to Auth0 Dashboard → **Applications** → **NetBird**
+2. Go to **Settings** tab
+3. Under **Allowed Callback URLs**, add the redirect URL from NetBird
+4. Click **Save Changes**
+
+### Step 4: Test the Connection
+
+1. Log out of NetBird Dashboard
+2. On the login page, you should see an "Auth0" button
+3. Click it and authenticate
+4. You should be redirected back to NetBird and logged in
+
+---
+
+## Standalone Setup (Advanced)
+
+Use Auth0 as your primary identity provider instead of the embedded IdP.
- If you prefer to have full control over authentication and authorization of your NetBird network, there are good
- self-hosted alternatives to the managed Auth0 service like [Keycloak](/selfhosted/identity-providers#keycloak).
+If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
-## Step 1: Create Auth0 account
-To create an Auth0 account, sign up at [https://auth0.com](https://auth0.com/).
+### 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`:
-There are multiple properties of the **`setup.env`** file that we will configure in this guide:
- `NETBIRD_AUTH_CLIENT_ID`
- `NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT`
- `NETBIRD_USE_AUTH0`
@@ -27,115 +88,113 @@ There are multiple properties of the **`setup.env`** file that we will configure
- `NETBIRD_IDP_MGMT_CLIENT_SECRET`
- `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE`
-## Step 2: Create and configure Auth0 application
+### Step 1: Create Dashboard Application
-This Auth0 application will be used to authorize access to NetBird Dashboard (Web UI).
+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`
-- Follow the steps in the [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0)
-up until "Install the Auth0 React SDK".
-- Use **`https://YOUR DOMAIN`** and **`http://localhost:53000`** as: `Allowed Callback URLs`,
-- Use **`https://YOUR DOMAIN`** and **`http://localhost`** as: `Allowed Logout URLs`, `Allowed Web Origins`, `Allowed Origins (CORS)`
- Make sure that **`Token Endpoint Authentication Method`** is set to **`None`**.
+Ensure **Token Endpoint Authentication Method** is set to **None**.
-- Use **`Client ID`** to set ```NETBIRD_AUTH_CLIENT_ID``` property in the `setup.env` file.
-- Use **`Domain`** to configure ```NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT``` property in the `setup.env` file like so:
+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
+https:///.well-known/openid-configuration
```
+
- Double-check if the endpoint returns a JSON response by calling it from your browser.
+Double-check if the endpoint returns a JSON response by calling it from your browser.
-#### Step 3: Create and configure Auth0 API
+### Step 2: Create API
-This Auth0 API will be used to access NetBird Management Service API.
+This API is used to access NetBird Management Service.
-- Follow the steps in the [Auth0 Create An API](https://auth0.com/docs/quickstart/backend/golang#create-an-api).
-- Use API **`Identifier`** to set ```NETBIRD_AUTH_AUDIENCE``` property in the `setup.env` file.
-- Set ```NETBIRD_USE_AUTH0``` to `true`in the `setup.env` file.
+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 4: Enable Interactive SSO Login (Optional)
+### Step 3: Enable Interactive SSO Login (Optional)
-The [Interactive SSO Login feature](/get-started/install#running-net-bird-with-sso-login) allows for machine
-authorization with your Identity Provider. This feature can be used as an alternative to [setup keys](/manage/peers/register-machines-using-setup-keys)
-and is optional.
+This enables machine authorization via your Identity Provider as an alternative to [setup keys](/manage/peers/register-machines-using-setup-keys).
-You can enable it by following these steps:
-- Log in to your Auth0 account https://manage.auth0.com/
-- Go to `Applications` (left-hand menu)
-- Click `Create Application` button (top right)
-- Fill in the form with the following values:
- - Name: `Interactive Login`
- - Application type: `Native`
-- Click `Create`
+1. Go to **Applications**
+2. Click **Create Application**
+3. Fill in:
+ - **Name**: `Interactive Login`
+ - **Application type**: `Native`
+4. Click **Create**
-
+
-- Click `Settings` tab
-- Copy **`Client ID`** to `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID` in the `setup.env` file
+5. Click **Settings** tab
+6. Copy **Client ID** to `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID`
-
+
-- Scroll down to the `Advanced Settings` section
-- Enable **`Device Code`**
-- Click `Save Changes`
+7. Scroll to **Advanced Settings**
+8. Enable **Device Code**
+9. Click **Save Changes**
-
+
-## Step 5: Create and configuire Machine to Machine application.
-This application will be used to authorize access to Auth0 Management API.
+### Step 4: Create Machine to Machine Application
+
+This application authorizes access to Auth0 Management API.
-- Log in to your Auth0 account https://manage.auth0.com/
-- Go to `Applications` (left-hand menu)
-- Click `Create Application` button (top right)
-- Fill in the form with the following values:
- - Name: `Netbird API`
- - Application type: `Machine to Machine Applications`
-- Click `Create`
+1. Go to **Applications**
+2. Click **Create Application**
+3. Fill in:
+ - **Name**: `Netbird API`
+ - **Application type**: `Machine to Machine Applications`
+4. Click **Create**
-
+
-- Fill the form with the following values:
- - API: `Auth0 Management API`
- - Permissions: `read:users`, `update:users`, `create:users`, `read:users_app_metadata`, `update:users_app_metadata`, `create:users_app_metadata`
- - Click `Authorize`
+5. Configure:
+ - **API**: `Auth0 Management API`
+ - **Permissions**: `read:users`, `update:users`, `create:users`, `read:users_app_metadata`, `update:users_app_metadata`, `create:users_app_metadata`
+6. Click **Authorize**
-
+
-Optional
-
-NetBird offers the ability to automatically delete a user from the Auth0 side when the user is deleted from the associated account.
-To enable this functionality, include the `--user-delete-from-idp` flag in the management startup command within your Docker Compose configuration. If you choose to enable this feature, please ensure that you assign the `delete:users` permission following the steps outlined above.
+**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.
-- Click `Settings` tab
-- Copy **`Client ID`** to `NETBIRD_IDP_MGMT_CLIENT_ID` in the `setup.env` file
-- Copy **`Client SECRET`** to `NETBIRD_IDP_MGMT_CLIENT_SECRET` in the `setup.env` file
-- Copy **`DOMAIN`** to `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE` in the `setup.env` file
+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/`)
-
+
-- Set properties in the `setup.env` file:
+### 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_CLIENT_ID=""
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api email_verified"
NETBIRD_AUTH_AUDIENCE=""
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
@@ -146,6 +205,39 @@ 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
+
+---
+
+## Related Resources
-## Step 6: Continue with the NetBird Self-hosting Guide
-You've configured all required resources in Auth0. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
\ No newline at end of file
+- [Auth0 Documentation](https://auth0.com/docs/)
+- [Auth0 Dashboard](https://manage.auth0.com/)
+- [Embedded IdP Overview](/selfhosted/identity-providers/embedded-idp)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
index b6da5959d..4ae600512 100644
--- a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
@@ -1,127 +1,237 @@
import {Note} from "@/components/mdx";
-# Google Workspace with NetBird Self-Hosted
+# Google Workspace
-This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate
-**self-hosted** NetBird with [Google Workspace](https://workspace.google.com/).
+Use Google accounts for authentication with NetBird. This supports both personal Google accounts and Google Workspace (formerly G Suite) organizations.
+
+## Connector Setup (Recommended)
+
+Add Google as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments.
+
+### Prerequisites
+
+- NetBird self-hosted with embedded IdP enabled
+- Access to [Google Cloud Console](https://console.cloud.google.com/)
+
+### Step 1: Create OAuth Credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Select or create a project
+3. Navigate to **APIs & Services** → **Credentials**
+4. Click **Create Credentials** → **OAuth client ID**
+5. If prompted, configure the OAuth consent screen first:
+ - Choose **Internal** (for Workspace) or **External** (for any Google account)
+ - Fill in required fields (app name, support email)
+ - Add scopes: `email`, `profile`, `openid`
+ - Save and continue
+6. Back in Credentials, create the OAuth client:
+ - **Application type**: `Web application`
+ - **Name**: `NetBird`
+ - Leave redirect URIs empty for now
+7. Click **Create**
+8. Note the **Client ID** and **Client Secret**
+
+### Step 2: Add Connector in NetBird
+
+1. Log in to your NetBird Dashboard
+2. Navigate to **Settings** → **Identity Providers**
+3. Click **Add Identity Provider**
+4. Fill in the fields:
+
+| Field | Value |
+|-------|-------|
+| Type | Google |
+| Name | Google (or your preferred display name) |
+| Client ID | From Google Cloud Console |
+| Client Secret | From Google Cloud Console |
-Beginning with NetBird version v0.23.6 and onwards, the Google Workspace IdP manager no longer requires the creation of a custom admin role called `User and Schema Management`.
-Instead, we are transitioning towards a more tailored role explicitly designed for managing read-only user information.
-Consequently, you have the option to remove the previously established custom admin role and refer to the documentation to configure the admin role scope for read-only access correctly.
+Google connectors don't require an Issuer field—it's determined automatically.
-Before you start creating and configuring an Google Workspace application, ensure that you have the following:
-- An Google Workspace account: To create an Google Work application, you must have an Google Workspace. If you don't have one, sign up at https://workspace.google.com/business/signup/welcome.
-- User account with admin permissions: You must have an Google Workspace user account with the admin permissions to create and manage Google Workspace applications. If you don't have the required permissions, ask your workspace administrator to grant them to you.
-- Create new `Netbird` project in Google cloud console https://console.cloud.google.com.
-- Enable `Admin SDK API` for `Netbird` project at https://console.cloud.google.com/apis/library/admin.googleapis.com.
+5. Click **Save**
+
+### Step 3: Configure Redirect URI
+
+After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Google OAuth client:
+
+1. Return to Google Cloud Console → **Credentials**
+2. Click on your OAuth client
+3. Under **Authorized redirect URIs**, click **Add URI**
+4. Paste the redirect URL from NetBird
+5. Click **Save**
+
+### Step 4: Test the Connection
+
+1. Log out of NetBird Dashboard
+2. On the login page, you should see a "Google" button
+3. Click it and sign in with your Google account
+4. You should be redirected back to NetBird and logged in
+
+### Restricting to Google Workspace Domains
+
+To limit authentication to specific Google Workspace domains:
+
+1. Go to **APIs & Services** → **OAuth consent screen**
+2. Under **User type**, select **Internal** (Workspace only)
+3. For external apps, verify your domain to restrict access
+
+
+Domain restrictions are configured in Google Cloud Console, not in NetBird.
+
+
+---
+
+## Standalone Setup (Advanced)
+
+Use Google Workspace as your primary identity provider instead of the embedded IdP. This enables full user management integration with Google Workspace.
+
+
+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**
-## Step 1: Configure OAuth consent screen
-- Navigate to [OAuth consent](https://console.cloud.google.com/apis/credentials/consent) page
-- Select `Internal` User Type and click create
-
+
-- Fill in the form with the following values and click `SAVE AND CONTINUE`
- - App name: `Netbird`
- - User support email: ``
- - Authorized domain: ``
- - Developer contact information: ``
-- Click `ADD OR REMOVE SCOPES`
-- Select `/auth/userinfo.email`, `/auth/userinfo.profile` and `openid` scopes and then click `UPDATE`
+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**
+
-
+
-- Click `SAVE AND CONTINUE`
-- Verify the summary of the OAuth consent screen to ensure that everything is properly configured, and then click `BACK TO DASHBOARD`
+
+8. Click **SAVE AND CONTINUE**
+9. Review the summary and click **BACK TO DASHBOARD**
+
-
+
-## Step 2: Create OAuth 2.0 credentials
-- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page
-- Click `CREATE CREDENTIALS` at the top and select `OAuth client ID`
-- Fill in the form with the following values and click `CREATE`
- - Application type: `Web application`
- - Name: `netbird`
- - Authorized JavaScript origins: `https://` and `http://localhost`
- - Authorized redirect URIs: `https:///auth`, `https:///silent-auth` and `http://localhost:53000`
+### Step 2: Create OAuth 2.0 Credentials
+
+1. Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials)
+2. Click **CREATE CREDENTIALS** → **OAuth client ID**
+3. Fill in:
+ - **Application type**: `Web application`
+ - **Name**: `netbird`
+ - **Authorized JavaScript origins**: `https://` and `http://localhost`
+ - **Authorized redirect URIs**:
+ - `https:///auth`
+ - `https:///silent-auth`
+ - `http://localhost:53000`
+4. Click **CREATE**
+
-
+
-- Take note of `Client ID` and `Client Secret` and click `OK`
+
+5. Note **Client ID** and **Client Secret**
+
-
+
-## Step 3: Create service account
-- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page
-- Click `CREATE CREDENTIALS` at the top and select `Service account`
-- Fill in the form with the following values and click `CREATE`
- - Service account name: `netbird`
- - Service account ID: `netbird`
-- Take note of service account email address, we will use it later
-- Click `DONE`
+### 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
-- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page
-- Under `Service Accounts` click the `netbird` to edit the service account
+### 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
+
-
+
-- Click the `Keys` tab
-- Click the `Add key` drop-down menu, then select `Create new key`
-- Select `JSON` as the Key type and click `Create`
+
+3. Click the **Keys** tab
+4. Click **Add key** → **Create new key**
+5. Select **JSON** and click **Create**
-When you create a service account key by using the Google Cloud console, most browsers immediately download the new key and save it in a download folder on your computer.
-Read how to manage and secure your service keys [here](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys#temp-locations)
+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).
-- Open downloaded json file and take note of `client_id` will be used later as `Service Account Client ID`
+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**
-## Step 5: Grant user management admin role to service account
-- Navigate to [Admin Console](https://admin.google.com/ac/home) page
-- Select `Account` on the left menu and then click `Admin Roles`
-- Click `Create new role`
-- Fill in the form with the following values and click `CREATE`
- - name: `User Management ReadOnly`
- - description: `User Management ReadOnly`
-- Click `CONTINUE`
-
+
-- Scroll down to `Admin API privileges` and add the following privileges
- - Users: `Read`
-- Click `CONTINUE`
+6. Scroll to **Admin API privileges** and add:
+ - **Users**: `Read`
+7. Click **CONTINUE**
+
-
+
-- Verify preview of assigned Admin API privileges to ensure that everything is properly configured, and then click `CREATE ROLE`
-- Click `Assign service accounts`, add service account email address and then click `ADD`
+
+8. Click **CREATE ROLE**
+9. Click **Assign service accounts**
+10. Add the service account email address
+11. Click **ADD** then **ASSIGN ROLE**
+
-
+
-- Click `ASSIGN ROLE` to assign service account to `User Management ReadOnly` role
+
-
+
-- Navigate to [Account Settings](https://admin.google.com/ac/accountsettings/profile?hl=en_US) page and take note of `Customer ID`
+12. Navigate to [Account Settings](https://admin.google.com/ac/accountsettings/profile) and note the **Customer ID**
-- Encode service account json key into base64 format
- ```sh
- base64 -i
- ```
+### Step 6: Encode Service Account Key
+
+```bash
+base64 -i
+```
-- Set properties in the `setup.env` file:
-```json
+### 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
@@ -141,5 +251,42 @@ NETBIRD_IDP_MGMT_EXTRA_SERVICE_ACCOUNT_KEY=""
NETBIRD_IDP_MGMT_EXTRA_CUSTOMER_ID=""
```
-## Step 6: Continue with the NetBird Self-hosting Guide
-You've configured all required resources in Google Workspace. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).
\ No newline at end of file
+### 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
+
+---
+
+## 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/embedded-idp)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx b/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
index 9d2b324d4..9ab8359e1 100644
--- a/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
@@ -1,105 +1,202 @@
import {Note} from "@/components/mdx";
-# JumpCloud with NetBird Self-Hosted
+# JumpCloud
-This guide is a part of the [NetBird Self-hosting Guide](/getting-started/self-hosting) and explains how to integrate
-**self-hosted** NetBird with [JumpCloud](https://jumpcloud.com/).
+[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.
-Before you start creating and configuring an JumpCloud application, ensure that you have the following:
-- An JumpCloud account: To create application, you must have an JumpCloud account. If you don't have one, sign up at https://jumpcloud.com/.
-- User account with admin permissions: You must have an JumpCloud account with the admin permissions. If you don't have the required permissions, ask your administrator to grant them to you.
+## Connector Setup (Recommended)
+Add JumpCloud as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments.
-## Step 1: Create and configure SSO application
+### Prerequisites
+
+- NetBird self-hosted with embedded IdP enabled
+- JumpCloud account with admin permissions
+
+### Step 1: Create OIDC Application in JumpCloud
+
+1. Navigate to [JumpCloud Admin Portal](https://console.jumpcloud.com/)
+2. Click **SSO Applications** under **USER AUTHENTICATION**
+3. Click **Add New Application** → **Custom Application**
+4. Confirm **Custom application** and click **Next**
+5. Select **Manage Single Sign-On (SSO)** and check **Configure SSO with OIDC**
+6. Click **Next**
+7. Enter **Display Label**: `NetBird`
+8. Click **Next**
+9. Review and click **Configure Application**
+10. On the **SSO** tab, configure:
+ - **Client Authentication Type**: `Confidential`
+ - Leave redirect URIs empty for now
+11. Click **Activate**
+12. Note the **Client ID** and **Client Secret**
+
+### Step 2: Add Connector in NetBird
+
+1. Log in to your NetBird Dashboard
+2. Navigate to **Settings** → **Identity Providers**
+3. Click **Add Identity Provider**
+4. Fill in the fields:
+
+| Field | Value |
+|-------|-------|
+| Type | Generic OIDC |
+| Name | JumpCloud (or your preferred display name) |
+| Client ID | From JumpCloud |
+| Client Secret | From JumpCloud |
+| Issuer | `https://oauth.id.jumpcloud.com` |
+
+5. Click **Save**
+
+### Step 3: Configure Redirect URI
+
+After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your JumpCloud application:
+
+1. Return to JumpCloud Admin → **SSO Applications** → **NetBird**
+2. Click the **SSO** tab
+3. Under **Redirect URIs**, add the redirect URL from NetBird
+4. Click **Save**
+
+### Step 4: Assign User Groups
+
+1. Click the **User Groups** tab
+2. Select the user groups that can access NetBird
+3. Click **Save**
+
+### Step 5: Test the Connection
+
+1. Log out of NetBird Dashboard
+2. On the login page, you should see a "JumpCloud" button
+3. Click it and authenticate with your JumpCloud credentials
+4. You should be redirected back to NetBird and logged in
+
+---
+
+## Standalone Setup (Advanced)
+
+Use JumpCloud as your primary identity provider instead of the embedded IdP.
+
+### 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**
-- Navigate to to [Admin Portal](https://console.jumpcloud.com/) page
-- Click `SSO Applications` on the left menu under `USER AUTHENTICATION` section
-- Click `Add New Application` and select `Custom Application`
-
+
-- On the `Which application would you like to integrate` screen, confirm that you've selected `Custom application` and click `Next`
+
+4. Confirm **Custom application** selected and click **Next**
+
-
+
-- On the `Select the features you would like to enable` screen, select `Manage Single Sign-On (SSO)` and check `Configure SSO with OIDC` and click `Next`
+
+5. Select **Manage Single Sign-On (SSO)** and check **Configure SSO with OIDC**
+6. Click **Next**
+
-
+
-- On the `Enter General info` screen, add `NetBird` as `Display Label` and click `Next`
+
+7. Enter **Display Label**: `NetBird`
+8. Click **Next**
+
-
+
-- On the confirmation screen, review the information and click on `Configure Application` to proceed
+
+9. Review and click **Configure Application**
+
-
+
-- On the `New Application` screen, click on the SSO tab and enter the following values:
- - Under `Endpoint Configuration` section:
- - Redirect URIs: `https:///silent-auth`, `https:///auth` and `http://localhost:53000`
- - Client Authentication Type: `Public (None PKCE)`
- - Login URL: `https://`
+
+10. On the **SSO** tab, configure:
+ - **Redirect URIs**:
+ - `https:///silent-auth`
+ - `https:///auth`
+ - `http://localhost:53000`
+ - **Client Authentication Type**: `Public (None PKCE)`
+ - **Login URL**: `https://`
-
+
- - Under `Attribute Mapping (optional)` section:
- - Standard Scopes: `Email`, `Profile`
+
+11. Under **Attribute Mapping (optional)**:
+ - **Standard Scopes**: `Email`, `Profile`
+
-
+
-- Click on the `User Groups` tab and select the user groups that can access this application
+
+12. Click **User Groups** tab and select groups that can access the application
+
-
+
-- Click `Activate`
+
+13. Click **Activate**
+
-
+
-- Take note of `Client ID`, will be used later
-
-## Step 2: Create an account administrator for integration
-The NetBird management system requires an API token to get user information from JumpCloud. This API is bound to an administrator user configured in JumpCloud's admin portal.
-
-The following steps will assume that you are creating a new account. If you already have a user for this purpose, confirm it has the required role described below and skip to Step 3 in this guide.
-- Navigate to to [Admin Portal](https://console.jumpcloud.com/) page
-- Go to account `Settings` and click on the add button (+)
-- On the `Create New Administrator` window, enter the following values:
- - First Name: `NetBird`
- - Last Name: `Integration`
- - Administrator Email: `netbird-user@` # this email will be used to receive the login instructions
- - Role: `Read Only`
- - Click `Save`
-
- Optional
- NetBird offers the ability to automatically delete a user from the JumpCloud side when the user is deleted from the associated account.
- To enable this functionality, simply include the `--user-delete-from-idp` flag in the management startup command within your Docker Compose configuration. If you choose to enable this feature,
- please ensure that you assign the `Help Desk` role to the `NetBird Integration` user following the steps outlined above.
+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**
+
-
+
-After following the steps above, you will receive the login instructions for the newly created user in the email configured. Please follow the instructions to set a password for the user.
+
+**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
-## Step 3: Generate api token
-In this step, we will generate netbird api token in jumpcloud for authorizing calls to user api.
+1. Log in to [Admin Portal](https://console.jumpcloud.com/) with the integration user
+2. Click the account initials (top-right) → **My API Key**
-- Navigate to to [Admin Portal](https://console.jumpcloud.com/) page
-- Login with the user created in the previous step or with an existing user
-- Click on the account initials displayed at the top-right and select `My API Key` from the drop-down
-
+
-- If there is no API key generated, click on `Generate New API Key` button
-- Take note of your api token displayed
+
+3. If no key exists, click **Generate New API Key**
+4. Copy the API token
+
-
+
-- Set properties in the `setup.env` file:
-```json
+### 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
@@ -117,5 +214,39 @@ NETBIRD_MGMT_IDP="jumpcloud"
NETBIRD_IDP_MGMT_EXTRA_API_TOKEN=""
```
-## Step 4: Continue with the NetBird Self-hosting Guide
-You've configured all required resources in JumpCloud. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-5-run-configuration-script).
+### 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
+
+### "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"`
+
+---
+
+## Related Resources
+
+- [JumpCloud Documentation](https://jumpcloud.com/support)
+- [JumpCloud Admin Console](https://console.jumpcloud.com/)
+- [Embedded IdP Overview](/selfhosted/identity-providers/embedded-idp)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx b/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
index 2dcd61533..c2c5729eb 100644
--- a/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
@@ -1,133 +1,222 @@
import {Note} from "@/components/mdx";
-# Microsoft Entra ID with NetBird Self-Hosted
+# Microsoft Entra ID
-This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate **self-hosted** NetBird with [Azure AD](https://azure.microsoft.com/en-us/products/active-directory/).
+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.
-Azure AD is a an enterprise identity service that provides single sign-on and multifactor authentication to your applications.
-It is a 3rd party managed service and can't be self-hosted.
+## Connector Setup (Recommended)
+
+Add Microsoft as a connector to the embedded IdP. Choose the appropriate connector type based on your needs:
+
+| Connector Type | Use Case |
+|---------------|----------|
+| **Microsoft** (`microsoft`) | Personal Microsoft accounts |
+| **Microsoft Entra ID** (`entra`) | Work/school accounts via Azure AD |
+
+### Prerequisites
+
+- NetBird self-hosted with embedded IdP enabled
+- Access to [Azure Portal](https://portal.azure.com/) or [Entra Admin Center](https://entra.microsoft.com/)
+
+### Step 1: Create App Registration
+
+1. Navigate to [Azure Portal](https://portal.azure.com/) → **Azure Active Directory** (or [Entra Admin Center](https://entra.microsoft.com/))
+2. Click **App registrations** → **New registration**
+3. Fill in:
+ - **Name**: `NetBird`
+ - **Supported account types**: Choose based on your needs:
+ - *Personal accounts only*: `Personal Microsoft accounts only`
+ - *Work/school only*: `Accounts in this organizational directory only`
+ - *Both*: `Accounts in any organizational directory and personal Microsoft accounts`
+ - **Redirect URI**: Leave empty for now
+4. Click **Register**
+5. Note the **Application (client) ID** and **Directory (tenant) ID**
+
+### Step 2: Create Client Secret
+
+1. Go to **Certificates & secrets**
+2. Click **New client secret**
+3. Add a description and expiration
+4. Click **Add**
+5. Copy the **Value** immediately (it won't be shown again)
+
+### Step 3: Add Connector in NetBird
+
+1. Log in to your NetBird Dashboard
+2. Navigate to **Settings** → **Identity Providers**
+3. Click **Add Identity Provider**
+4. Fill in the fields:
+
+**For Personal Microsoft Accounts:**
+
+| Field | Value |
+|-------|-------|
+| Type | Microsoft |
+| Name | Microsoft (or your preferred display name) |
+| Client ID | Application (client) ID from Azure |
+| Client Secret | Secret value from Azure |
+
+**For Microsoft Entra ID (Work/School):**
+
+| Field | Value |
+|-------|-------|
+| Type | Microsoft Entra ID |
+| Name | Microsoft Work (or your preferred display name) |
+| Client ID | Application (client) ID from Azure |
+| Client Secret | Secret value from Azure |
+| Tenant ID | Directory (tenant) ID from Azure |
+
+5. Click **Save**
+
+### Step 4: Configure Redirect URI
+
+After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Azure app:
+
+1. Return to Azure Portal → Your app registration
+2. Go to **Authentication**
+3. Click **Add a platform** → **Single-page application**
+4. Add the redirect URL from NetBird
+5. Click **Configure**
+
+### Step 5: Test the Connection
+
+1. Log out of NetBird Dashboard
+2. On the login page, you should see the Microsoft button
+3. Click it and sign in with your Microsoft account
+4. You should be redirected back to NetBird and logged in
+
+---
+
+## Standalone Setup (Advanced)
+
+Use Microsoft Entra ID as your primary identity provider instead of the embedded IdP.
- If you prefer to have full control over authentication and authorization of your NetBird network, there are good
- self-hosted alternatives to the managed Auth0 service like [Keycloak](/selfhosted/identity-providers#keycloak).
+If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
-Before you start creating and configuring an Azure AD application, ensure that you have the following:
-- An Azure account: To create an Azure AD application, you must have an Azure account. If you don't have one, sign up for a free account at https://azure.microsoft.com/free/.
+### Prerequisites
-- User account with appropriate permissions: You must have an Azure AD user account with the appropriate permissions to create and manage Azure AD applications. If you don't have the required permissions, ask your Azure AD administrator to grant them to you.
+- An Azure account with appropriate permissions
+- Docker and Docker Compose for NetBird
+### Step 1: Create and Configure Azure AD Application
-## Step 1. Create and configure Azure AD application
-In this step, we will create and configure NetBird application in azure AD.
-- Navigate to [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)
-- Click `App Registrations` in the left menu then click on the `+ New registration` button to create a new application.
-- Fill in the form with the following values and click Register
- - Name: `Netbird`
- - Account Types: `Accounts in this organizational directory only (Default Directory only - Single tenant)`
- - Redirect URI: select `Single-page application (SPA)` and URI as `https:///silent-auth`
+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 (Single tenant)`
+ - **Redirect URI**: Select `Single-page application (SPA)` and enter `https:///silent-auth`
+4. Click **Register**
-
+
-#### Step 2. Platform configurations
-- Click `Authentication` on the left side menu
-- Under the `Single-page application` Section, add another URI `https:///auth`
+### Step 2: Configure Platform Settings
+
+1. Click **Authentication** on the left menu
+2. Under **Single-page application**, add another URI: `https:///auth`
-
+
-- Scroll down and setup other options as on the screenshot below and click Save
+3. Scroll down and configure options as shown:
-
+
-- Click `Add a Platform` and select `Mobile and desktop applications`
-- Fill in the form with the following values and click Configure
- - Custom redirect URIs: `http://localhost:53000`
-
-
-
+4. Click **Add a Platform** → **Mobile and desktop applications**
+5. Add custom redirect URI: `http://localhost:53000`
+6. Click **Configure**
-## Step 3. Create a NetBird application scope
-- Click `Expose an API` on the left menu
-- Under `Application ID URI` click `Set` and then `Save`
-- Click `+ Add a Scope`
-- Fill in the form with the following values and click `Add scope`
-- Scope name: `api`
+### 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**
-
+
-- Under `Authorized client Applications`, click on `+ add a client application` and enter the following:
-- Fill in the form with the following values and click `Add application`
-- Client ID: same as your Application ID URI minus the `api://`
+6. Under **Authorized client applications**, click **+ Add a client application**
+7. Enter your **Client ID** (same as Application ID URI minus `api://`)
+8. Click **Add application**
-
+
+### Step 4: Add API Permissions
-## Step 4. Add API permissions
-Add `Netbird` permissions
-
-- Click `API permissions` on the left menu
-- Click `Add a permission`
-- Click `My APIs` tab, and select `Netbird`. Next check `api` permission checkbox and click `Add 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**
-
+
-Add `Delegated permissions` to Microsoft Graph
-
-- Click `Add a permission`
-- Click `Microsoft Graph` and then click `Application permissions` tab
-- In `Select permissions` search for `User.Read` and under the `User` section select `User.Read.All` and click `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**
-
+
-
-- Click `Grant admin consent for Default Directory` and click `Yes`
+8. Click **Grant admin consent for Default Directory** → **Yes**
-
+
-## Step 5. Update token version
-- Click `Manifest` on left menu
-- Search for `accessTokenAcceptedVersion` and change the value from `null` to `2`
-- Click `Save`
+### Step 5: Update Token Version
-## Step 6. Generate client secret
-- Click `Certificates & secrets` on left menu
-- Click `New client secret`
-- Fill in the form with the following values and click `Add`
-- Description: `Netbird`
-- Copy `Value` and save it as it can be viewed only once after creation.
+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
-
+
-- Click `Overview` on left menu and take note of `Application (client) ID`, `Object ID` and `Directory (tenant) ID`
-will be required in next step.
+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:
-Your authority OIDC configuration will be available under:
```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.
+Double-check if the endpoint returns a JSON response by calling it from your browser.
-- Set properties in the `setup.env` file:
+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"
@@ -147,8 +236,43 @@ NETBIRD_IDP_MGMT_CLIENT_ID=""
NETBIRD_IDP_MGMT_CLIENT_SECRET=""
NETBIRD_IDP_MGMT_EXTRA_OBJECT_ID="
Where you have the following types: `host` (local address), `srflx` (STUN reflexive address), `relay`
(TURN relay address). If `srflx` and `relay` are not present then the TURN server is not working or not accessible and you should review the required ports in the [requirements section](/selfhosted/selfhosted-guide#requirements).
+
+## Dashboard Issues
+
+### Dashboard shows blank page
+
+**Problem**: The Dashboard loads but shows a blank page or errors.
+
+**Solutions**:
+1. Check browser console for JavaScript errors (F12 → Console)
+2. Verify the Dashboard can reach the Management API
+3. Check CORS configuration if running behind a custom reverse proxy
+4. Clear browser cache and try again
+
+### "Unauthorized" or "403" errors
+
+**Problem**: API calls return unauthorized or forbidden errors.
+
+**Solutions**:
+1. Verify your authentication token is valid
+2. Check that the user has appropriate permissions
+3. For API access, ensure you're using a valid Personal Access Token (PAT)
+4. Review Management service logs for detailed error information
+
+## Certificate Issues
+
+### Let's Encrypt certificate not renewing
+
+**Problem**: SSL certificate expires and doesn't auto-renew.
+
+**Solutions**:
+1. Ensure port 80 is accessible for ACME challenge
+2. Check Caddy logs: `docker compose logs caddy`
+3. Verify the domain points to the correct IP
+4. Manually trigger renewal: `docker compose exec caddy caddy reload`
+
+### Certificate errors with custom reverse proxy
+
+**Problem**: SSL errors when using your own reverse proxy.
+
+**Solutions**:
+1. Ensure your reverse proxy terminates SSL correctly
+2. Set `NETBIRD_DISABLE_LETSENCRYPT=true` in your configuration
+3. Configure proper headers (X-Forwarded-For, X-Forwarded-Proto)
+4. Verify HTTP/2 support is enabled for gRPC endpoints
+
+## Connection Issues
+
+### Peers can't connect to each other
+
+**Problem**: Peers are registered but can't establish connections.
+
+**Solutions**:
+1. Check that UDP port 3478 is accessible (STUN/TURN)
+2. Verify the TURN server is working (see [TURN debugging](#debugging-turn-connections))
+3. Check firewall rules on both peers
+4. Review peer logs: `netbird status -d`
+
+### Management service unreachable
+
+**Problem**: Clients can't connect to the Management service.
+
+**Solutions**:
+1. Verify port 443 is accessible
+2. Check DNS resolution for your domain
+3. Review Management logs: `docker compose logs management`
+4. Test with curl: `curl -v https://your-domain.com/api/health`
+
+## Database Issues
+
+### Management service won't start after upgrade
+
+**Problem**: After upgrading, the Management service fails to start.
+
+**Solutions**:
+1. Check logs for migration errors: `docker compose logs management`
+2. Ensure you followed the [upgrade path](/selfhosted/selfhosted-quickstart#upgrade) for your version
+3. Restore from backup if needed
+4. For major version jumps, you may need intermediate upgrades
+
+### Data corruption after power loss
+
+**Problem**: Services don't start properly after unexpected shutdown.
+
+**Solutions**:
+1. Check for database lock files
+2. Review all service logs
+3. Consider restoring from backup
+4. For SQLite databases, you may need to run integrity checks
+
+## Getting Help
+
+If you're still experiencing issues:
+
+1. **Check logs**: `docker compose logs` for all services
+2. **Search existing issues**: [GitHub Issues](https://github.com/netbirdio/netbird/issues)
+3. **Join our community**: [Slack Channel](/slack-url)
+4. **Open an issue**: Include logs, configuration (without secrets), and steps to reproduce
\ No newline at end of file
From 30112ebbae5ea2b2fbd4e7eb9cf7185f86c718f1 Mon Sep 17 00:00:00 2001
From: Brandon Hopkins
Date: Mon, 5 Jan 2026 14:01:25 -0800
Subject: [PATCH 02/18] No IdP required, Multiple IdPs supported, Onboarding
flow
---
.../identity-providers/connectors.mdx | 37 +++++------
.../identity-providers/embedded-idp.mdx | 58 ++++++++++--------
.../selfhosted/identity-providers/index.mdx | 41 +++++++------
.../self-hosted-vs-cloud-netbird.mdx | 16 ++---
.../selfhosted/selfhosted-quickstart.mdx | 61 +++++++++++--------
5 files changed, 118 insertions(+), 95 deletions(-)
diff --git a/src/pages/selfhosted/identity-providers/connectors.mdx b/src/pages/selfhosted/identity-providers/connectors.mdx
index 4231da17f..9d75f3a83 100644
--- a/src/pages/selfhosted/identity-providers/connectors.mdx
+++ b/src/pages/selfhosted/identity-providers/connectors.mdx
@@ -1,15 +1,16 @@
-# Identity Provider Connectors
+# External Identity Providers
-When using the [embedded IdP](/selfhosted/identity-providers/embedded-idp), you can add identity provider **connectors** to enable Single Sign-On (SSO). This allows users to sign in with their existing accounts from services like Google, Microsoft, or your corporate identity provider—while still maintaining the simplicity of the embedded IdP.
+NetBird supports connecting **multiple external identity providers** alongside local user management. This allows users to sign in with their existing accounts from services like Google, Microsoft, or your corporate identity provider—while still maintaining the option for local username/password authentication.
-## Why Use Connectors?
+## Why Add External Identity Providers?
-Connectors provide:
+External identity providers give you:
- **Single Sign-On (SSO)** - Users authenticate with familiar credentials
+- **Multiple providers** - Configure as many OIDC-compatible providers as you need
- **Federation** - Multiple identity sources, single NetBird account
- **Flexibility** - Mix local users with SSO authentication
-- **Gradual adoption** - Start with local users, add SSO later
+- **Gradual adoption** - Start with local users, add SSO providers later
## Supported Providers
@@ -24,7 +25,7 @@ Connectors provide:
| [**PocketID**](/selfhosted/identity-providers/pocketid) | `pocketid` | Lightweight self-hosted IdP |
| [**Generic OIDC**](/selfhosted/identity-providers/generic-oidc) | `oidc` | Any OIDC-compliant provider |
-## Adding a Connector
+## Adding an Identity Provider
### Via Dashboard
@@ -36,7 +37,7 @@ Connectors provide:
6. Copy the **Redirect URL** and configure it in your identity provider
-The Identity Providers tab is only visible when the embedded IdP is enabled.
+The Identity Providers tab is only visible when local user management is enabled (default for new installations).
### Via API
@@ -82,33 +83,35 @@ Some providers also require:
Users who authenticate via a connector appear in your Users list with a badge showing their identity provider.
-## Multiple Connectors
+## Multiple Identity Providers
-You can configure multiple connectors simultaneously:
+You can configure **multiple identity providers simultaneously**:
-- All enabled providers appear as buttons on the login page
-- "Continue with Email" (local authentication) is always available
+- All configured providers appear as buttons on the login page
+- "Continue with Email" (local authentication) is always available first
- Users can authenticate with any configured provider
- Each user's provider is tracked and displayed in the Dashboard
+This allows you to support different authentication methods for different user groups—for example, Google for contractors and Microsoft Entra ID for employees.
+
## Best Practices
-1. **Start simple** - Begin with local users, add connectors as needed
-2. **Test thoroughly** - Verify the connector works before announcing to users
+1. **Start simple** - Begin with local users, add external providers as needed
+2. **Test thoroughly** - Verify the provider works before announcing to users
3. **Communicate changes** - Let users know about new login options
-4. **Keep a fallback** - Local authentication remains available if a connector has issues
+4. **Keep a fallback** - Local authentication remains available if an external provider has issues
## Troubleshooting
### Provider not appearing on login page
-- Verify the connector was saved successfully in Settings → Identity Providers
-- Check that the connector is enabled
+- Verify the provider was saved successfully in Settings → Identity Providers
+- Check that the provider is enabled
- Clear browser cache and reload the login page
### "Invalid redirect URI" error
-- Copy the exact Redirect URL from NetBird after creating the connector
+- Copy the exact Redirect URL from NetBird after creating the provider
- Ensure no trailing slashes or typos
- Some providers are case-sensitive
diff --git a/src/pages/selfhosted/identity-providers/embedded-idp.mdx b/src/pages/selfhosted/identity-providers/embedded-idp.mdx
index ac41d177b..43be4ea50 100644
--- a/src/pages/selfhosted/identity-providers/embedded-idp.mdx
+++ b/src/pages/selfhosted/identity-providers/embedded-idp.mdx
@@ -1,21 +1,23 @@
-# Embedded Identity Provider
+# Local User Management
-The embedded identity provider is NetBird's built-in authentication system, powered by [Dex](https://dexidp.io/). It runs directly within the Management service, eliminating the need for external IdP containers or complex configuration.
+NetBird's Management service includes built-in user management, allowing you to create and manage local users directly without requiring an external identity provider. This functionality is powered by an embedded [Dex](https://dexidp.io/) server.
## Overview
-The embedded IdP provides:
+The Management service provides:
- **Local user management** - Create users with email/password authentication directly in NetBird
-- **External connector support** - Optionally integrate Google, GitHub, OIDC, or SAML providers
+- **No external IdP required** - Works out of the box, no Zitadel, Keycloak, or other IdP needed
+- **External identity provider support** - Optionally connect one or more OIDC-compatible providers (Google, Microsoft, Okta, etc.)
+- **Multiple IdP support** - Configure multiple external identity providers simultaneously
- **Device authentication** - CLI authentication via device authorization flow
- **Secure storage** - AES-256-GCM encryption for sensitive user data at rest
-## When to Use Embedded IdP
+## When to Use Local Users
-The embedded IdP is ideal for:
+Local user management is ideal for:
-| Use Case | Why Embedded IdP Works |
+| Use Case | Why Local Users Work |
|----------|----------------------|
| **Homelabs** | Simple setup, minimal resources, no external dependencies |
| **Small teams** | Easy user management, quick onboarding |
@@ -23,29 +25,29 @@ The embedded IdP is ideal for:
| **Air-gapped environments** | No external service dependencies |
| **Development/testing** | Fast iteration, simple reset |
-Consider an [external IdP](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp) if you need:
+Consider a [standalone external IdP](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp) if you need:
- SCIM user provisioning (Enterprise feature)
- Complex user lifecycle management
- Integration with existing enterprise SSO infrastructure
-- Specific IdP features not available in connectors
+- Specific IdP features not available via OIDC connectors
## Architecture
-With the embedded IdP enabled, the architecture is simplified:
+With local user management enabled, the architecture is simplified:
```
- NetBird Management
- ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐
- │ Management │ │ Embedded Dex │ │ Dashboard │
- │ Service │◄─┤ IdP Server │◄─┤ API │
- └─────────────────┘ └─────────────────┘ └─────────────┘
- │ │
- ▼ ▼
- ┌─────────────────────────────────────────────────────────┐
- │ SQLite/Postgres Database │
- │ (Users, Accounts, IdP Connectors) │
- └─────────────────────────────────────────────────────────┘
+ NetBird Management
+┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐
+│ Management │ │ Embedded Dex │ │ Dashboard │
+│ Service │◄─┤ IdP Server │◄─┤ API │
+└─────────────────┘ └─────────────────┘ └─────────────┘
+ │ │
+ ▼ ▼
+┌─────────────────────────────────────────────────────────┐
+│ SQLite/Postgres Database │
+│ (Users, Accounts, IdP Connectors) │
+└─────────────────────────────────────────────────────────┘
```
Compare this to the external IdP architecture which requires separate containers for the IdP and its database.
@@ -94,7 +96,7 @@ openssl rand -base64 32
```
-**Warning:** Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures.
+Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures.
## User Management
@@ -117,7 +119,7 @@ After creation, a modal displays with:
- **Copy & Close** button to copy password and dismiss
-**Warning:** The generated password is only shown once at creation time. It cannot be retrieved later. Make sure to copy it and share it securely with the user.
+The generated password is only shown once at creation time. It cannot be retrieved later. Make sure to copy it and share it securely with the user.
### User IdP Badges
@@ -213,9 +215,9 @@ curl -X POST "https://netbird.example.com/api/instance/setup" \
}
```
-## Adding Identity Provider Connectors
+## Adding External Identity Providers
-The embedded IdP supports adding identity provider [**connectors**](/selfhosted/identity-providers/connectors) to enable SSO. This allows users to sign in with existing accounts from:
+You can connect one or more external identity providers to enable SSO alongside local users. This allows users to sign in with existing accounts from:
- Google
- Microsoft (personal accounts)
@@ -225,7 +227,9 @@ The embedded IdP supports adding identity provider [**connectors**](/selfhosted/
- PocketID
- Any OIDC-compliant provider
-### Managing Connectors via Dashboard
+**Multiple providers supported**: You can configure as many OIDC-compatible identity providers as you need. Users will see all configured providers as login options alongside the local email/password option.
+
+### Managing External IdPs via Dashboard
1. Navigate to **Settings** → **Identity Providers**
2. Click **Add Identity Provider**
@@ -404,5 +408,5 @@ To switch from embedded IdP to an external IdP:
4. Users will need to re-authenticate with the new IdP
-**Warning:** Disabling the embedded IdP will invalidate all local user accounts. Ensure users have accounts in the external IdP before switching.
+Disabling the embedded IdP will invalidate all local user accounts. Ensure users have accounts in the external IdP before switching.
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/index.mdx b/src/pages/selfhosted/identity-providers/index.mdx
index bff8ebc28..cecc5458a 100644
--- a/src/pages/selfhosted/identity-providers/index.mdx
+++ b/src/pages/selfhosted/identity-providers/index.mdx
@@ -2,19 +2,20 @@
NetBird's self-hosted implementation uses the OpenID Connect (OIDC) protocol for authentication, an industry-standard identity layer built on top of OAuth 2.0. OIDC is used both for user authentication to access the Management Service Dashboard and for user device authorization when accessing internal resources.
-## Embedded IdP (Recommended)
+## Local User Management
-Starting with version X.XX, NetBird includes a **built-in identity provider** powered by [Dex](https://dexidp.io/). This is now the default for new deployments and eliminates the need for separate IdP infrastructure.
+Starting with version X.XX, NetBird **no longer requires an external identity provider**. The Management service now supports creating and managing local users directly, so you can get started without setting up Zitadel, Keycloak, or any other IdP.
-With the embedded IdP, you can:
+With local user management, you can:
- **Create local users** directly from the NetBird Dashboard
-- **Add SSO connectors** (Google, Microsoft, Okta, etc.) through the Dashboard UI
+- **Add external identity providers** (Google, Microsoft, Okta, etc.) through the Dashboard UI
+- **Configure multiple IdPs** simultaneously—users see all providers as login options
- **Simplify your deployment** with fewer containers and reduced resource requirements
-- **Get started faster** with automatic configuration and no additional setup
+- **Get started faster** with no additional IdP setup required
-The embedded IdP uses [Dex](https://dexidp.io/), a lightweight, portable OIDC identity provider that supports federated authentication. Dex runs embedded within the NetBird Management service, requiring no additional containers or databases.
+Local user management is powered by an embedded [Dex](https://dexidp.io/) server running within the NetBird Management service, requiring no additional containers or databases.
[Get Started →](/selfhosted/selfhosted-quickstart)
@@ -35,11 +36,11 @@ This approach provides several key benefits:
| Approach | Best For | Setup Complexity |
|----------|----------|------------------|
-| **Embedded IdP Only** | Homelabs, small teams, quick deployments | Minimal |
-| **Embedded IdP + Connectors** | Organizations wanting SSO with existing providers | Low |
+| **Local Users Only** | Homelabs, small teams, quick deployments | Minimal |
+| **Local Users + External IdPs** | Organizations wanting SSO with existing providers | Low |
| **Standalone IdP (Advanced)** | Enterprises with existing IdP investments, SCIM requirements | Moderate to High |
-### Embedded IdP Only
+### Local Users Only
The simplest approach—create and manage users directly in NetBird:
@@ -50,16 +51,17 @@ The simplest approach—create and manage users directly in NetBird:
[Setup Guide →](/selfhosted/identity-providers/embedded-idp)
-### Embedded IdP with Connectors
+### Local Users + External Identity Providers
-Combine the simplicity of embedded IdP with your existing identity providers:
+Combine local user management with your existing identity providers:
- Keep local user management as a fallback
-- Add Google, Microsoft, Okta, or other SSO for convenience
-- Configure connectors directly from the Dashboard UI
+- Add Google, Microsoft, Okta, or other providers for SSO
+- **Configure multiple IdPs**—users see all options on the login page
+- Configure everything directly from the Dashboard UI
- Best of both worlds
-[About Connectors →](/selfhosted/identity-providers/connectors)
+[About External IdPs →](/selfhosted/identity-providers/connectors)
### Standalone IdP (Advanced)
@@ -76,7 +78,7 @@ For organizations with specific requirements or existing IdP investments:
## Identity Provider Options
-Each provider page includes both **connector setup** (recommended, for use with embedded IdP) and **standalone setup** (advanced) instructions.
+Each provider page includes both **connector setup** (recommended, for adding to local user management) and **standalone setup** (advanced) instructions.
### Self-Hosted Providers
@@ -109,12 +111,11 @@ In addition to OIDC-based authentication, NetBird supports provisioning users an
## Migration Guide
-If you have an existing NetBird deployment using a standalone IdP (like Zitadel from the previous quickstart), you can continue using it. To migrate to the embedded IdP:
+If you have an existing NetBird deployment using a standalone IdP (like Zitadel from the previous quickstart), you have several options:
-1. Export your user list from your current IdP
-2. Deploy the new version with embedded IdP enabled
-3. Recreate users through the Dashboard or API
-4. (Optional) Add your previous IdP as a connector for SSO
+1. **Keep using your standalone IdP** - No changes required, your setup continues to work
+2. **Add your IdP as an external provider** - Keep your IdP but add it as an OIDC provider alongside local users
+3. **Migrate to local users** - Export users from your IdP and recreate them as local users
User data and network configurations are preserved during migration. Only authentication changes—users may need to re-authenticate after the switch.
diff --git a/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx b/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx
index d578791e3..9751fe8bf 100644
--- a/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx
+++ b/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx
@@ -18,15 +18,16 @@ peer-to-peer connectivity, fallback relayed connections through a network of geo
and overall system reliability and availability. It is not an easy task to deploy and maintain such infrastructure in
a reliable manner. NetBird is not just one VPN server. You can read more about how NetBird works [here](/about-netbird/how-netbird-works).
-## What's New: Simplified Self-Hosting
+## What's New: No External IdP Required
-Starting with version X.XX, self-hosting NetBird has become significantly easier with the introduction of the **embedded identity provider**. Previously, self-hosting required setting up and maintaining a separate identity provider (like Zitadel, Keycloak, or Auth0). Now, NetBird includes a built-in IdP powered by [Dex](https://dexidp.io/), which means:
+Starting with version X.XX, self-hosting NetBird has become significantly easier. Previously, self-hosting required setting up and maintaining a separate identity provider (like Zitadel, Keycloak, or Auth0). Now, the Management service supports **local user management** directly, which means:
+- **No external IdP required** - Create and manage users directly in NetBird
- **Fewer containers** to deploy and maintain (4-5 vs 7+ previously)
- **Lower resource requirements** (~1GB RAM vs 2-4GB previously)
-- **No external IdP configuration** required
- **User management directly in the Dashboard**
-- **Optional SSO connectors** if you want to integrate with Google, Microsoft, Okta, etc.
+- **Optional external IdPs** - Connect Google, Microsoft, Okta, etc. if you want SSO
+- **Multiple IdPs supported** - Configure multiple OIDC providers simultaneously
This makes self-hosting a more viable option for homelabs, small teams, and proof-of-concept deployments.
@@ -37,7 +38,7 @@ machines to establish direct point-to-point connections and for network administ
e.g., control network access.
When running the self-hosted version, you are responsible for installing and maintaining all the components as well as backing up
-and securing the data. With the new embedded IdP, this burden is reduced—you no longer need to maintain a separate identity provider infrastructure.
+and securing the data. With local user management built into the Management service, this burden is significantly reduced—you no longer need to maintain separate identity provider infrastructure.
The cloud-hosted NetBird only requires you to install the client software (NetBird agent) on your machines and log them in to the network.
The cloud-hosted version is more suitable for organizations that want a hassle-free solution that is easy to set up and maintain.
@@ -78,9 +79,10 @@ your critical network infrastructure.
| Aspect | Self-Hosted | Cloud-Hosted |
|--------|-------------|--------------|
-| **Setup time** | ~5 minutes with embedded IdP | Instant |
+| **Setup time** | ~5 minutes with local users | Instant |
| **Infrastructure** | You manage | We manage |
-| **Identity provider** | Built-in (or bring your own) | Managed |
+| **Identity provider** | Built-in local users (+ optional external IdPs) | Managed |
+| **Multiple IdPs** | Yes, OIDC-compatible | Yes |
| **Relay servers** | Single instance (or DIY geo-distribution) | Geo-distributed globally |
| **High availability** | DIY | Included |
| **SCIM provisioning** | Enterprise license | Included (Business+) |
diff --git a/src/pages/selfhosted/selfhosted-quickstart.mdx b/src/pages/selfhosted/selfhosted-quickstart.mdx
index 221274d56..3a7ec2f84 100644
--- a/src/pages/selfhosted/selfhosted-quickstart.mdx
+++ b/src/pages/selfhosted/selfhosted-quickstart.mdx
@@ -3,7 +3,7 @@
NetBird is open-source and can be self-hosted on your servers.
It relies on components developed by NetBird Authors [Management Service](https://github.com/netbirdio/netbird/tree/main/management), [Management UI Dashboard](https://github.com/netbirdio/dashboard), [Signal Service](https://github.com/netbirdio/netbird/tree/main/signal),
-a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn), and a built-in identity provider.
+and a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn).
If you would like to learn more about the architecture please refer to the [Architecture section](/about-netbird/how-netbird-works).
@@ -12,15 +12,22 @@ It might be a good idea to try NetBird before self-hosting on your servers.
We run NetBird in the cloud, and it will take a few clicks to get started with our managed version. [Check it out!](https://netbird.io/pricing)
-## Quick self-hosting with embedded IdP
+## Quick self-hosting
-Starting with version X.XX, NetBird includes a **built-in identity provider** powered by [Dex](https://dexidp.io/). This eliminates the need for external IdP setup and is the recommended approach for new deployments.
+Starting with version X.XX, NetBird **no longer requires an external identity provider**. The Management service now supports creating and managing local users directly, so you can get started without setting up Zitadel, Keycloak, or any other IdP.
This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM.
-For advanced setups with custom IdPs, see the [Advanced guide](/selfhosted/selfhosted-guide).
+For advanced setups with standalone IdPs, see the [Advanced guide](/selfhosted/selfhosted-guide).
+### What you get
+
+- **Local user management** - Create and manage users directly in the Dashboard
+- **No external IdP required** - Works out of the box without Zitadel, Keycloak, or any other identity provider
+- **Optional SSO integration** - Connect one or more external identity providers (Google, Microsoft, Okta, etc.) if needed
+- **Multiple IdP support** - Configure multiple OIDC-compatible identity providers simultaneously
+
### Requirements
**Infrastructure requirements:**
@@ -52,23 +59,26 @@ bash getting-started.sh
Replace `netbird.example.com` with your domain name.
-### Initial setup
+### Initial setup (Onboarding)
-Once the script completes, open your browser and navigate to `https://netbird.example.com/setup`. You'll be prompted to create your first admin user:
+The script deploys NetBird **without any users**. Once complete, you'll need to create your first user:
-1. Enter your email address
-2. Set a secure password
-3. Click **Create Account**
+1. Open your browser and navigate to `https://netbird.example.com`
+2. You'll be redirected to the setup page (`/setup`)
+3. Create your admin account:
+ - Enter your email address
+ - Set a secure password
+ - Click **Create Account**
-This creates the owner account for your NetBird instance. You can now log in to the Dashboard.
+This creates the owner account for your NetBird instance. You'll be logged in automatically and can start using the Dashboard.
-The `/setup` page is only accessible once. After creating the first user, it will redirect to the login page.
+The `/setup` page is only accessible when no users exist. After creating the first user, it redirects to the regular login page.
-### Add users
+### Add more local users
-You can add users directly from the NetBird Dashboard:
+You can add additional local users directly from the NetBird Dashboard—no external identity provider needed:
1. Navigate to **Team** → **Users**
2. Click **Create User**
@@ -77,16 +87,19 @@ You can add users directly from the NetBird Dashboard:
A password will be generated and displayed once. Share this securely with the user—it cannot be retrieved later.
-### Add SSO (Optional)
+### Connect identity providers (Optional)
-Want users to sign in with Google, Microsoft, or your corporate IdP? You can add SSO connectors directly from the Dashboard:
+Local users work great on their own, but if you want users to sign in with their existing accounts from Google, Microsoft, Okta, or other providers, you can connect external identity providers:
1. Navigate to **Settings** → **Identity Providers**
2. Click **Add Identity Provider**
-3. Select your provider (Google, Microsoft, Okta, etc.)
-4. Follow the provider-specific setup instructions
+3. Select your provider type (Google, Microsoft, Okta, or generic OIDC)
+4. Enter the OAuth client credentials from your provider
+5. Click **Save**
+
+**Multiple providers supported**: You can add as many OIDC-compatible identity providers as you need. Users will see all configured providers as login options.
-For detailed setup guides, see [Identity Provider Connectors](/selfhosted/identity-providers/connectors).
+For detailed setup guides, see [Identity Providers](/selfhosted/identity-providers).
### Backup
@@ -160,10 +173,10 @@ For more troubleshooting help, see the [Troubleshooting guide](/selfhosted/troub
---
-## Legacy: Quick self-hosting with Zitadel IdP
+## Legacy: Self-hosting with Zitadel IdP
-This section is for users who prefer to use Zitadel as a standalone IdP instead of the embedded IdP. For new installations, we recommend the [embedded IdP approach](#quick-self-hosting-with-embedded-idp) above.
+This section is for users who prefer to use Zitadel as a standalone IdP instead of local user management. For new installations, we recommend the [quickstart approach](#quick-self-hosting) above—you can always add Zitadel as an external identity provider later if needed.
If you want to deploy NetBird with [Zitadel](https://zitadel.com/) as the identity provider, you can use the legacy quickstart script:
@@ -214,12 +227,12 @@ docker compose down --volumes
rm -f docker-compose.yml Caddyfile zitadel.env dashboard.env machinekey/zitadel-admin-sa.token turnserver.conf management.json
```
-### Migrating from Zitadel to Embedded IdP
+### Migrating from Zitadel to Local Users
-If you have an existing Zitadel deployment and want to migrate to the embedded IdP:
+If you have an existing Zitadel deployment and want to migrate:
-1. **Option A**: Keep Zitadel as a connector—add it as an SSO provider in the embedded IdP
-2. **Option B**: Recreate users in the embedded IdP and decommission Zitadel
+1. **Option A**: Keep Zitadel as an external provider—add it as an identity provider in Settings
+2. **Option B**: Recreate users as local users and decommission Zitadel
See the [Migration Guide](/selfhosted/identity-providers/migration) for detailed steps.
From 9acd32f6485fe80ca73d57c83ebfe23f8b0a1a44 Mon Sep 17 00:00:00 2001
From: Brandon Hopkins
Date: Mon, 5 Jan 2026 14:05:46 -0800
Subject: [PATCH 03/18] File Name Change
---
src/components/NavigationDocs.jsx | 2 +-
.../identity-providers/{connectors.mdx => idp-connectors.mdx} | 3 ++-
src/pages/selfhosted/identity-providers/index.mdx | 2 +-
3 files changed, 4 insertions(+), 3 deletions(-)
rename src/pages/selfhosted/identity-providers/{connectors.mdx => idp-connectors.mdx} (99%)
diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx
index c46314177..ee90f39ea 100644
--- a/src/components/NavigationDocs.jsx
+++ b/src/components/NavigationDocs.jsx
@@ -289,7 +289,7 @@ export const docsNavigation = [
links: [
{ title: 'Using IdPs on Self-Hosted', href: '/selfhosted/identity-providers' },
{ title: 'Embedded IdP', href: '/selfhosted/identity-providers/embedded-idp' },
- { title: 'Connectors', href: '/selfhosted/identity-providers/connectors' },
+ { title: 'Connectors', href: '/selfhosted/identity-providers/idp-connectors' },
{ title: 'API Reference', href: '/selfhosted/identity-providers/api-reference' },
{
title: 'Self-hosted IdPs',
diff --git a/src/pages/selfhosted/identity-providers/connectors.mdx b/src/pages/selfhosted/identity-providers/idp-connectors.mdx
similarity index 99%
rename from src/pages/selfhosted/identity-providers/connectors.mdx
rename to src/pages/selfhosted/identity-providers/idp-connectors.mdx
index 9d75f3a83..92bea8dbc 100644
--- a/src/pages/selfhosted/identity-providers/connectors.mdx
+++ b/src/pages/selfhosted/identity-providers/idp-connectors.mdx
@@ -121,4 +121,5 @@ This allows you to support different authentication methods for different user g
- Verify the token contains required claims (email, name)
- Ensure the user's email domain is not blocked by any policies
-For provider-specific troubleshooting, see the individual provider pages.
\ No newline at end of file
+For provider-specific troubleshooting, see the individual provider pages.
+
diff --git a/src/pages/selfhosted/identity-providers/index.mdx b/src/pages/selfhosted/identity-providers/index.mdx
index cecc5458a..d2a8fdcfd 100644
--- a/src/pages/selfhosted/identity-providers/index.mdx
+++ b/src/pages/selfhosted/identity-providers/index.mdx
@@ -61,7 +61,7 @@ Combine local user management with your existing identity providers:
- Configure everything directly from the Dashboard UI
- Best of both worlds
-[About External IdPs →](/selfhosted/identity-providers/connectors)
+[About External IdPs →](/selfhosted/identity-providers/idp-connectors)
### Standalone IdP (Advanced)
From 6db3463751dc09b63379e1c449f2695178fb5fc2 Mon Sep 17 00:00:00 2001
From: Brandon Hopkins
Date: Mon, 5 Jan 2026 15:02:13 -0800
Subject: [PATCH 04/18] Add Announcement
---
.../announcement-banner/AnnouncementBannerProvider.jsx | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/src/components/announcement-banner/AnnouncementBannerProvider.jsx b/src/components/announcement-banner/AnnouncementBannerProvider.jsx
index 6b426ef7f..c88956c96 100644
--- a/src/components/announcement-banner/AnnouncementBannerProvider.jsx
+++ b/src/components/announcement-banner/AnnouncementBannerProvider.jsx
@@ -12,11 +12,11 @@ import { useLocalStorage } from '@/hooks/useLocalStorage'
const BANNER_ENABLED = true
export const announcement = {
- tag: '',
- text: 'NetBird v0.60 Released - Native SSH Access',
- link: '/manage/peers/ssh',
- linkText: 'Read Release Documentation',
- linkAlt: 'Learn more about the NetBird v0.60 release',
+ tag: 'New',
+ text: 'Embedded Identity Provider with DEX for Self-Hosted Installations',
+ link: '/selfhosted/identity-providers/embedded-idp',
+ linkText: 'Learn More',
+ linkAlt: 'Learn more about the embedded Identity Provider powered by DEX for self-hosted installations',
isExternal: false,
closeable: true,
}
From 4a71dbfdac6a02f8bc0e09d3e3a845aa25f7dc67 Mon Sep 17 00:00:00 2001
From: Brandon Hopkins
Date: Mon, 5 Jan 2026 15:29:53 -0800
Subject: [PATCH 05/18] Specify that Embedded IdP is Recommended
---
src/pages/selfhosted/identity-providers/authentik.mdx | 4 +++-
src/pages/selfhosted/identity-providers/keycloak.mdx | 4 +++-
src/pages/selfhosted/identity-providers/managed/auth0.mdx | 4 +++-
.../identity-providers/managed/google-workspace.mdx | 4 +++-
src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx | 4 +++-
.../identity-providers/managed/microsoft-entra-id.mdx | 4 +++-
src/pages/selfhosted/identity-providers/managed/okta.mdx | 4 +++-
src/pages/selfhosted/identity-providers/pocketid.mdx | 4 +++-
src/pages/selfhosted/identity-providers/zitadel.mdx | 4 +++-
9 files changed, 27 insertions(+), 9 deletions(-)
diff --git a/src/pages/selfhosted/identity-providers/authentik.mdx b/src/pages/selfhosted/identity-providers/authentik.mdx
index 1291e61b7..f44f072ba 100644
--- a/src/pages/selfhosted/identity-providers/authentik.mdx
+++ b/src/pages/selfhosted/identity-providers/authentik.mdx
@@ -86,7 +86,9 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
## Standalone Setup (Advanced)
-Use Authentik as your primary identity provider instead of the embedded IdP. This approach gives you full control over identity management but requires more configuration.
+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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-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/auth0).
diff --git a/src/pages/selfhosted/identity-providers/keycloak.mdx b/src/pages/selfhosted/identity-providers/keycloak.mdx
index 16248c335..1ac2aa6df 100644
--- a/src/pages/selfhosted/identity-providers/keycloak.mdx
+++ b/src/pages/selfhosted/identity-providers/keycloak.mdx
@@ -71,7 +71,9 @@ Users who authenticate via Keycloak will appear in your NetBird Users list with
## Standalone Setup (Advanced)
-Use Keycloak as your primary identity provider instead of the embedded IdP. This approach gives you full control but requires more configuration.
+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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-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/auth0).
diff --git a/src/pages/selfhosted/identity-providers/managed/auth0.mdx b/src/pages/selfhosted/identity-providers/managed/auth0.mdx
index 407b9d462..7ed9faf52 100644
--- a/src/pages/selfhosted/identity-providers/managed/auth0.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/auth0.mdx
@@ -63,7 +63,9 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
## Standalone Setup (Advanced)
-Use Auth0 as your primary identity provider instead of the embedded IdP.
+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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
diff --git a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
index 4ae600512..8154ba1c9 100644
--- a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
@@ -84,7 +84,9 @@ Domain restrictions are configured in Google Cloud Console, not in NetBird.
## Standalone Setup (Advanced)
-Use Google Workspace as your primary identity provider instead of the embedded IdP. This enables full user management integration with Google Workspace.
+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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-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.
diff --git a/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx b/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
index 9ab8359e1..9f0c5cf8d 100644
--- a/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
@@ -73,7 +73,9 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
## Standalone Setup (Advanced)
-Use JumpCloud as your primary identity provider instead of the embedded IdP.
+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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
### Prerequisites
diff --git a/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx b/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
index c2c5729eb..e5ed03057 100644
--- a/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
@@ -89,7 +89,9 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
## Standalone Setup (Advanced)
-Use Microsoft Entra ID as your primary identity provider instead of the embedded IdP.
+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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
diff --git a/src/pages/selfhosted/identity-providers/managed/okta.mdx b/src/pages/selfhosted/identity-providers/managed/okta.mdx
index 4e5acb4bd..86f0b2dc2 100644
--- a/src/pages/selfhosted/identity-providers/managed/okta.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/okta.mdx
@@ -66,7 +66,9 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
## Standalone Setup (Advanced)
-Use Okta as your primary identity provider instead of the embedded IdP.
+Use Okta 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 Okta administrators as it also requires additional setup and ongoing maintenance.
+
+For most deployments, the [embedded IdP](/selfhosted/identity-providers/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
diff --git a/src/pages/selfhosted/identity-providers/pocketid.mdx b/src/pages/selfhosted/identity-providers/pocketid.mdx
index c21efb45e..be37fb960 100644
--- a/src/pages/selfhosted/identity-providers/pocketid.mdx
+++ b/src/pages/selfhosted/identity-providers/pocketid.mdx
@@ -67,7 +67,9 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
## Standalone Setup (Advanced)
-Use PocketID as your primary identity provider instead of the embedded IdP.
+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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
### Prerequisites
diff --git a/src/pages/selfhosted/identity-providers/zitadel.mdx b/src/pages/selfhosted/identity-providers/zitadel.mdx
index 2b5c848b6..7eece79db 100644
--- a/src/pages/selfhosted/identity-providers/zitadel.mdx
+++ b/src/pages/selfhosted/identity-providers/zitadel.mdx
@@ -70,7 +70,9 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
## Standalone Setup (Advanced)
-Use Zitadel as your primary identity provider instead of the embedded IdP. This was the default approach in previous NetBird versions.
+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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
If you prefer not to self-host, Zitadel offers a managed cloud option at [zitadel.com](https://zitadel.com/).
From dc05cc65ea8c99fff344bcf0213a5283403b5f7c Mon Sep 17 00:00:00 2001
From: Brandon Hopkins
Date: Mon, 5 Jan 2026 22:36:46 -0800
Subject: [PATCH 06/18] Condense Pages to index.mdx and Extra Remove Idp Info
Quickstart
---
src/components/NavigationDocs.jsx | 2 -
.../AnnouncementBannerProvider.jsx | 2 +-
.../identity-providers/api-reference.mdx | 2 +-
.../identity-providers/authentik.mdx | 4 +-
.../identity-providers/embedded-idp.mdx | 412 -------------
.../identity-providers/idp-connectors.mdx | 125 ----
.../selfhosted/identity-providers/index.mdx | 578 +++++++++++++++++-
.../identity-providers/keycloak.mdx | 4 +-
.../identity-providers/managed/auth0.mdx | 4 +-
.../managed/google-workspace.mdx | 4 +-
.../identity-providers/managed/jumpcloud.mdx | 4 +-
.../managed/microsoft-entra-id.mdx | 4 +-
.../identity-providers/managed/okta.mdx | 4 +-
.../identity-providers/pocketid.mdx | 4 +-
.../selfhosted/identity-providers/zitadel.mdx | 4 +-
.../selfhosted/selfhosted-quickstart.mdx | 15 +-
16 files changed, 575 insertions(+), 597 deletions(-)
delete mode 100644 src/pages/selfhosted/identity-providers/embedded-idp.mdx
delete mode 100644 src/pages/selfhosted/identity-providers/idp-connectors.mdx
diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx
index ee90f39ea..39a2233b6 100644
--- a/src/components/NavigationDocs.jsx
+++ b/src/components/NavigationDocs.jsx
@@ -288,8 +288,6 @@ export const docsNavigation = [
isOpen: false,
links: [
{ title: 'Using IdPs on Self-Hosted', href: '/selfhosted/identity-providers' },
- { title: 'Embedded IdP', href: '/selfhosted/identity-providers/embedded-idp' },
- { title: 'Connectors', href: '/selfhosted/identity-providers/idp-connectors' },
{ title: 'API Reference', href: '/selfhosted/identity-providers/api-reference' },
{
title: 'Self-hosted IdPs',
diff --git a/src/components/announcement-banner/AnnouncementBannerProvider.jsx b/src/components/announcement-banner/AnnouncementBannerProvider.jsx
index c88956c96..9233eebf2 100644
--- a/src/components/announcement-banner/AnnouncementBannerProvider.jsx
+++ b/src/components/announcement-banner/AnnouncementBannerProvider.jsx
@@ -14,7 +14,7 @@ const BANNER_ENABLED = true
export const announcement = {
tag: 'New',
text: 'Embedded Identity Provider with DEX for Self-Hosted Installations',
- link: '/selfhosted/identity-providers/embedded-idp',
+ link: '/selfhosted/identity-providers#local-user-management',
linkText: 'Learn More',
linkAlt: 'Learn more about the embedded Identity Provider powered by DEX for self-hosted installations',
isExternal: false,
diff --git a/src/pages/selfhosted/identity-providers/api-reference.mdx b/src/pages/selfhosted/identity-providers/api-reference.mdx
index 2311925c5..e73fa247e 100644
--- a/src/pages/selfhosted/identity-providers/api-reference.mdx
+++ b/src/pages/selfhosted/identity-providers/api-reference.mdx
@@ -1,6 +1,6 @@
# Identity Provider API Reference
-This page documents the API endpoints for managing identity providers when using the [embedded IdP](/selfhosted/identity-providers/embedded-idp).
+This page documents the API endpoints for managing identity providers when using the [embedded IdP](/selfhosted/identity-providers#local-user-management).
## Base URL
diff --git a/src/pages/selfhosted/identity-providers/authentik.mdx b/src/pages/selfhosted/identity-providers/authentik.mdx
index f44f072ba..23c4aeb6f 100644
--- a/src/pages/selfhosted/identity-providers/authentik.mdx
+++ b/src/pages/selfhosted/identity-providers/authentik.mdx
@@ -88,7 +88,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+For most deployments, the [embedded IdP](/selfhosted/identity-providers#local-user-management) 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 [Connector Setup (Recommended)](#connector-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/auth0).
@@ -238,5 +238,5 @@ You've configured all required resources in Authentik. Continue with the [NetBir
## Related Resources
- [Authentik Documentation](https://goauthentik.io/docs/)
-- [Embedded IdP Overview](/selfhosted/identity-providers/embedded-idp)
+- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
- [API Reference](/selfhosted/identity-providers/api-reference)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/embedded-idp.mdx b/src/pages/selfhosted/identity-providers/embedded-idp.mdx
deleted file mode 100644
index 43be4ea50..000000000
--- a/src/pages/selfhosted/identity-providers/embedded-idp.mdx
+++ /dev/null
@@ -1,412 +0,0 @@
-# Local User Management
-
-NetBird's Management service includes built-in user management, allowing you to create and manage local users directly without requiring an external identity provider. This functionality is powered by an embedded [Dex](https://dexidp.io/) server.
-
-## Overview
-
-The Management service provides:
-
-- **Local user management** - Create users with email/password authentication directly in NetBird
-- **No external IdP required** - Works out of the box, no Zitadel, Keycloak, or other IdP needed
-- **External identity provider support** - Optionally connect one or more OIDC-compatible providers (Google, Microsoft, Okta, etc.)
-- **Multiple IdP support** - Configure multiple external identity providers simultaneously
-- **Device authentication** - CLI authentication via device authorization flow
-- **Secure storage** - AES-256-GCM encryption for sensitive user data at rest
-
-## When to Use Local Users
-
-Local user management is ideal for:
-
-| Use Case | Why Local Users Work |
-|----------|----------------------|
-| **Homelabs** | Simple setup, minimal resources, no external dependencies |
-| **Small teams** | Easy user management, quick onboarding |
-| **Proof of concept** | Get started in minutes, upgrade path available |
-| **Air-gapped environments** | No external service dependencies |
-| **Development/testing** | Fast iteration, simple reset |
-
-Consider a [standalone external IdP](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp) if you need:
-
-- SCIM user provisioning (Enterprise feature)
-- Complex user lifecycle management
-- Integration with existing enterprise SSO infrastructure
-- Specific IdP features not available via OIDC connectors
-
-## Architecture
-
-With local user management enabled, the architecture is simplified:
-
-```
- NetBird Management
-┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐
-│ Management │ │ Embedded Dex │ │ Dashboard │
-│ Service │◄─┤ IdP Server │◄─┤ API │
-└─────────────────┘ └─────────────────┘ └─────────────┘
- │ │
- ▼ ▼
-┌─────────────────────────────────────────────────────────┐
-│ SQLite/Postgres Database │
-│ (Users, Accounts, IdP Connectors) │
-└─────────────────────────────────────────────────────────┘
-```
-
-Compare this to the external IdP architecture which requires separate containers for the IdP and its database.
-
-## Configuration
-
-### Enabling Embedded IdP
-
-The embedded IdP is enabled by default when using the new `getting-started.sh` quickstart script. For manual configuration, update your `management.json`:
-
-```json
-{
- "EmbeddedIdP": {
- "Enabled": true,
- "DataDir": "/var/lib/netbird/idp"
- },
- "EncryptionKey": ""
-}
-```
-
-### Configuration Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `EmbeddedIdP.Enabled` | Enable/disable the embedded IdP | `true` (quickstart) |
-| `EmbeddedIdP.DataDir` | Directory for IdP data storage | `/var/lib/netbird/idp` |
-| `EncryptionKey` | Base64-encoded AES-256 key for encrypting user data | Auto-generated |
-
-### Environment Variables
-
-When using docker-compose, you can configure these via environment variables:
-
-```yaml
-environment:
- - NETBIRD_EMBEDDED_IDP_ENABLED=true
- - NETBIRD_EMBEDDED_IDP_DATA_DIR=/var/lib/netbird/idp
- - NETBIRD_ENCRYPTION_KEY=${ENCRYPTION_KEY}
-```
-
-### Generating an Encryption Key
-
-If you need to generate an encryption key manually:
-
-```bash
-openssl rand -base64 32
-```
-
-
-Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures.
-
-
-## User Management
-
-### Creating Users via Dashboard
-
-When embedded IdP is enabled, the Dashboard shows a **"Create User"** button (instead of "Invite User" shown for cloud-hosted NetBird):
-
-1. Navigate to **Team** → **Users**
-2. Click **Create User**
-3. Fill in the user details:
- - **Email** (required) - User's email address for login
- - **Name** (required) - Display name
- - **Groups** (optional) - Auto-assign to groups
-4. Click **Create**
-
-After creation, a modal displays with:
-- The **generated password** with a copy button
-- Warning: *"This password will only be shown once. Please copy it now."*
-- **Copy & Close** button to copy password and dismiss
-
-
-The generated password is only shown once at creation time. It cannot be retrieved later. Make sure to copy it and share it securely with the user.
-
-
-### User IdP Badges
-
-In the Users table, each user shows a badge indicating their identity provider:
-- Users created locally show no badge (or "Local" badge)
-- Users who authenticated via an external connector show that provider's icon (Google, Microsoft, etc.)
-- The badge links to the `idp_id` field in the user record
-
-### Creating Users via API
-
-```bash
-curl -X POST "https://netbird.example.com/api/users" \
- -H "Authorization: Bearer ${TOKEN}" \
- -H "Content-Type: application/json" \
- -d '{
- "email": "user@example.com",
- "name": "New User",
- "auto_groups": ["group-id-1"]
- }'
-```
-
-Response includes the generated password:
-
-```json
-{
- "id": "user-abc123",
- "email": "user@example.com",
- "name": "New User",
- "role": "user",
- "status": "active",
- "password": "generated-password-here"
-}
-```
-
-
-The `password` field is only included when creating users with embedded IdP. Store it immediately—it won't be returned in subsequent API calls.
-
-
-### User Roles
-
-Users created through the embedded IdP can be assigned roles:
-
-| Role | Permissions |
-|------|-------------|
-| **Owner** | Full administrative access, cannot be demoted |
-| **Admin** | Manage users, peers, policies, and settings |
-| **User** | Connect devices, view assigned resources |
-
-## Instance Setup (First Run)
-
-When NetBird starts with the embedded IdP and no existing accounts, the Dashboard redirects to the `/setup` route and displays the **Instance Setup Wizard**:
-
-1. The Dashboard checks `GET /instance` for `setup_required: true`
-2. If setup is required, users are redirected to `/setup`
-3. The wizard collects:
- - **Email address** (required)
- - **Password** (required, minimum 8 characters)
- - **Name** (optional)
-4. On submit, the owner account is created via `POST /instance/setup`
-5. User is redirected to login with the credentials they just created
-
-
-The `/setup` route is unauthenticated and only accessible when `setup_required` is true. Once setup is complete, accessing `/setup` returns a 412 error and redirects to login.
-
-
-### Setup API
-
-For automated deployments, you can complete setup via API:
-
-```bash
-# Check if setup is required
-curl "https://netbird.example.com/api/instance"
-
-# Response when setup is needed:
-{
- "setup_required": true
-}
-
-# Complete setup
-curl -X POST "https://netbird.example.com/api/instance/setup" \
- -H "Content-Type: application/json" \
- -d '{
- "email": "admin@example.com",
- "password": "securepassword123",
- "name": "Admin User"
- }'
-
-# Response:
-{
- "user_id": "user-abc123",
- "account_id": "account-xyz789"
-}
-```
-
-## Adding External Identity Providers
-
-You can connect one or more external identity providers to enable SSO alongside local users. This allows users to sign in with existing accounts from:
-
-- Google
-- Microsoft (personal accounts)
-- Microsoft Entra ID (Azure AD / work accounts)
-- Okta
-- Zitadel
-- PocketID
-- Any OIDC-compliant provider
-
-**Multiple providers supported**: You can configure as many OIDC-compatible identity providers as you need. Users will see all configured providers as login options alongside the local email/password option.
-
-### Managing External IdPs via Dashboard
-
-1. Navigate to **Settings** → **Identity Providers**
-2. Click **Add Identity Provider**
-3. Select your provider type from the dropdown
-4. Configure the required fields:
- - **Name** - Display name for the login button
- - **Client ID** - From your identity provider
- - **Client Secret** - From your identity provider
- - **Issuer** - Required for Okta, Zitadel, PocketID, and generic OIDC
-5. Click **Save**
-
-After saving, a modal displays the **Redirect URL** that you must configure in your identity provider's OAuth settings. Copy this URL before closing.
-
-
-The Identity Providers tab is only visible when `embedded_idp_enabled` is `true` in your account settings.
-
-
-For detailed setup instructions for each provider, see the individual provider pages:
-- [Google](/selfhosted/identity-providers/google)
-- [Microsoft](/selfhosted/identity-providers/microsoft)
-- [Keycloak](/selfhosted/identity-providers/keycloak)
-- [Zitadel](/selfhosted/identity-providers/zitadel)
-- [All Providers →](/selfhosted/identity-providers)
-
-### Managing Connectors via API
-
-```bash
-# List configured connectors
-curl "https://netbird.example.com/api/identity-providers" \
- -H "Authorization: Bearer ${TOKEN}"
-
-# Add a Google connector
-curl -X POST "https://netbird.example.com/api/identity-providers" \
- -H "Authorization: Bearer ${TOKEN}" \
- -H "Content-Type: application/json" \
- -d '{
- "type": "google",
- "name": "Google Workspace",
- "client_id": "your-client-id.apps.googleusercontent.com",
- "client_secret": "your-client-secret"
- }'
-
-# Response includes redirect_url to configure in Google:
-{
- "id": "idp-abc123",
- "type": "google",
- "name": "Google Workspace",
- "client_id": "your-client-id.apps.googleusercontent.com",
- "issuer": "",
- "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
-}
-
-# Update a connector
-curl -X PUT "https://netbird.example.com/api/identity-providers/{id}" \
- -H "Authorization: Bearer ${TOKEN}" \
- -H "Content-Type: application/json" \
- -d '{
- "name": "Updated Name"
- }'
-
-# Delete a connector
-curl -X DELETE "https://netbird.example.com/api/identity-providers/{id}" \
- -H "Authorization: Bearer ${TOKEN}"
-```
-
-## Login Flow
-
-When embedded IdP is enabled with external connectors, the login page displays:
-
-1. **"Continue with Email"** - Local username/password authentication (always shown first)
-2. **External provider buttons** - One for each configured connector
-
-Users can choose their preferred authentication method.
-
-## Data Encryption
-
-The embedded IdP encrypts sensitive user data at rest:
-
-| Field | Encryption |
-|-------|------------|
-| Email | AES-256-GCM |
-| Name | AES-256-GCM |
-| Password | bcrypt hash (via Dex) |
-
-The encryption key is configured in `management.json` and should be:
-
-- Generated using a cryptographically secure random generator
-- Stored securely (not in version control)
-- Included in backup procedures
-- Rotated according to your security policies
-
-## Troubleshooting
-
-### "Embedded IdP not available" error
-
-Ensure `EmbeddedIdP.Enabled` is `true` in `management.json` and the Management service has been restarted.
-
-### Users can't log in
-
-1. Check Management service logs: `docker compose logs management`
-2. Verify the encryption key hasn't changed
-3. Confirm the user exists: Check **Team** → **Users** in Dashboard
-
-### External connector not working
-
-1. Verify Client ID and Secret are correct
-2. Check redirect URIs are properly configured in the external IdP
-3. Review Management logs for OIDC/SAML errors
-
-### Password reset
-
-Use the management CLI:
-
-```bash
-docker compose exec management /go/bin/netbird-mgmt users reset-password \
- --email user@example.com \
- --new-password "newpassword123"
-```
-
-## Security Considerations
-
-### Password Requirements
-
-Default password requirements for local users:
-
-- Minimum 8 characters
-- No specific complexity requirements (consider your security policy)
-
-### Session Management
-
-- JWT tokens are issued upon successful authentication
-- Token expiration follows OIDC best practices
-- Device authorization flow available for CLI clients
-
-### Audit Logging
-
-User authentication events are logged in the activity log:
-
-- Login attempts (successful and failed)
-- User creation/deletion
-- Connector configuration changes
-- Password resets
-
-## Comparison with External IdP
-
-| Feature | Embedded IdP | External IdP |
-|---------|--------------|--------------|
-| Setup complexity | Minimal | Moderate to High |
-| Resource requirements | Low (~1GB RAM) | Higher (2-4GB+ RAM) |
-| Additional containers | None | IdP + Database |
-| User management | Dashboard/API | External IdP console |
-| External SSO | Via connectors | Native |
-| SCIM provisioning | Not available | Available (Enterprise) |
-| MFA | Via external connectors | Native IdP feature |
-| Backup complexity | Single database | Multiple databases |
-
-## Disabling Embedded IdP
-
-To switch from embedded IdP to an external IdP:
-
-1. Configure your external IdP following the [Advanced guide](/selfhosted/selfhosted-guide)
-2. Update `management.json`:
-
- ```json
- {
- "EmbeddedIdP": {
- "Enabled": false
- },
- "HttpConfig": {
- "OIDCConfigEndpoint": "https://your-idp.example.com/.well-known/openid-configuration"
- }
- }
- ```
-
-3. Restart the Management service
-4. Users will need to re-authenticate with the new IdP
-
-
-Disabling the embedded IdP will invalidate all local user accounts. Ensure users have accounts in the external IdP before switching.
-
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/idp-connectors.mdx b/src/pages/selfhosted/identity-providers/idp-connectors.mdx
deleted file mode 100644
index 92bea8dbc..000000000
--- a/src/pages/selfhosted/identity-providers/idp-connectors.mdx
+++ /dev/null
@@ -1,125 +0,0 @@
-# External Identity Providers
-
-NetBird supports connecting **multiple external identity providers** alongside local user management. This allows users to sign in with their existing accounts from services like Google, Microsoft, or your corporate identity provider—while still maintaining the option for local username/password authentication.
-
-## Why Add External Identity Providers?
-
-External identity providers give you:
-
-- **Single Sign-On (SSO)** - Users authenticate with familiar credentials
-- **Multiple providers** - Configure as many OIDC-compatible providers as you need
-- **Federation** - Multiple identity sources, single NetBird account
-- **Flexibility** - Mix local users with SSO authentication
-- **Gradual adoption** - Start with local users, add SSO providers later
-
-## Supported Providers
-
-| Provider | Type | Best For |
-|----------|------|----------|
-| [**Google**](/selfhosted/identity-providers/google) | `google` | Google Workspace, personal Google accounts |
-| [**Microsoft**](/selfhosted/identity-providers/microsoft) | `microsoft` / `entra` | Personal accounts, Azure AD / Entra ID |
-| [**Okta**](/selfhosted/identity-providers/okta) | `okta` | Enterprise SSO |
-| [**Zitadel**](/selfhosted/identity-providers/zitadel) | `zitadel` | Self-hosted Zitadel |
-| [**Keycloak**](/selfhosted/identity-providers/keycloak) | `oidc` | Self-hosted Keycloak |
-| [**Authentik**](/selfhosted/identity-providers/authentik) | `oidc` | Self-hosted Authentik |
-| [**PocketID**](/selfhosted/identity-providers/pocketid) | `pocketid` | Lightweight self-hosted IdP |
-| [**Generic OIDC**](/selfhosted/identity-providers/generic-oidc) | `oidc` | Any OIDC-compliant provider |
-
-## Adding an Identity Provider
-
-### Via Dashboard
-
-1. Log in to your NetBird Dashboard
-2. Navigate to **Settings** → **Identity Providers**
-3. Click **Add Identity Provider**
-4. Select your provider type and fill in the required fields
-5. Click **Save**
-6. Copy the **Redirect URL** and configure it in your identity provider
-
-
-The Identity Providers tab is only visible when local user management is enabled (default for new installations).
-
-
-### Via API
-
-```bash
-curl -X POST "https://netbird.example.com/api/identity-providers" \
- -H "Authorization: Bearer ${TOKEN}" \
- -H "Content-Type: application/json" \
- -d '{
- "type": "oidc",
- "name": "My SSO Provider",
- "client_id": "your-client-id",
- "client_secret": "your-client-secret",
- "issuer": "https://sso.example.com"
- }'
-```
-
-See the [API Reference](/selfhosted/identity-providers/api-reference) for complete documentation.
-
-## Common Configuration Fields
-
-All connectors require:
-
-| Field | Description |
-|-------|-------------|
-| **Name** | Display name shown on the login button |
-| **Client ID** | OAuth client identifier from your provider |
-| **Client Secret** | OAuth client secret from your provider |
-
-Some providers also require:
-
-| Field | Required For | Description |
-|-------|--------------|-------------|
-| **Issuer** | Okta, Zitadel, PocketID, OIDC | The OIDC issuer URL |
-
-## How It Works
-
-1. User clicks the provider button on the login page
-2. User is redirected to the identity provider to authenticate
-3. After successful authentication, user is redirected back to NetBird
-4. NetBird validates the token and creates/updates the user account
-5. User is logged in and can access the Dashboard
-
-Users who authenticate via a connector appear in your Users list with a badge showing their identity provider.
-
-## Multiple Identity Providers
-
-You can configure **multiple identity providers simultaneously**:
-
-- All configured providers appear as buttons on the login page
-- "Continue with Email" (local authentication) is always available first
-- Users can authenticate with any configured provider
-- Each user's provider is tracked and displayed in the Dashboard
-
-This allows you to support different authentication methods for different user groups—for example, Google for contractors and Microsoft Entra ID for employees.
-
-## Best Practices
-
-1. **Start simple** - Begin with local users, add external providers as needed
-2. **Test thoroughly** - Verify the provider works before announcing to users
-3. **Communicate changes** - Let users know about new login options
-4. **Keep a fallback** - Local authentication remains available if an external provider has issues
-
-## Troubleshooting
-
-### Provider not appearing on login page
-
-- Verify the provider was saved successfully in Settings → Identity Providers
-- Check that the provider is enabled
-- Clear browser cache and reload the login page
-
-### "Invalid redirect URI" error
-
-- Copy the exact Redirect URL from NetBird after creating the provider
-- Ensure no trailing slashes or typos
-- Some providers are case-sensitive
-
-### Authentication succeeds but user not created
-
-- Check Management service logs for errors
-- Verify the token contains required claims (email, name)
-- Ensure the user's email domain is not blocked by any policies
-
-For provider-specific troubleshooting, see the individual provider pages.
-
diff --git a/src/pages/selfhosted/identity-providers/index.mdx b/src/pages/selfhosted/identity-providers/index.mdx
index d2a8fdcfd..237ea195c 100644
--- a/src/pages/selfhosted/identity-providers/index.mdx
+++ b/src/pages/selfhosted/identity-providers/index.mdx
@@ -2,24 +2,6 @@
NetBird's self-hosted implementation uses the OpenID Connect (OIDC) protocol for authentication, an industry-standard identity layer built on top of OAuth 2.0. OIDC is used both for user authentication to access the Management Service Dashboard and for user device authorization when accessing internal resources.
-## Local User Management
-
-Starting with version X.XX, NetBird **no longer requires an external identity provider**. The Management service now supports creating and managing local users directly, so you can get started without setting up Zitadel, Keycloak, or any other IdP.
-
-With local user management, you can:
-
-- **Create local users** directly from the NetBird Dashboard
-- **Add external identity providers** (Google, Microsoft, Okta, etc.) through the Dashboard UI
-- **Configure multiple IdPs** simultaneously—users see all providers as login options
-- **Simplify your deployment** with fewer containers and reduced resource requirements
-- **Get started faster** with no additional IdP setup required
-
-
-Local user management is powered by an embedded [Dex](https://dexidp.io/) server running within the NetBird Management service, requiring no additional containers or databases.
-
-
-[Get Started →](/selfhosted/selfhosted-quickstart)
-
## How Authentication Works
When a user attempts to access the NetBird network, the Management Service handles authentication through the configured identity provider. After successful authentication, a JSON Web Token (JWT) is issued containing the user's identity and claims. NetBird's Management Service validates this token and uses it to authenticate the user without ever storing passwords or sensitive credentials.
@@ -49,7 +31,7 @@ The simplest approach—create and manage users directly in NetBird:
- User management through the Dashboard
- Ideal for homelabs, small teams, and proof-of-concept deployments
-[Setup Guide →](/selfhosted/identity-providers/embedded-idp)
+See the [Local User Management](#local-user-management) section below for setup details.
### Local Users + External Identity Providers
@@ -61,7 +43,7 @@ Combine local user management with your existing identity providers:
- Configure everything directly from the Dashboard UI
- Best of both worlds
-[About External IdPs →](/selfhosted/identity-providers/idp-connectors)
+See the [Adding External Identity Providers](#adding-external-identity-providers) section below for setup details.
### Standalone IdP (Advanced)
@@ -76,13 +58,559 @@ For organizations with specific requirements or existing IdP investments:
---
+
+## Local User Management
+
+NetBird's Management service includes built-in user management, allowing you to create and manage local users directly without requiring an external identity provider. This functionality is powered by an embedded [Dex](https://dexidp.io/) server.
+
+Starting with version X.XX, NetBird **no longer requires an external identity provider**. The Management service now supports creating and managing local users directly, so you can get started without setting up Zitadel, Keycloak, or any other IdP.
+
+With local user management, you can:
+
+- **Create local users** directly from the NetBird Dashboard
+- **Add external identity providers** (Google, Microsoft, Okta, etc.) through the Dashboard UI
+- **Configure multiple IdPs** simultaneously—users see all providers as login options
+- **Simplify your deployment** with fewer containers and reduced resource requirements
+- **Get started faster** with no additional IdP setup required
+
+
+Local user management is powered by an embedded [Dex](https://dexidp.io/) server running within the NetBird Management service, requiring no additional containers or databases.
+
+
+[Get Started →](/selfhosted/selfhosted-quickstart)
+
+### Overview
+
+The Management service provides:
+
+- **Local user management** - Create users with email/password authentication directly in NetBird
+- **No external IdP required** - Works out of the box, no Zitadel, Keycloak, or other IdP needed
+- **External identity provider support** - Optionally connect one or more OIDC-compatible providers (Google, Microsoft, Okta, etc.)
+- **Multiple IdP support** - Configure multiple external identity providers simultaneously
+- **Device authentication** - CLI authentication via device authorization flow
+- **Secure storage** - AES-256-GCM encryption for sensitive user data at rest
+
+### When to Use Local Users
+
+Local user management is ideal for:
+
+| Use Case | Why Local Users Work |
+|----------|----------------------|
+| **Homelabs** | Simple setup, minimal resources, no external dependencies |
+| **Small teams** | Easy user management, quick onboarding |
+| **Proof of concept** | Get started in minutes, upgrade path available |
+| **Air-gapped environments** | No external service dependencies |
+| **Development/testing** | Fast iteration, simple reset |
+
+Consider a [standalone external IdP](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp) if you need:
+
+- SCIM user provisioning (Enterprise feature)
+- Complex user lifecycle management
+- Integration with existing enterprise SSO infrastructure
+- Specific IdP features not available via OIDC connectors
+
+### Architecture
+
+With local user management enabled, the architecture is simplified:
+
+```
+ NetBird Management
+┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐
+│ Management │ │ Embedded Dex │ │ Dashboard │
+│ Service │◄─┤ IdP Server │◄─┤ API │
+└─────────────────┘ └─────────────────┘ └─────────────┘
+ │ │
+ ▼ ▼
+┌─────────────────────────────────────────────────────────┐
+│ SQLite/Postgres Database │
+│ (Users, Accounts, IdP Connectors) │
+└─────────────────────────────────────────────────────────┘
+```
+
+Compare this to the external IdP architecture which requires separate containers for the IdP and its database.
+
+
+### Configuration
+
+#### Enabling Embedded IdP
+
+The embedded IdP is enabled by default when using the new `getting-started.sh` quickstart script. For manual configuration, update your `management.json`:
+
+```json
+{
+ "EmbeddedIdP": {
+ "Enabled": true,
+ "DataDir": "/var/lib/netbird/idp"
+ },
+ "EncryptionKey": ""
+}
+```
+
+#### Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `EmbeddedIdP.Enabled` | Enable/disable the embedded IdP | `true` (quickstart) |
+| `EmbeddedIdP.DataDir` | Directory for IdP data storage | `/var/lib/netbird/idp` |
+| `EncryptionKey` | Base64-encoded AES-256 key for encrypting user data | Auto-generated |
+
+#### Environment Variables
+
+When using docker-compose, you can configure these via environment variables:
+
+```yaml
+environment:
+ - NETBIRD_EMBEDDED_IDP_ENABLED=true
+ - NETBIRD_EMBEDDED_IDP_DATA_DIR=/var/lib/netbird/idp
+ - NETBIRD_ENCRYPTION_KEY=${ENCRYPTION_KEY}
+```
+
+#### Generating an Encryption Key
+
+If you need to generate an encryption key manually:
+
+```bash
+openssl rand -base64 32
+```
+
+
+Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures.
+
+
+
+### User Management
+
+#### Creating Users via Dashboard
+
+When embedded IdP is enabled, the Dashboard shows a **"Create User"** button (instead of "Invite User" shown for cloud-hosted NetBird):
+
+1. Navigate to **Team** → **Users**
+2. Click **Create User**
+3. Fill in the user details:
+ - **Email** (required) - User's email address for login
+ - **Name** (required) - Display name
+ - **Groups** (optional) - Auto-assign to groups
+4. Click **Create**
+
+After creation, a modal displays with:
+- The **generated password** with a copy button
+- Warning: *"This password will only be shown once. Please copy it now."*
+- **Copy & Close** button to copy password and dismiss
+
+
+The generated password is only shown once at creation time. It cannot be retrieved later. Make sure to copy it and share it securely with the user.
+
+
+#### User IdP Badges
+
+In the Users table, each user shows a badge indicating their identity provider:
+- Users created locally show no badge (or "Local" badge)
+- Users who authenticated via an external connector show that provider's icon (Google, Microsoft, etc.)
+- The badge links to the `idp_id` field in the user record
+
+#### Creating Users via API
+
+```bash
+curl -X POST "https://netbird.example.com/api/users" \
+ -H "Authorization: Bearer ${TOKEN}" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "email": "user@example.com",
+ "name": "New User",
+ "auto_groups": ["group-id-1"]
+ }'
+```
+
+Response includes the generated password:
+
+```json
+{
+ "id": "user-abc123",
+ "email": "user@example.com",
+ "name": "New User",
+ "role": "user",
+ "status": "active",
+ "password": "generated-password-here"
+}
+```
+
+
+The `password` field is only included when creating users with embedded IdP. Store it immediately—it won't be returned in subsequent API calls.
+
+
+#### User Roles
+
+Users created through the embedded IdP can be assigned roles:
+
+| Role | Permissions |
+|------|-------------|
+| **Owner** | Full administrative access, cannot be demoted |
+| **Admin** | Manage users, peers, policies, and settings |
+| **User** | Connect devices, view assigned resources |
+
+
+### Instance Setup (First Run)
+
+When NetBird starts with the embedded IdP and no existing accounts, the Dashboard redirects to the `/setup` route and displays the **Instance Setup Wizard**:
+
+1. The Dashboard checks `GET /instance` for `setup_required: true`
+2. If setup is required, users are redirected to `/setup`
+3. The wizard collects:
+ - **Email address** (required)
+ - **Password** (required, minimum 8 characters)
+ - **Name** (optional)
+4. On submit, the owner account is created via `POST /instance/setup`
+5. User is redirected to login with the credentials they just created
+
+
+The `/setup` route is unauthenticated and only accessible when `setup_required` is true. Once setup is complete, accessing `/setup` returns a 412 error and redirects to login.
+
+
+#### Setup API
+
+For automated deployments, you can complete setup via API:
+
+```bash
+# Check if setup is required
+curl "https://netbird.example.com/api/instance"
+
+# Response when setup is needed:
+{
+ "setup_required": true
+}
+
+# Complete setup
+curl -X POST "https://netbird.example.com/api/instance/setup" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "email": "admin@example.com",
+ "password": "securepassword123",
+ "name": "Admin User"
+ }'
+
+# Response:
+{
+ "user_id": "user-abc123",
+ "account_id": "account-xyz789"
+}
+```
+
+### Data Encryption
+
+The embedded IdP encrypts sensitive user data at rest:
+
+| Field | Encryption |
+|-------|------------|
+| Email | AES-256-GCM |
+| Name | AES-256-GCM |
+| Password | bcrypt hash (via Dex) |
+
+The encryption key is configured in `management.json` and should be:
+
+- Generated using a cryptographically secure random generator
+- Stored securely (not in version control)
+- Included in backup procedures
+- Rotated according to your security policies
+
+### Security Considerations
+
+#### Password Requirements
+
+Default password requirements for local users:
+
+- Minimum 8 characters
+- No specific complexity requirements (consider your security policy)
+
+#### Session Management
+
+- JWT tokens are issued upon successful authentication
+- Token expiration follows OIDC best practices
+- Device authorization flow available for CLI clients
+
+#### Audit Logging
+
+User authentication events are logged in the activity log:
+
+- Login attempts (successful and failed)
+- User creation/deletion
+- Connector configuration changes
+- Password resets
+
+### Troubleshooting
+
+#### "Embedded IdP not available" error
+
+Ensure `EmbeddedIdP.Enabled` is `true` in `management.json` and the Management service has been restarted.
+
+#### Users can't log in
+
+1. Check Management service logs: `docker compose logs management`
+2. Verify the encryption key hasn't changed
+3. Confirm the user exists: Check **Team** → **Users** in Dashboard
+
+#### Password reset
+
+Use the management CLI:
+
+```bash
+docker compose exec management /go/bin/netbird-mgmt users reset-password \
+ --email user@example.com \
+ --new-password "newpassword123"
+```
+
+### Comparison with External IdP
+
+| Feature | Embedded IdP | External IdP |
+|---------|--------------|--------------|
+| Setup complexity | Minimal | Moderate to High |
+| Resource requirements | Low (~1GB RAM) | Higher (2-4GB+ RAM) |
+| Additional containers | None | IdP + Database |
+| User management | Dashboard/API | External IdP console |
+| External SSO | Via connectors | Native |
+| SCIM provisioning | Not available | Available (Enterprise) |
+| MFA | Via external connectors | Native IdP feature |
+| Backup complexity | Single database | Multiple databases |
+
+### Disabling Embedded IdP
+
+To switch from embedded IdP to an external IdP:
+
+1. Configure your external IdP following the [Advanced guide](/selfhosted/selfhosted-guide)
+2. Update `management.json`:
+
+ ```json
+ {
+ "EmbeddedIdP": {
+ "Enabled": false
+ },
+ "HttpConfig": {
+ "OIDCConfigEndpoint": "https://your-idp.example.com/.well-known/openid-configuration"
+ }
+ }
+ ```
+
+3. Restart the Management service
+4. Users will need to re-authenticate with the new IdP
+
+
+Disabling the embedded IdP will invalidate all local user accounts. Ensure users have accounts in the external IdP before switching.
+
+
+---
+
+
+## Adding External Identity Providers
+
+NetBird supports connecting **multiple external identity providers** alongside local user management. This allows users to sign in with their existing accounts from services like Google, Microsoft, or your corporate identity provider—while still maintaining the option for local username/password authentication.
+
+### Why Add External Identity Providers?
+
+External identity providers give you:
+
+- **Single Sign-On (SSO)** - Users authenticate with familiar credentials
+- **Multiple providers** - Configure as many OIDC-compatible providers as you need
+- **Federation** - Multiple identity sources, single NetBird account
+- **Flexibility** - Mix local users with SSO authentication
+- **Gradual adoption** - Start with local users, add SSO providers later
+
+### Supported Providers
+
+| Provider | Type | Best For |
+|----------|------|----------|
+| [**Generic OIDC**](#adding-external-identity-providers) | `oidc` | Any OIDC-compliant provider |
+| [**Google**](/selfhosted/identity-providers/google) | `google` | Google Workspace, personal Google accounts |
+| [**Microsoft**](/selfhosted/identity-providers/microsoft) | `microsoft` / `entra` | Personal accounts, Azure AD / Entra ID |
+| [**Okta**](/selfhosted/identity-providers/okta) | `okta` | Enterprise SSO |
+| [**Zitadel**](/selfhosted/identity-providers/zitadel) | `zitadel` | Self-hosted Zitadel |
+| [**Keycloak**](/selfhosted/identity-providers/keycloak) | `oidc` | Self-hosted Keycloak |
+| [**Authentik**](/selfhosted/identity-providers/authentik) | `oidc` | Self-hosted Authentik |
+| [**PocketID**](/selfhosted/identity-providers/pocketid) | `pocketid` | Lightweight self-hosted IdP |
+
+### Adding an Identity Provider
+
+#### Via Dashboard
+
+1. Log in to your NetBird Dashboard
+2. Navigate to **Settings** → **Identity Providers**
+3. Click **Add Identity Provider**
+4. Select your provider type from the dropdown
+5. Configure the required fields:
+ - **Name** - Display name for the login button
+ - **Client ID** - From your identity provider
+ - **Client Secret** - From your identity provider
+ - **Issuer** - Required for Okta, Zitadel, PocketID, and generic OIDC
+6. Click **Save**
+7. Copy the **Redirect URL** and configure it in your identity provider
+
+After saving, a modal displays the **Redirect URL** that you must configure in your identity provider's OAuth settings. Copy this URL before closing.
+
+
+The Identity Providers tab is only visible when `embedded_idp_enabled` is `true` in your account settings (default for new installations).
+
+
+For detailed setup instructions for each provider, see the individual provider pages:
+- [Google](/selfhosted/identity-providers/google)
+- [Microsoft](/selfhosted/identity-providers/microsoft)
+- [Keycloak](/selfhosted/identity-providers/keycloak)
+- [Zitadel](/selfhosted/identity-providers/zitadel)
+- [All Providers →](/selfhosted/identity-providers)
+
+#### Via API
+
+```bash
+curl -X POST "https://netbird.example.com/api/identity-providers" \
+ -H "Authorization: Bearer ${TOKEN}" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "type": "oidc",
+ "name": "My SSO Provider",
+ "client_id": "your-client-id",
+ "client_secret": "your-client-secret",
+ "issuer": "https://sso.example.com"
+ }'
+```
+
+See the [API Reference](/selfhosted/identity-providers/api-reference) for complete documentation.
+
+### Managing Connectors via API
+
+```bash
+# List configured connectors
+curl "https://netbird.example.com/api/identity-providers" \
+ -H "Authorization: Bearer ${TOKEN}"
+
+# Add a Google connector
+curl -X POST "https://netbird.example.com/api/identity-providers" \
+ -H "Authorization: Bearer ${TOKEN}" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "type": "google",
+ "name": "Google Workspace",
+ "client_id": "your-client-id.apps.googleusercontent.com",
+ "client_secret": "your-client-secret"
+ }'
+
+# Response includes redirect_url to configure in Google:
+{
+ "id": "idp-abc123",
+ "type": "google",
+ "name": "Google Workspace",
+ "client_id": "your-client-id.apps.googleusercontent.com",
+ "issuer": "",
+ "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
+}
+
+# Update a connector
+curl -X PUT "https://netbird.example.com/api/identity-providers/{id}" \
+ -H "Authorization: Bearer ${TOKEN}" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Updated Name"
+ }'
+
+# Delete a connector
+curl -X DELETE "https://netbird.example.com/api/identity-providers/{id}" \
+ -H "Authorization: Bearer ${TOKEN}"
+```
+
+### Common Configuration Fields
+
+All connectors require:
+
+| Field | Description |
+|-------|-------------|
+| **Name** | Display name shown on the login button |
+| **Client ID** | OAuth client identifier from your provider |
+| **Client Secret** | OAuth client secret from your provider |
+
+Some providers also require:
+
+| Field | Required For | Description |
+|-------|--------------|-------------|
+| **Issuer** | Okta, Zitadel, PocketID, OIDC | The OIDC issuer URL |
+
+### How It Works
+
+1. User clicks the provider button on the login page
+2. User is redirected to the identity provider to authenticate
+3. After successful authentication, user is redirected back to NetBird
+4. NetBird validates the token and creates/updates the user account
+5. User is logged in and can access the Dashboard
+
+Users who authenticate via a connector appear in your Users list with a badge showing their identity provider.
+
+### Multiple Identity Providers
+
+You can configure **multiple identity providers simultaneously**:
+
+- All configured providers appear as buttons on the login page
+- "Continue with Email" (local authentication) is always available first
+- Users can authenticate with any configured provider
+- Each user's provider is tracked and displayed in the Dashboard
+
+This allows you to support different authentication methods for different user groups—for example, Google for contractors and Microsoft Entra ID for employees.
+
+### Login Flow
+
+When embedded IdP is enabled with external connectors, the login page displays:
+
+1. **"Continue with Email"** - Local username/password authentication (always shown first)
+2. **External provider buttons** - One for each configured connector
+
+Users can choose their preferred authentication method.
+
+### Best Practices
+
+1. **Start simple** - Begin with local users, add external providers as needed
+2. **Test thoroughly** - Verify the provider works before announcing to users
+3. **Communicate changes** - Let users know about new login options
+4. **Keep a fallback** - Local authentication remains available if an external provider has issues
+
+### Troubleshooting
+
+#### Provider not appearing on login page
+
+- Verify the provider was saved successfully in Settings → Identity Providers
+- Check that the provider is enabled
+- Clear browser cache and reload the login page
+
+#### "Invalid redirect URI" error
+
+- Copy the exact Redirect URL from NetBird after creating the provider
+- Ensure no trailing slashes or typos
+- Some providers are case-sensitive
+
+#### Authentication succeeds but user not created
+
+- Check Management service logs for errors
+- Verify the token contains required claims (email, name)
+- Ensure the user's email domain is not blocked by any policies
+
+#### External connector not working
+
+1. Verify Client ID and Secret are correct
+2. Check redirect URIs are properly configured in the external IdP
+3. Review Management logs for OIDC/SAML errors
+
+For provider-specific troubleshooting, see the individual provider pages.
+
+---
+
## Identity Provider Options
-Each provider page includes both **connector setup** (recommended, for adding to local user management) and **standalone setup** (advanced) instructions.
+Each provider page includes specific setup instructions for both **connector setup** (recommended, for adding to local user management) and **standalone setup** (advanced).
+
+### Generic OIDC
+
+Any identity provider that supports OpenID Connect can be integrated with NetBird. If your provider isn't listed below, use the generic OIDC configuration.
+
+| Provider | Description |
+|----------|-------------|
+| [**Generic OIDC**](#adding-external-identity-providers) | Connect any OIDC-compliant identity provider |
### Self-Hosted Providers
-Self-hosted Identity Providers give you full control over authentication and authorization.
+Self-hosted Identity Providers give you full control over authentication and authorization. See each provider's page for specific configuration instructions.
| Provider | Description |
|----------|-------------|
@@ -93,7 +621,7 @@ Self-hosted Identity Providers give you full control over authentication and aut
### Cloud/Managed Providers
-Managed Identity Providers handle infrastructure and maintenance for you.
+Managed Identity Providers handle infrastructure and maintenance for you. See each provider's page for specific configuration instructions.
| Provider | Description |
|----------|-------------|
@@ -119,6 +647,4 @@ If you have an existing NetBird deployment using a standalone IdP (like Zitadel
User data and network configurations are preserved during migration. Only authentication changes—users may need to re-authenticate after the switch.
-
-
-[Detailed Migration Guide →](/selfhosted/identity-providers/migration)
\ No newline at end of file
+
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/keycloak.mdx b/src/pages/selfhosted/identity-providers/keycloak.mdx
index 1ac2aa6df..5c58c93d3 100644
--- a/src/pages/selfhosted/identity-providers/keycloak.mdx
+++ b/src/pages/selfhosted/identity-providers/keycloak.mdx
@@ -73,7 +73,7 @@ Users who authenticate via Keycloak will appear in your NetBird Users list with
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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+For most deployments, the [embedded IdP](/selfhosted/identity-providers#local-user-management) 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 [Connector Setup (Recommended)](#connector-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/auth0).
@@ -320,5 +320,5 @@ You've configured all required resources in Keycloak. Continue with the [NetBird
## Related Resources
- [Keycloak Documentation](https://www.keycloak.org/documentation)
-- [Embedded IdP Overview](/selfhosted/identity-providers/embedded-idp)
+- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
- [API Reference](/selfhosted/identity-providers/api-reference)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/auth0.mdx b/src/pages/selfhosted/identity-providers/managed/auth0.mdx
index 7ed9faf52..87b36937a 100644
--- a/src/pages/selfhosted/identity-providers/managed/auth0.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/auth0.mdx
@@ -65,7 +65,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+For most deployments, the [embedded IdP](/selfhosted/identity-providers#local-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
@@ -242,4 +242,4 @@ You've configured all required resources in Auth0. Continue with the [NetBird Se
- [Auth0 Documentation](https://auth0.com/docs/)
- [Auth0 Dashboard](https://manage.auth0.com/)
-- [Embedded IdP Overview](/selfhosted/identity-providers/embedded-idp)
\ No newline at end of file
+- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
index 8154ba1c9..d03c18fab 100644
--- a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
@@ -86,7 +86,7 @@ Domain restrictions are configured in Google Cloud Console, not in NetBird.
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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+For most deployments, the [embedded IdP](/selfhosted/identity-providers#local-user-management) 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 [Connector Setup (Recommended)](#connector-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.
@@ -291,4 +291,4 @@ You've configured all required resources in Google Workspace. Continue with the
- [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/embedded-idp)
\ No newline at end of file
+- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx b/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
index 9f0c5cf8d..c5d6738d8 100644
--- a/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
@@ -75,7 +75,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+For most deployments, the [embedded IdP](/selfhosted/identity-providers#local-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
### Prerequisites
@@ -251,4 +251,4 @@ You've configured all required resources in JumpCloud. Continue with the [NetBir
- [JumpCloud Documentation](https://jumpcloud.com/support)
- [JumpCloud Admin Console](https://console.jumpcloud.com/)
-- [Embedded IdP Overview](/selfhosted/identity-providers/embedded-idp)
\ No newline at end of file
+- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx b/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
index e5ed03057..ce37eb827 100644
--- a/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
@@ -91,7 +91,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+For most deployments, the [embedded IdP](/selfhosted/identity-providers#local-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
@@ -277,4 +277,4 @@ You've configured all required resources in Azure AD. Continue with the [NetBird
- [Microsoft Identity Platform Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/)
- [Azure Portal](https://portal.azure.com/)
-- [Embedded IdP Overview](/selfhosted/identity-providers/embedded-idp)
\ No newline at end of file
+- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/okta.mdx b/src/pages/selfhosted/identity-providers/managed/okta.mdx
index 86f0b2dc2..10ce517e6 100644
--- a/src/pages/selfhosted/identity-providers/managed/okta.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/okta.mdx
@@ -68,7 +68,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
Use Okta 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 Okta administrators as it also requires additional setup and ongoing maintenance.
-For most deployments, the [embedded IdP](/selfhosted/identity-providers/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+For most deployments, the [embedded IdP](/selfhosted/identity-providers#local-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
@@ -231,4 +231,4 @@ You've configured all required resources in Okta. Continue with the [NetBird Sel
- [Okta Developer Documentation](https://developer.okta.com/docs/)
- [Okta Admin Console](https://help.okta.com/en/prod/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm)
-- [Embedded IdP Overview](/selfhosted/identity-providers/embedded-idp)
\ No newline at end of file
+- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/pocketid.mdx b/src/pages/selfhosted/identity-providers/pocketid.mdx
index be37fb960..b9fb805aa 100644
--- a/src/pages/selfhosted/identity-providers/pocketid.mdx
+++ b/src/pages/selfhosted/identity-providers/pocketid.mdx
@@ -69,7 +69,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+For most deployments, the [embedded IdP](/selfhosted/identity-providers#local-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
### Prerequisites
@@ -178,5 +178,5 @@ You've configured all required resources in PocketID. Continue with the [NetBird
## Related Resources
- [PocketID Documentation](https://pocket-id.org/docs)
-- [Embedded IdP Overview](/selfhosted/identity-providers/embedded-idp)
+- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
- [API Reference](/selfhosted/identity-providers/api-reference)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/zitadel.mdx b/src/pages/selfhosted/identity-providers/zitadel.mdx
index 7eece79db..e6481ea4f 100644
--- a/src/pages/selfhosted/identity-providers/zitadel.mdx
+++ b/src/pages/selfhosted/identity-providers/zitadel.mdx
@@ -72,7 +72,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
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/embedded-idp) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+For most deployments, the [embedded IdP](/selfhosted/identity-providers#local-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
If you prefer not to self-host, Zitadel offers a managed cloud option at [zitadel.com](https://zitadel.com/).
@@ -285,5 +285,5 @@ If you deployed NetBird using the previous quickstart script with Zitadel:
- [Zitadel Documentation](https://zitadel.com/docs)
- [Zitadel GitHub](https://github.com/zitadel/zitadel)
-- [Embedded IdP Overview](/selfhosted/identity-providers/embedded-idp)
+- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
- [Migration Guide](/selfhosted/identity-providers/migration)
\ No newline at end of file
diff --git a/src/pages/selfhosted/selfhosted-quickstart.mdx b/src/pages/selfhosted/selfhosted-quickstart.mdx
index 3a7ec2f84..b89f02ce7 100644
--- a/src/pages/selfhosted/selfhosted-quickstart.mdx
+++ b/src/pages/selfhosted/selfhosted-quickstart.mdx
@@ -14,20 +14,11 @@ We run NetBird in the cloud, and it will take a few clicks to get started with o
## Quick self-hosting
-Starting with version X.XX, NetBird **no longer requires an external identity provider**. The Management service now supports creating and managing local users directly, so you can get started without setting up Zitadel, Keycloak, or any other IdP.
-
This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM.
-For advanced setups with standalone IdPs, see the [Advanced guide](/selfhosted/selfhosted-guide).
+For advanced setups, see the [Advanced guide](/selfhosted/selfhosted-guide).
-### What you get
-
-- **Local user management** - Create and manage users directly in the Dashboard
-- **No external IdP required** - Works out of the box without Zitadel, Keycloak, or any other identity provider
-- **Optional SSO integration** - Connect one or more external identity providers (Google, Microsoft, Okta, etc.) if needed
-- **Multiple IdP support** - Configure multiple OIDC-compatible identity providers simultaneously
-
### Requirements
**Infrastructure requirements:**
@@ -67,10 +58,10 @@ The script deploys NetBird **without any users**. Once complete, you'll need to
2. You'll be redirected to the setup page (`/setup`)
3. Create your admin account:
- Enter your email address
- - Set a secure password
+ - Enter your name
- Click **Create Account**
-This creates the owner account for your NetBird instance. You'll be logged in automatically and can start using the Dashboard.
+A password will be generated and displayed. Copy it securely—it will only be shown once. You can then log in with your email and the generated password.
The `/setup` page is only accessible when no users exist. After creating the first user, it redirects to the regular login page.
From cffcad149d2d3890f3ffe08d372596202bd493d1 Mon Sep 17 00:00:00 2001
From: Brandon Hopkins
Date: Mon, 5 Jan 2026 22:39:28 -0800
Subject: [PATCH 07/18] Fix Links
---
.../identity-providers/authentik.mdx | 2 +-
.../selfhosted/identity-providers/index.mdx | 21 ++++++++++---------
.../identity-providers/keycloak.mdx | 2 +-
.../selfhosted/identity-providers/zitadel.mdx | 2 +-
src/pages/selfhosted/selfhosted-guide.mdx | 12 +++++------
.../selfhosted/selfhosted-quickstart.mdx | 2 +-
6 files changed, 21 insertions(+), 20 deletions(-)
diff --git a/src/pages/selfhosted/identity-providers/authentik.mdx b/src/pages/selfhosted/identity-providers/authentik.mdx
index 23c4aeb6f..b5e37011a 100644
--- a/src/pages/selfhosted/identity-providers/authentik.mdx
+++ b/src/pages/selfhosted/identity-providers/authentik.mdx
@@ -91,7 +91,7 @@ Use Authentik as your primary identity provider instead of NetBird's embedded Id
For most deployments, the [embedded IdP](/selfhosted/identity-providers#local-user-management) 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 [Connector Setup (Recommended)](#connector-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/auth0).
+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
diff --git a/src/pages/selfhosted/identity-providers/index.mdx b/src/pages/selfhosted/identity-providers/index.mdx
index 237ea195c..7618197cf 100644
--- a/src/pages/selfhosted/identity-providers/index.mdx
+++ b/src/pages/selfhosted/identity-providers/index.mdx
@@ -418,9 +418,9 @@ External identity providers give you:
| Provider | Type | Best For |
|----------|------|----------|
| [**Generic OIDC**](#adding-external-identity-providers) | `oidc` | Any OIDC-compliant provider |
-| [**Google**](/selfhosted/identity-providers/google) | `google` | Google Workspace, personal Google accounts |
-| [**Microsoft**](/selfhosted/identity-providers/microsoft) | `microsoft` / `entra` | Personal accounts, Azure AD / Entra ID |
-| [**Okta**](/selfhosted/identity-providers/okta) | `okta` | Enterprise SSO |
+| [**Google**](/selfhosted/identity-providers/managed/google-workspace) | `google` | Google Workspace, personal Google accounts |
+| [**Microsoft**](/selfhosted/identity-providers/managed/microsoft-entra-id) | `microsoft` / `entra` | Personal accounts, Azure AD / Entra ID |
+| [**Okta**](/selfhosted/identity-providers/managed/okta) | `okta` | Enterprise SSO |
| [**Zitadel**](/selfhosted/identity-providers/zitadel) | `zitadel` | Self-hosted Zitadel |
| [**Keycloak**](/selfhosted/identity-providers/keycloak) | `oidc` | Self-hosted Keycloak |
| [**Authentik**](/selfhosted/identity-providers/authentik) | `oidc` | Self-hosted Authentik |
@@ -449,8 +449,8 @@ The Identity Providers tab is only visible when `embedded_idp_enabled` is `true`
For detailed setup instructions for each provider, see the individual provider pages:
-- [Google](/selfhosted/identity-providers/google)
-- [Microsoft](/selfhosted/identity-providers/microsoft)
+- [Google Workspace](/selfhosted/identity-providers/managed/google-workspace)
+- [Microsoft Entra ID](/selfhosted/identity-providers/managed/microsoft-entra-id)
- [Keycloak](/selfhosted/identity-providers/keycloak)
- [Zitadel](/selfhosted/identity-providers/zitadel)
- [All Providers →](/selfhosted/identity-providers)
@@ -625,11 +625,11 @@ Managed Identity Providers handle infrastructure and maintenance for you. See ea
| Provider | Description |
|----------|-------------|
-| [**Google**](/selfhosted/identity-providers/google) | Google accounts and Google Workspace authentication |
-| [**Microsoft**](/selfhosted/identity-providers/microsoft) | Microsoft personal accounts and Entra ID (Azure AD) for work accounts |
-| [**Okta**](/selfhosted/identity-providers/okta) | Enterprise identity and access management with extensive integrations |
-| [**Auth0**](/selfhosted/identity-providers/auth0) | Flexible authentication service with customization options |
-| [**JumpCloud**](/selfhosted/identity-providers/jumpcloud) | Cloud directory platform with identity and device management |
+| [**Google Workspace**](/selfhosted/identity-providers/managed/google-workspace) | Google accounts and Google Workspace authentication |
+| [**Microsoft Entra ID**](/selfhosted/identity-providers/managed/microsoft-entra-id) | Microsoft personal accounts and Entra ID (Azure AD) for work accounts |
+| [**Okta**](/selfhosted/identity-providers/managed/okta) | Enterprise identity and access management with extensive integrations |
+| [**Auth0**](/selfhosted/identity-providers/managed/auth0) | Flexible authentication service with customization options |
+| [**JumpCloud**](/selfhosted/identity-providers/managed/jumpcloud) | Cloud directory platform with identity and device management |
---
@@ -637,6 +637,7 @@ Managed Identity Providers handle infrastructure and maintenance for you. See ea
In addition to OIDC-based authentication, NetBird supports provisioning users and groups through SCIM and the API. However, this functionality is not available in the open source Community Edition. It is offered only in the cloud-managed version of NetBird or through a [Commercial License](https://netbird.io/pricing#on-prem) for enterprise self-hosted deployments.
+
## Migration Guide
If you have an existing NetBird deployment using a standalone IdP (like Zitadel from the previous quickstart), you have several options:
diff --git a/src/pages/selfhosted/identity-providers/keycloak.mdx b/src/pages/selfhosted/identity-providers/keycloak.mdx
index 5c58c93d3..33a3b3dad 100644
--- a/src/pages/selfhosted/identity-providers/keycloak.mdx
+++ b/src/pages/selfhosted/identity-providers/keycloak.mdx
@@ -76,7 +76,7 @@ Use Keycloak as your primary identity provider instead of NetBird's embedded IdP
For most deployments, the [embedded IdP](/selfhosted/identity-providers#local-user-management) 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 [Connector Setup (Recommended)](#connector-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/auth0).
+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
diff --git a/src/pages/selfhosted/identity-providers/zitadel.mdx b/src/pages/selfhosted/identity-providers/zitadel.mdx
index e6481ea4f..e89a363c9 100644
--- a/src/pages/selfhosted/identity-providers/zitadel.mdx
+++ b/src/pages/selfhosted/identity-providers/zitadel.mdx
@@ -286,4 +286,4 @@ If you deployed NetBird using the previous quickstart script with Zitadel:
- [Zitadel Documentation](https://zitadel.com/docs)
- [Zitadel GitHub](https://github.com/zitadel/zitadel)
- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
-- [Migration Guide](/selfhosted/identity-providers/migration)
\ No newline at end of file
+- [Migration Guide](/selfhosted/identity-providers#migration-guide)
\ No newline at end of file
diff --git a/src/pages/selfhosted/selfhosted-guide.mdx b/src/pages/selfhosted/selfhosted-guide.mdx
index 893a458cc..faa7b2f89 100644
--- a/src/pages/selfhosted/selfhosted-guide.mdx
+++ b/src/pages/selfhosted/selfhosted-guide.mdx
@@ -144,11 +144,11 @@ Pick the one that suits your needs, follow the **Standalone Setup (Advanced)** s
- [PocketID](/selfhosted/identity-providers/pocketid) - Lightweight self-hosted option
**Managed options**
-- [Microsoft Entra ID](/selfhosted/identity-providers/microsoft) - Azure AD / Microsoft 365
-- [Google Workspace](/selfhosted/identity-providers/google) - Google accounts
-- [Okta](/selfhosted/identity-providers/okta) - Enterprise SSO
-- [Auth0](/selfhosted/identity-providers/auth0) - Flexible auth platform
-- [JumpCloud](/selfhosted/identity-providers/jumpcloud) - Cloud directory
+- [Microsoft Entra ID](/selfhosted/identity-providers/managed/microsoft-entra-id) - Azure AD / Microsoft 365
+- [Google Workspace](/selfhosted/identity-providers/managed/google-workspace) - Google accounts
+- [Okta](/selfhosted/identity-providers/managed/okta) - Enterprise SSO
+- [Auth0](/selfhosted/identity-providers/managed/auth0) - Flexible auth platform
+- [JumpCloud](/selfhosted/identity-providers/managed/jumpcloud) - Cloud directory
Each provider page includes both "Connector Setup" (for use with embedded IdP) and "Standalone Setup (Advanced)" sections. For this guide, follow the **Standalone Setup** section.
@@ -309,7 +309,7 @@ If you've deployed NetBird using this advanced guide and want to simplify your s
2. Users can continue logging in with their existing credentials
3. You can gradually transition to local user management
-See the [Migration Guide](/selfhosted/identity-providers/migration) for detailed instructions.
+See the [Migration Guide](/selfhosted/identity-providers#migration-guide) for detailed instructions.
## Get in touch
diff --git a/src/pages/selfhosted/selfhosted-quickstart.mdx b/src/pages/selfhosted/selfhosted-quickstart.mdx
index b89f02ce7..5c5b01241 100644
--- a/src/pages/selfhosted/selfhosted-quickstart.mdx
+++ b/src/pages/selfhosted/selfhosted-quickstart.mdx
@@ -225,7 +225,7 @@ If you have an existing Zitadel deployment and want to migrate:
1. **Option A**: Keep Zitadel as an external provider—add it as an identity provider in Settings
2. **Option B**: Recreate users as local users and decommission Zitadel
-See the [Migration Guide](/selfhosted/identity-providers/migration) for detailed steps.
+See the [Migration Guide](/selfhosted/identity-providers#migration-guide) for detailed steps.
---
From 9da8c2f54a825ce64653fddf415e445d0a63b1e9 Mon Sep 17 00:00:00 2001
From: Brandon Hopkins
Date: Mon, 5 Jan 2026 22:55:04 -0800
Subject: [PATCH 08/18] Remove API Reference
---
src/components/NavigationDocs.jsx | 1 -
.../identity-providers/api-reference.mdx | 490 ------------------
.../identity-providers/authentik.mdx | 2 +-
.../selfhosted/identity-providers/index.mdx | 2 +-
.../identity-providers/keycloak.mdx | 2 +-
.../identity-providers/pocketid.mdx | 2 +-
6 files changed, 4 insertions(+), 495 deletions(-)
delete mode 100644 src/pages/selfhosted/identity-providers/api-reference.mdx
diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx
index 39a2233b6..59ca480ef 100644
--- a/src/components/NavigationDocs.jsx
+++ b/src/components/NavigationDocs.jsx
@@ -288,7 +288,6 @@ export const docsNavigation = [
isOpen: false,
links: [
{ title: 'Using IdPs on Self-Hosted', href: '/selfhosted/identity-providers' },
- { title: 'API Reference', href: '/selfhosted/identity-providers/api-reference' },
{
title: 'Self-hosted IdPs',
isOpen: true,
diff --git a/src/pages/selfhosted/identity-providers/api-reference.mdx b/src/pages/selfhosted/identity-providers/api-reference.mdx
deleted file mode 100644
index e73fa247e..000000000
--- a/src/pages/selfhosted/identity-providers/api-reference.mdx
+++ /dev/null
@@ -1,490 +0,0 @@
-# Identity Provider API Reference
-
-This page documents the API endpoints for managing identity providers when using the [embedded IdP](/selfhosted/identity-providers#local-user-management).
-
-## Base URL
-
-All endpoints are relative to your NetBird Management API:
-
-```
-https://netbird.example.com/api
-```
-
-## Authentication
-
-Most endpoints require authentication via Bearer token:
-
-```
-Authorization: Bearer
-```
-
-## Permissions
-
-Identity provider management requires administrator privileges. The following permission is required:
-
-- `identity_providers` permission - For managing identity provider configurations
-- `settings:read` - For viewing the Identity Providers tab
-
----
-
-## Instance Setup
-
-These endpoints handle the initial setup when embedded IdP is enabled and no accounts exist. Both endpoints are **unauthenticated** and only work before setup is complete.
-
-### Get Instance Status
-
-Check if the instance requires initial setup.
-
-```http
-GET /instance
-```
-
-**Authentication:** None required (public endpoint)
-
-**Response:**
-
-```json
-{
- "setup_required": true
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `setup_required` | boolean | `true` if no accounts exist and setup is needed |
-
-### Complete Setup
-
-Create the initial owner account.
-
-```http
-POST /instance/setup
-```
-
-**Authentication:** None required (only available during setup)
-
-**Request Body:**
-
-```json
-{
- "email": "admin@example.com",
- "password": "securepassword123",
- "name": "Admin User"
-}
-```
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `email` | string | Yes | Email address for the owner account |
-| `password` | string | Yes | Password (minimum 8 characters) |
-| `name` | string | No | Display name |
-
-**Response:**
-
-```json
-{
- "user_id": "user-abc123",
- "account_id": "account-xyz789"
-}
-```
-
-**Errors:**
-
-| Status | Code | Description |
-|--------|------|-------------|
-| 400 | `invalid_request` | Missing required fields or invalid format |
-| 412 | `precondition_failed` | Setup already completed (redirects to login) |
-| 503 | `idp_unavailable` | Embedded IdP is not enabled |
-
----
-
-## Identity Providers (Connectors)
-
-Manage external identity provider connectors. The Identity Providers tab is visible in Settings when `embedded_idp_enabled` is `true` in account settings.
-
-### List Identity Providers
-
-Get all configured identity providers.
-
-```http
-GET /identity-providers
-```
-
-**Response:**
-
-```json
-[
- {
- "id": "idp-abc123",
- "type": "google",
- "name": "Google Workspace",
- "client_id": "123456789.apps.googleusercontent.com",
- "issuer": "",
- "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
- },
- {
- "id": "idp-def456",
- "type": "oidc",
- "name": "Corporate SSO",
- "client_id": "netbird-client",
- "issuer": "https://sso.example.com",
- "redirect_url": "https://netbird.example.com/api/idp/callback/idp-def456"
- }
-]
-```
-
-
-Client secrets are never returned in API responses for security.
-
-
-### Get Identity Provider
-
-Get details for a specific identity provider.
-
-```http
-GET /identity-providers/{id}
-```
-
-**Path Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `id` | string | Identity provider ID |
-
-**Response:**
-
-```json
-{
- "id": "idp-abc123",
- "type": "google",
- "name": "Google Workspace",
- "client_id": "123456789.apps.googleusercontent.com",
- "issuer": "",
- "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
-}
-```
-
-### Create Identity Provider
-
-Add a new identity provider connector.
-
-```http
-POST /identity-providers
-```
-
-**Request Body:**
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `type` | string | Yes | Provider type (see below) |
-| `name` | string | Yes | Display name on login page |
-| `client_id` | string | Yes | OAuth client ID |
-| `client_secret` | string | Yes | OAuth client secret |
-| `issuer` | string | Conditional | Issuer URL (required for oidc, okta, zitadel, pocketid) |
-
-**Provider Types:**
-
-| Type | Description | Requires Issuer |
-|------|-------------|-----------------|
-| `google` | Google accounts / Google Workspace | No |
-| `microsoft` | Microsoft personal accounts | No |
-| `entra` | Microsoft Entra ID (Azure AD) | No |
-| `okta` | Okta SSO | Yes |
-| `zitadel` | Zitadel IdP | Yes |
-| `pocketid` | PocketID | Yes |
-| `oidc` | Generic OIDC provider | Yes |
-
-#### Google Configuration
-
-```json
-{
- "type": "google",
- "name": "Google Workspace",
- "client_id": "123456789.apps.googleusercontent.com",
- "client_secret": "GOCSPX-xxxxx"
-}
-```
-
-
-Google and Microsoft types do not require an `issuer` field - the issuer is determined automatically.
-
-
-#### Microsoft / Entra ID Configuration
-
-```json
-{
- "type": "entra",
- "name": "Microsoft Entra ID",
- "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
- "client_secret": "xxxxx"
-}
-```
-
-Use `microsoft` for personal Microsoft accounts, or `entra` for Azure AD / work accounts.
-
-#### Okta Configuration
-
-```json
-{
- "type": "okta",
- "name": "Okta SSO",
- "client_id": "0oaxxxxxxxxxx",
- "client_secret": "xxxxx",
- "issuer": "https://yourcompany.okta.com/oauth2/default"
-}
-```
-
-#### Zitadel Configuration
-
-```json
-{
- "type": "zitadel",
- "name": "Zitadel",
- "client_id": "123456789",
- "client_secret": "xxxxx",
- "issuer": "https://zitadel.example.com"
-}
-```
-
-#### PocketID Configuration
-
-```json
-{
- "type": "pocketid",
- "name": "PocketID",
- "client_id": "netbird",
- "client_secret": "xxxxx",
- "issuer": "https://pocketid.example.com"
-}
-```
-
-#### Generic OIDC Configuration
-
-```json
-{
- "type": "oidc",
- "name": "Custom SSO",
- "client_id": "netbird-client",
- "client_secret": "xxxxx",
- "issuer": "https://sso.example.com"
-}
-```
-
-The issuer URL must have a valid `/.well-known/openid-configuration` endpoint.
-
-**Response:**
-
-On successful creation, the response includes a `redirect_url` that must be configured in your identity provider:
-
-```json
-{
- "id": "idp-abc123",
- "type": "google",
- "name": "Google Workspace",
- "client_id": "123456789.apps.googleusercontent.com",
- "issuer": "",
- "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
-}
-```
-
-
-**Important:** After creating an identity provider, you must configure the `redirect_url` in your IdP's OAuth application settings. The Dashboard shows a modal with copy functionality after successful creation.
-
-
-**Errors:**
-
-| Status | Code | Description |
-|--------|------|-------------|
-| 400 | `invalid_request` | Missing required fields |
-| 400 | `invalid_type` | Unknown provider type |
-| 403 | `permission_denied` | Insufficient permissions |
-
-### Update Identity Provider
-
-Update an existing identity provider.
-
-```http
-PUT /identity-providers/{id}
-```
-
-**Path Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `id` | string | Identity provider ID |
-
-**Request Body:**
-
-Include only fields you want to update. The `type` cannot be changed.
-
-```json
-{
- "name": "Updated Name",
- "client_id": "new-client-id",
- "client_secret": "new-secret"
-}
-```
-
-
-If `client_secret` is empty or omitted, the existing secret is preserved. The help text in the Dashboard says: "Leave empty to keep the existing secret."
-
-
-**Response:**
-
-```json
-{
- "id": "idp-abc123",
- "type": "google",
- "name": "Updated Name",
- "client_id": "new-client-id",
- "issuer": "",
- "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
-}
-```
-
-### Delete Identity Provider
-
-Remove an identity provider connector.
-
-```http
-DELETE /identity-providers/{id}
-```
-
-**Path Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `id` | string | Identity provider ID |
-
-**Response:**
-
-```
-204 No Content
-```
-
-**Errors:**
-
-| Status | Code | Description |
-|--------|------|-------------|
-| 404 | `not_found` | Identity provider not found |
-| 403 | `permission_denied` | Insufficient permissions |
-
-
-Deleting an identity provider will prevent users who authenticate exclusively through that provider from logging in.
-
-
----
-
-## Users (Embedded IdP)
-
-When embedded IdP is enabled, the Dashboard shows a **"Create User"** button instead of "Invite User". Created users receive a generated password that is shown only once.
-
-### Create User
-
-Create a new local user. In the Dashboard, after creation, a modal displays the generated password with a copy button and the warning: *"This password will only be shown once. Please copy it now."*
-
-```http
-POST /users
-```
-
-**Request Body:**
-
-```json
-{
- "email": "user@example.com",
- "name": "New User",
- "role": "user",
- "auto_groups": ["group-id-1", "group-id-2"]
-}
-```
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `email` | string | Yes | User's email address |
-| `name` | string | Yes | Display name |
-| `role` | string | No | Role: `admin`, `user` (default: `user`) |
-| `auto_groups` | string[] | No | Groups to automatically assign |
-
-**Response:**
-
-```json
-{
- "id": "user-abc123",
- "email": "user@example.com",
- "name": "New User",
- "role": "user",
- "status": "active",
- "password": "generated-password-here"
-}
-```
-
-
-The `password` field is only included in the response when creating a user with embedded IdP enabled. It is never returned in subsequent API calls. Store it securely or share it with the user immediately.
-
-
-### User IdP Association
-
-When users authenticate through an external identity provider connector, their user record includes an `idp_id` field linking them to the provider. The Dashboard displays an IdP badge (with the provider's icon) next to the user's name in the Users table.
-
-```json
-{
- "id": "user-abc123",
- "email": "user@example.com",
- "name": "User Name",
- "role": "user",
- "status": "active",
- "idp_id": "idp-def456"
-}
-```
-
-
-This endpoint is only available when embedded IdP is enabled (`account.settings.extra.embedded_idp_enabled: true`). With external IdPs, users are provisioned through the IdP.
-
-
----
-
-## Error Responses
-
-All error responses follow this format:
-
-```json
-{
- "error": {
- "code": "error_code",
- "message": "Human-readable error message",
- "details": {}
- }
-}
-```
-
-### Common Error Codes
-
-| Code | HTTP Status | Description |
-|------|-------------|-------------|
-| `invalid_request` | 400 | Request body is malformed or missing required fields |
-| `invalid_config` | 400 | Provider configuration is invalid |
-| `unauthorized` | 401 | Missing or invalid authentication token |
-| `permission_denied` | 403 | Insufficient permissions for this operation |
-| `not_found` | 404 | Requested resource not found |
-| `duplicate` | 409 | Resource already exists |
-| `idp_unavailable` | 503 | Embedded IdP is not enabled or unavailable |
-
----
-
-## Rate Limits
-
-API requests are subject to rate limiting:
-
-| Endpoint Category | Rate Limit |
-|-------------------|------------|
-| Read operations | 100 requests/minute |
-| Write operations | 20 requests/minute |
-| Onboarding | 5 requests/minute |
-
-Rate limit headers are included in responses:
-
-```
-X-RateLimit-Limit: 100
-X-RateLimit-Remaining: 95
-X-RateLimit-Reset: 1642089600
-```
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/authentik.mdx b/src/pages/selfhosted/identity-providers/authentik.mdx
index b5e37011a..184f42a37 100644
--- a/src/pages/selfhosted/identity-providers/authentik.mdx
+++ b/src/pages/selfhosted/identity-providers/authentik.mdx
@@ -239,4 +239,4 @@ You've configured all required resources in Authentik. Continue with the [NetBir
- [Authentik Documentation](https://goauthentik.io/docs/)
- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
-- [API Reference](/selfhosted/identity-providers/api-reference)
\ No newline at end of file
+- [API Reference](/api/resources/identity-providers)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/index.mdx b/src/pages/selfhosted/identity-providers/index.mdx
index 7618197cf..b446fa78f 100644
--- a/src/pages/selfhosted/identity-providers/index.mdx
+++ b/src/pages/selfhosted/identity-providers/index.mdx
@@ -470,7 +470,7 @@ curl -X POST "https://netbird.example.com/api/identity-providers" \
}'
```
-See the [API Reference](/selfhosted/identity-providers/api-reference) for complete documentation.
+See the [API Reference](/api/resources/identity-providers) for complete documentation. For instance setup endpoints, see [Accounts API](/api/resources/accounts). For user creation with embedded IdP, see [Users API](/api/resources/users).
### Managing Connectors via API
diff --git a/src/pages/selfhosted/identity-providers/keycloak.mdx b/src/pages/selfhosted/identity-providers/keycloak.mdx
index 33a3b3dad..19130474d 100644
--- a/src/pages/selfhosted/identity-providers/keycloak.mdx
+++ b/src/pages/selfhosted/identity-providers/keycloak.mdx
@@ -321,4 +321,4 @@ You've configured all required resources in Keycloak. Continue with the [NetBird
- [Keycloak Documentation](https://www.keycloak.org/documentation)
- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
-- [API Reference](/selfhosted/identity-providers/api-reference)
\ No newline at end of file
+- [API Reference](/api/resources/identity-providers)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/pocketid.mdx b/src/pages/selfhosted/identity-providers/pocketid.mdx
index b9fb805aa..0f1e5f069 100644
--- a/src/pages/selfhosted/identity-providers/pocketid.mdx
+++ b/src/pages/selfhosted/identity-providers/pocketid.mdx
@@ -179,4 +179,4 @@ You've configured all required resources in PocketID. Continue with the [NetBird
- [PocketID Documentation](https://pocket-id.org/docs)
- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
-- [API Reference](/selfhosted/identity-providers/api-reference)
\ No newline at end of file
+- [API Reference](/api/resources/identity-providers)
\ No newline at end of file
From 049d28e0a3a5d5ad7adec50b84e126e698ab8f8f Mon Sep 17 00:00:00 2001
From: Brandon Hopkins
Date: Mon, 5 Jan 2026 23:08:51 -0800
Subject: [PATCH 09/18] Remove Gap
---
src/pages/selfhosted/identity-providers/index.mdx | 3 ---
1 file changed, 3 deletions(-)
diff --git a/src/pages/selfhosted/identity-providers/index.mdx b/src/pages/selfhosted/identity-providers/index.mdx
index b446fa78f..667928cd0 100644
--- a/src/pages/selfhosted/identity-providers/index.mdx
+++ b/src/pages/selfhosted/identity-providers/index.mdx
@@ -56,9 +56,6 @@ For organizations with specific requirements or existing IdP investments:
[Advanced IdP Setup →](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp)
----
-
-
## Local User Management
NetBird's Management service includes built-in user management, allowing you to create and manage local users directly without requiring an external identity provider. This functionality is powered by an embedded [Dex](https://dexidp.io/) server.
From 7c337e8feeab12eedb0db53571f655cffa0111e0 Mon Sep 17 00:00:00 2001
From: Brandon Hopkins
Date: Mon, 5 Jan 2026 23:51:31 -0800
Subject: [PATCH 10/18] Remove API Changes
---
src/pages/ipa/resources/accounts.mdx | 405 ------
.../ipa/resources/identity-providers.mdx | 1112 -----------------
src/pages/ipa/resources/users.mdx | 9 +-
3 files changed, 1 insertion(+), 1525 deletions(-)
delete mode 100644 src/pages/ipa/resources/identity-providers.mdx
diff --git a/src/pages/ipa/resources/accounts.mdx b/src/pages/ipa/resources/accounts.mdx
index 9bcdbd1d5..86eb8cb54 100644
--- a/src/pages/ipa/resources/accounts.mdx
+++ b/src/pages/ipa/resources/accounts.mdx
@@ -2,411 +2,6 @@ export const title = 'Accounts'
-## Get Instance Status {{ tag: 'GET' , label: '/api/instance' }}
-
-
-
- Check if the instance requires initial setup. This endpoint is only available when embedded IdP is enabled and no accounts exist. It is **unauthenticated** and only works before setup is complete.
-
-
-
- Create the initial owner account. This endpoint is only available when embedded IdP is enabled and no accounts exist. It is **unauthenticated** and only works before setup is complete.
-
- ### Request-Body Parameters
-
-
-
- Email address for the owner account
-
-
-
-
- Password for the owner account (minimum 8 characters)
-
-
-
-
- Display name for the owner account
-
-
-
-
-
- After setup is complete, accessing this endpoint returns a 412 error and redirects to login.
-
-
-
-
-
- Returns a list of all configured identity provider connectors. These endpoints are only available when embedded IdP is enabled (`account.settings.extra.embedded_idp_enabled: true`).
-
-
- Client secrets are never returned in API responses for security.
-
-
-
-
- Update an existing identity provider connector. The `type` cannot be changed after creation.
-
- ### Path Parameters
-
-
-
- The unique identifier of an identity provider
-
-
-
- ### Request-Body Parameters
-
-
-
- Display name on login page
-
-
-
-
- OAuth client ID from your identity provider
-
-
-
-
- OAuth client secret. If empty or omitted, the existing secret is preserved.
-
-
-
-
- Issuer URL. Only applicable for `okta`, `zitadel`, `pocketid`, and `oidc` types.
-
-
-
-
-
- Include only fields you want to update. If `client_secret` is empty or omitted, the existing secret is preserved.
-
-
-
-
-
-
- Remove an identity provider connector.
-
- ### Path Parameters
-
-
-
- The unique identifier of an identity provider
-
-
-
-
- **Warning:** Deleting an identity provider will prevent users who authenticate exclusively through that provider from logging in.
-
-
-
-
- Creates a new service user or sends an invite to a regular user. When embedded IdP is enabled (`account.settings.extra.embedded_idp_enabled: true`), this endpoint creates a local user with a generated password that is returned in the response.
+ Creates a new service user or sends an invite to a regular user
### Request-Body Parameters
@@ -295,9 +295,6 @@ echo $response;
-
- **Embedded IdP Behavior:** When embedded IdP is enabled, the response includes a `password` field containing the generated password. This password is only returned once at creation time and cannot be retrieved later. Store it securely or share it with the user immediately. Users authenticated through external identity provider connectors will have an `idp_id` field linking them to the provider.
-
@@ -535,8 +532,6 @@ echo $response;
"is_service_user": false,
"is_blocked": false,
"issued": "api",
- "password": "generated-password-here",
- "idp_id": "idp-def456",
"permissions": {
"is_restricted": {
"type": "boolean",
@@ -574,8 +569,6 @@ echo $response;
"is_service_user": "boolean",
"is_blocked": "boolean",
"issued": "string",
- "password": "string",
- "idp_id": "string",
"permissions": {
"is_restricted": "boolean",
"modules": {
From 3af9935f41d12913a8796507f8f405bf00371c0a Mon Sep 17 00:00:00 2001
From: Brandon Hopkins
Date: Tue, 6 Jan 2026 15:25:25 -0800
Subject: [PATCH 11/18] Update Quickstart
---
.../selfhosted/selfhosted-quickstart.mdx | 44 ++++++++++++-------
1 file changed, 28 insertions(+), 16 deletions(-)
diff --git a/src/pages/selfhosted/selfhosted-quickstart.mdx b/src/pages/selfhosted/selfhosted-quickstart.mdx
index 5c5b01241..c9081e60f 100644
--- a/src/pages/selfhosted/selfhosted-quickstart.mdx
+++ b/src/pages/selfhosted/selfhosted-quickstart.mdx
@@ -59,17 +59,20 @@ The script deploys NetBird **without any users**. Once complete, you'll need to
3. Create your admin account:
- Enter your email address
- Enter your name
+ - Enter a password
- Click **Create Account**
-A password will be generated and displayed. Copy it securely—it will only be shown once. You can then log in with your email and the generated password.
+You can then log in with your email and password.
The `/setup` page is only accessible when no users exist. After creating the first user, it redirects to the regular login page.
-### Add more local users
+### Add more users
-You can add additional local users directly from the NetBird Dashboard—no external identity provider needed:
+#### Local users
+
+You can add users directly from the NetBird Dashboard:
1. Navigate to **Team** → **Users**
2. Click **Create User**
@@ -78,9 +81,9 @@ You can add additional local users directly from the NetBird Dashboard—no exte
A password will be generated and displayed once. Share this securely with the user—it cannot be retrieved later.
-### Connect identity providers (Optional)
+#### Via Identity Provider (Optional)
-Local users work great on their own, but if you want users to sign in with their existing accounts from Google, Microsoft, Okta, or other providers, you can connect external identity providers:
+If you want users to sign in with their existing accounts from Google, Microsoft, Okta, or other providers, you can connect external identity providers:
1. Navigate to **Settings** → **Identity Providers**
2. Click **Add Identity Provider**
@@ -88,7 +91,7 @@ Local users work great on their own, but if you want users to sign in with their
4. Enter the OAuth client credentials from your provider
5. Click **Save**
-**Multiple providers supported**: You can add as many OIDC-compatible identity providers as you need. Users will see all configured providers as login options.
+You can add multiple identity providers. Users will see all configured providers as login options.
For detailed setup guides, see [Identity Providers](/selfhosted/identity-providers).
@@ -109,23 +112,24 @@ docker compose start management
```
### Upgrade
-
-The users with management on version < [v0.15.3](https://github.com/netbirdio/netbird/releases/tag/v0.15.3)
-should first upgrade their systems to [v0.25.9](https://github.com/netbirdio/netbird/releases/tag/v0.25.9),
-run management to properly migrate rules to policies, and then upgrade to **0.26.0+**.
-
-To upgrade NetBird to the latest version, you need to review the [release notes](https://github.com/netbirdio/netbird/releases) for any breaking changes and follow the upgrade steps below:
+To upgrade NetBird to the latest version:
+
1. Run the backup steps described in the [backup](#backup) section.
-2. Pull the latest NetBird docker images:
+2. Review the [release notes](https://github.com/netbirdio/netbird/releases) for any breaking changes.
+3. Pull the latest NetBird docker images:
```bash
docker compose pull management dashboard signal relay
```
-3. Restart the NetBird containers with the new images:
+4. Restart the NetBird containers with the new images:
```bash
docker compose up -d --force-recreate management dashboard signal relay
```
+
+For upgrades from older versions (pre-v0.26.0), see the [Legacy upgrade notes](#legacy-self-hosting-with-zitadel-idp).
+
+
### Support browser clients
If you deployed NetBird before version **0.59.0** and want to use browser clients, you need to update your Signal, Management, Dashboard and Relay services, see [Upgrade](#upgrade), then you need to edit the `Caddyfile` file to enable support for browser clients by adding the following lines to the `Caddyfile`:
```
@@ -167,10 +171,10 @@ For more troubleshooting help, see the [Troubleshooting guide](/selfhosted/troub
## Legacy: Self-hosting with Zitadel IdP
-This section is for users who prefer to use Zitadel as a standalone IdP instead of local user management. For new installations, we recommend the [quickstart approach](#quick-self-hosting) above—you can always add Zitadel as an external identity provider later if needed.
+**Deprecated**: This method is no longer recommended for new installations. It is preserved as a reference for users who deployed NetBird using the Zitadel quickstart script prior to version X.XX. For new installations, use the [quickstart approach](#quick-self-hosting) above.
-If you want to deploy NetBird with [Zitadel](https://zitadel.com/) as the identity provider, you can use the legacy quickstart script:
+The following instructions apply to deployments using the `getting-started-with-zitadel.sh` script, which bundled Zitadel as an external identity provider.
### Download and run the script
@@ -227,6 +231,14 @@ If you have an existing Zitadel deployment and want to migrate:
See the [Migration Guide](/selfhosted/identity-providers#migration-guide) for detailed steps.
+### Upgrade (Legacy)
+
+
+If upgrading from management version < [v0.15.3](https://github.com/netbirdio/netbird/releases/tag/v0.15.3),
+first upgrade to [v0.25.9](https://github.com/netbirdio/netbird/releases/tag/v0.25.9),
+run management to migrate rules to policies, then upgrade to **0.26.0+**.
+
+
---
## Get in touch
From 6188abf2b26b86bdee5c93caa7bd8257365d0c0d Mon Sep 17 00:00:00 2001
From: Brandon Hopkins
Date: Tue, 6 Jan 2026 15:56:34 -0800
Subject: [PATCH 12/18] New Local Page and Fixes
---
src/components/NavigationAPI.jsx | 1 -
src/components/NavigationDocs.jsx | 7 +-
.../identity-providers/authentik.mdx | 4 +-
.../selfhosted/identity-providers/index.mdx | 339 +-----------------
.../identity-providers/keycloak.mdx | 4 +-
.../selfhosted/identity-providers/local.mdx | 336 +++++++++++++++++
.../identity-providers/managed/auth0.mdx | 4 +-
.../managed/google-workspace.mdx | 4 +-
.../identity-providers/managed/jumpcloud.mdx | 4 +-
.../managed/microsoft-entra-id.mdx | 4 +-
.../identity-providers/managed/okta.mdx | 4 +-
.../identity-providers/pocketid.mdx | 4 +-
.../selfhosted/identity-providers/zitadel.mdx | 4 +-
.../self-hosted-vs-cloud-netbird.mdx | 2 +-
.../selfhosted/selfhosted-quickstart.mdx | 2 +-
15 files changed, 361 insertions(+), 362 deletions(-)
create mode 100644 src/pages/selfhosted/identity-providers/local.mdx
diff --git a/src/components/NavigationAPI.jsx b/src/components/NavigationAPI.jsx
index 48d220c06..4f46572de 100644
--- a/src/components/NavigationAPI.jsx
+++ b/src/components/NavigationAPI.jsx
@@ -23,7 +23,6 @@ export const apiNavigation = [
links: [
{ title: 'Accounts', href: '/api/resources/accounts' },
{ title: 'Users', href: '/api/resources/users' },
- { title: 'Identity Providers', href: '/api/resources/identity-providers' },
{ title: 'Tokens', href: '/api/resources/tokens' },
{ title: 'Peers', href: '/api/resources/peers' },
{ title: 'Ingress Ports', href: '/api/resources/ingress-ports' },
diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx
index 59ca480ef..2c705ad6d 100644
--- a/src/components/NavigationDocs.jsx
+++ b/src/components/NavigationDocs.jsx
@@ -282,12 +282,13 @@ export const docsNavigation = [
{
title: 'SELF-HOST NETBIRD',
links: [
- { title: 'Quickstart guide', href: '/selfhosted/selfhosted-quickstart' },
+ { title: 'Quickstart Guide', href: '/selfhosted/selfhosted-quickstart' },
{
- title: 'Supported IdPs',
+ title: 'Accounts and IdPs',
isOpen: false,
links: [
- { title: 'Using IdPs on Self-Hosted', href: '/selfhosted/identity-providers' },
+ { title: 'Identity Providers', href: '/selfhosted/identity-providers' },
+ { title: 'Local User Accounts', href: '/selfhosted/identity-providers/local' },
{
title: 'Self-hosted IdPs',
isOpen: true,
diff --git a/src/pages/selfhosted/identity-providers/authentik.mdx b/src/pages/selfhosted/identity-providers/authentik.mdx
index 184f42a37..881416181 100644
--- a/src/pages/selfhosted/identity-providers/authentik.mdx
+++ b/src/pages/selfhosted/identity-providers/authentik.mdx
@@ -88,7 +88,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
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-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+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 [Connector Setup (Recommended)](#connector-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).
@@ -238,5 +238,5 @@ You've configured all required resources in Authentik. Continue with the [NetBir
## Related Resources
- [Authentik Documentation](https://goauthentik.io/docs/)
-- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
- [API Reference](/api/resources/identity-providers)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/index.mdx b/src/pages/selfhosted/identity-providers/index.mdx
index 667928cd0..6063d1afc 100644
--- a/src/pages/selfhosted/identity-providers/index.mdx
+++ b/src/pages/selfhosted/identity-providers/index.mdx
@@ -31,7 +31,7 @@ The simplest approach—create and manage users directly in NetBird:
- User management through the Dashboard
- Ideal for homelabs, small teams, and proof-of-concept deployments
-See the [Local User Management](#local-user-management) section below for setup details.
+See the [Local User Management](/selfhosted/identity-providers/local) page for setup details.
### Local Users + External Identity Providers
@@ -56,343 +56,6 @@ For organizations with specific requirements or existing IdP investments:
[Advanced IdP Setup →](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp)
-## Local User Management
-
-NetBird's Management service includes built-in user management, allowing you to create and manage local users directly without requiring an external identity provider. This functionality is powered by an embedded [Dex](https://dexidp.io/) server.
-
-Starting with version X.XX, NetBird **no longer requires an external identity provider**. The Management service now supports creating and managing local users directly, so you can get started without setting up Zitadel, Keycloak, or any other IdP.
-
-With local user management, you can:
-
-- **Create local users** directly from the NetBird Dashboard
-- **Add external identity providers** (Google, Microsoft, Okta, etc.) through the Dashboard UI
-- **Configure multiple IdPs** simultaneously—users see all providers as login options
-- **Simplify your deployment** with fewer containers and reduced resource requirements
-- **Get started faster** with no additional IdP setup required
-
-
-Local user management is powered by an embedded [Dex](https://dexidp.io/) server running within the NetBird Management service, requiring no additional containers or databases.
-
-
-[Get Started →](/selfhosted/selfhosted-quickstart)
-
-### Overview
-
-The Management service provides:
-
-- **Local user management** - Create users with email/password authentication directly in NetBird
-- **No external IdP required** - Works out of the box, no Zitadel, Keycloak, or other IdP needed
-- **External identity provider support** - Optionally connect one or more OIDC-compatible providers (Google, Microsoft, Okta, etc.)
-- **Multiple IdP support** - Configure multiple external identity providers simultaneously
-- **Device authentication** - CLI authentication via device authorization flow
-- **Secure storage** - AES-256-GCM encryption for sensitive user data at rest
-
-### When to Use Local Users
-
-Local user management is ideal for:
-
-| Use Case | Why Local Users Work |
-|----------|----------------------|
-| **Homelabs** | Simple setup, minimal resources, no external dependencies |
-| **Small teams** | Easy user management, quick onboarding |
-| **Proof of concept** | Get started in minutes, upgrade path available |
-| **Air-gapped environments** | No external service dependencies |
-| **Development/testing** | Fast iteration, simple reset |
-
-Consider a [standalone external IdP](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp) if you need:
-
-- SCIM user provisioning (Enterprise feature)
-- Complex user lifecycle management
-- Integration with existing enterprise SSO infrastructure
-- Specific IdP features not available via OIDC connectors
-
-### Architecture
-
-With local user management enabled, the architecture is simplified:
-
-```
- NetBird Management
-┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐
-│ Management │ │ Embedded Dex │ │ Dashboard │
-│ Service │◄─┤ IdP Server │◄─┤ API │
-└─────────────────┘ └─────────────────┘ └─────────────┘
- │ │
- ▼ ▼
-┌─────────────────────────────────────────────────────────┐
-│ SQLite/Postgres Database │
-│ (Users, Accounts, IdP Connectors) │
-└─────────────────────────────────────────────────────────┘
-```
-
-Compare this to the external IdP architecture which requires separate containers for the IdP and its database.
-
-
-### Configuration
-
-#### Enabling Embedded IdP
-
-The embedded IdP is enabled by default when using the new `getting-started.sh` quickstart script. For manual configuration, update your `management.json`:
-
-```json
-{
- "EmbeddedIdP": {
- "Enabled": true,
- "DataDir": "/var/lib/netbird/idp"
- },
- "EncryptionKey": ""
-}
-```
-
-#### Configuration Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `EmbeddedIdP.Enabled` | Enable/disable the embedded IdP | `true` (quickstart) |
-| `EmbeddedIdP.DataDir` | Directory for IdP data storage | `/var/lib/netbird/idp` |
-| `EncryptionKey` | Base64-encoded AES-256 key for encrypting user data | Auto-generated |
-
-#### Environment Variables
-
-When using docker-compose, you can configure these via environment variables:
-
-```yaml
-environment:
- - NETBIRD_EMBEDDED_IDP_ENABLED=true
- - NETBIRD_EMBEDDED_IDP_DATA_DIR=/var/lib/netbird/idp
- - NETBIRD_ENCRYPTION_KEY=${ENCRYPTION_KEY}
-```
-
-#### Generating an Encryption Key
-
-If you need to generate an encryption key manually:
-
-```bash
-openssl rand -base64 32
-```
-
-
-Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures.
-
-
-
-### User Management
-
-#### Creating Users via Dashboard
-
-When embedded IdP is enabled, the Dashboard shows a **"Create User"** button (instead of "Invite User" shown for cloud-hosted NetBird):
-
-1. Navigate to **Team** → **Users**
-2. Click **Create User**
-3. Fill in the user details:
- - **Email** (required) - User's email address for login
- - **Name** (required) - Display name
- - **Groups** (optional) - Auto-assign to groups
-4. Click **Create**
-
-After creation, a modal displays with:
-- The **generated password** with a copy button
-- Warning: *"This password will only be shown once. Please copy it now."*
-- **Copy & Close** button to copy password and dismiss
-
-
-The generated password is only shown once at creation time. It cannot be retrieved later. Make sure to copy it and share it securely with the user.
-
-
-#### User IdP Badges
-
-In the Users table, each user shows a badge indicating their identity provider:
-- Users created locally show no badge (or "Local" badge)
-- Users who authenticated via an external connector show that provider's icon (Google, Microsoft, etc.)
-- The badge links to the `idp_id` field in the user record
-
-#### Creating Users via API
-
-```bash
-curl -X POST "https://netbird.example.com/api/users" \
- -H "Authorization: Bearer ${TOKEN}" \
- -H "Content-Type: application/json" \
- -d '{
- "email": "user@example.com",
- "name": "New User",
- "auto_groups": ["group-id-1"]
- }'
-```
-
-Response includes the generated password:
-
-```json
-{
- "id": "user-abc123",
- "email": "user@example.com",
- "name": "New User",
- "role": "user",
- "status": "active",
- "password": "generated-password-here"
-}
-```
-
-
-The `password` field is only included when creating users with embedded IdP. Store it immediately—it won't be returned in subsequent API calls.
-
-
-#### User Roles
-
-Users created through the embedded IdP can be assigned roles:
-
-| Role | Permissions |
-|------|-------------|
-| **Owner** | Full administrative access, cannot be demoted |
-| **Admin** | Manage users, peers, policies, and settings |
-| **User** | Connect devices, view assigned resources |
-
-
-### Instance Setup (First Run)
-
-When NetBird starts with the embedded IdP and no existing accounts, the Dashboard redirects to the `/setup` route and displays the **Instance Setup Wizard**:
-
-1. The Dashboard checks `GET /instance` for `setup_required: true`
-2. If setup is required, users are redirected to `/setup`
-3. The wizard collects:
- - **Email address** (required)
- - **Password** (required, minimum 8 characters)
- - **Name** (optional)
-4. On submit, the owner account is created via `POST /instance/setup`
-5. User is redirected to login with the credentials they just created
-
-
-The `/setup` route is unauthenticated and only accessible when `setup_required` is true. Once setup is complete, accessing `/setup` returns a 412 error and redirects to login.
-
-
-#### Setup API
-
-For automated deployments, you can complete setup via API:
-
-```bash
-# Check if setup is required
-curl "https://netbird.example.com/api/instance"
-
-# Response when setup is needed:
-{
- "setup_required": true
-}
-
-# Complete setup
-curl -X POST "https://netbird.example.com/api/instance/setup" \
- -H "Content-Type: application/json" \
- -d '{
- "email": "admin@example.com",
- "password": "securepassword123",
- "name": "Admin User"
- }'
-
-# Response:
-{
- "user_id": "user-abc123",
- "account_id": "account-xyz789"
-}
-```
-
-### Data Encryption
-
-The embedded IdP encrypts sensitive user data at rest:
-
-| Field | Encryption |
-|-------|------------|
-| Email | AES-256-GCM |
-| Name | AES-256-GCM |
-| Password | bcrypt hash (via Dex) |
-
-The encryption key is configured in `management.json` and should be:
-
-- Generated using a cryptographically secure random generator
-- Stored securely (not in version control)
-- Included in backup procedures
-- Rotated according to your security policies
-
-### Security Considerations
-
-#### Password Requirements
-
-Default password requirements for local users:
-
-- Minimum 8 characters
-- No specific complexity requirements (consider your security policy)
-
-#### Session Management
-
-- JWT tokens are issued upon successful authentication
-- Token expiration follows OIDC best practices
-- Device authorization flow available for CLI clients
-
-#### Audit Logging
-
-User authentication events are logged in the activity log:
-
-- Login attempts (successful and failed)
-- User creation/deletion
-- Connector configuration changes
-- Password resets
-
-### Troubleshooting
-
-#### "Embedded IdP not available" error
-
-Ensure `EmbeddedIdP.Enabled` is `true` in `management.json` and the Management service has been restarted.
-
-#### Users can't log in
-
-1. Check Management service logs: `docker compose logs management`
-2. Verify the encryption key hasn't changed
-3. Confirm the user exists: Check **Team** → **Users** in Dashboard
-
-#### Password reset
-
-Use the management CLI:
-
-```bash
-docker compose exec management /go/bin/netbird-mgmt users reset-password \
- --email user@example.com \
- --new-password "newpassword123"
-```
-
-### Comparison with External IdP
-
-| Feature | Embedded IdP | External IdP |
-|---------|--------------|--------------|
-| Setup complexity | Minimal | Moderate to High |
-| Resource requirements | Low (~1GB RAM) | Higher (2-4GB+ RAM) |
-| Additional containers | None | IdP + Database |
-| User management | Dashboard/API | External IdP console |
-| External SSO | Via connectors | Native |
-| SCIM provisioning | Not available | Available (Enterprise) |
-| MFA | Via external connectors | Native IdP feature |
-| Backup complexity | Single database | Multiple databases |
-
-### Disabling Embedded IdP
-
-To switch from embedded IdP to an external IdP:
-
-1. Configure your external IdP following the [Advanced guide](/selfhosted/selfhosted-guide)
-2. Update `management.json`:
-
- ```json
- {
- "EmbeddedIdP": {
- "Enabled": false
- },
- "HttpConfig": {
- "OIDCConfigEndpoint": "https://your-idp.example.com/.well-known/openid-configuration"
- }
- }
- ```
-
-3. Restart the Management service
-4. Users will need to re-authenticate with the new IdP
-
-
-Disabling the embedded IdP will invalidate all local user accounts. Ensure users have accounts in the external IdP before switching.
-
-
---
diff --git a/src/pages/selfhosted/identity-providers/keycloak.mdx b/src/pages/selfhosted/identity-providers/keycloak.mdx
index 19130474d..a94f57747 100644
--- a/src/pages/selfhosted/identity-providers/keycloak.mdx
+++ b/src/pages/selfhosted/identity-providers/keycloak.mdx
@@ -73,7 +73,7 @@ Users who authenticate via Keycloak will appear in your NetBird Users list with
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-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+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 [Connector Setup (Recommended)](#connector-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).
@@ -320,5 +320,5 @@ You've configured all required resources in Keycloak. Continue with the [NetBird
## Related Resources
- [Keycloak Documentation](https://www.keycloak.org/documentation)
-- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
- [API Reference](/api/resources/identity-providers)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/local.mdx b/src/pages/selfhosted/identity-providers/local.mdx
new file mode 100644
index 000000000..d9eb13134
--- /dev/null
+++ b/src/pages/selfhosted/identity-providers/local.mdx
@@ -0,0 +1,336 @@
+# Local User Management
+
+NetBird's Management service includes built-in user management, allowing you to create and manage local users directly without requiring an external identity provider. This functionality is powered by an embedded [Dex](https://dexidp.io/) server.
+
+Starting with version 0.62, NetBird **no longer requires an external identity provider**. The Management service now supports creating and managing local users directly, so you can get started without setting up Zitadel, Keycloak, or any other IdP.
+
+With local user management, you can:
+
+- **Create local users** directly from the NetBird Dashboard
+- **Add external identity providers** (Google, Microsoft, Okta, etc.) through the Dashboard UI
+- **Configure multiple IdPs** simultaneously—users see all providers as login options
+- **Simplify your deployment** with fewer containers and reduced resource requirements
+- **Get started faster** with no additional IdP setup required
+
+
+Local user management is powered by an embedded [Dex](https://dexidp.io/) server running within the NetBird Management service, requiring no additional containers or databases.
+
+
+[Get Started →](/selfhosted/selfhosted-quickstart)
+
+## Overview
+
+The Management service provides:
+
+- **Local user management** - Create users with email/password authentication directly in NetBird
+- **No external IdP required** - Works out of the box, no Zitadel, Keycloak, or other IdP needed
+- **External identity provider support** - Optionally connect one or more OIDC-compatible providers (Google, Microsoft, Okta, etc.)
+- **Multiple IdP support** - Configure multiple external identity providers simultaneously
+- **Device authentication** - CLI authentication via device authorization flow
+- **Secure storage** - AES-256-GCM encryption for sensitive user data at rest
+
+## When to Use Local Users
+
+Local user management is ideal for:
+
+| Use Case | Why Local Users Work |
+|----------|----------------------|
+| **Homelabs** | Simple setup, minimal resources, no external dependencies |
+| **Small teams** | Easy user management, quick onboarding |
+| **Proof of concept** | Get started in minutes, upgrade path available |
+| **Air-gapped environments** | No external service dependencies |
+| **Development/testing** | Fast iteration, simple reset |
+
+Consider a [standalone external IdP](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp) if you need:
+
+- SCIM user provisioning (Enterprise feature)
+- Complex user lifecycle management
+- Integration with existing enterprise SSO infrastructure
+- Specific IdP features not available via OIDC connectors
+
+## Architecture
+
+With local user management enabled, the architecture is simplified:
+
+```
+ NetBird Management
+┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐
+│ Management │ │ Embedded Dex │ │ Dashboard │
+│ Service │◄─┤ IdP Server │◄─┤ API │
+└─────────────────┘ └─────────────────┘ └─────────────┘
+ │ │
+ ▼ ▼
+┌─────────────────────────────────────────────────────────┐
+│ SQLite/Postgres Database │
+│ (Users, Accounts, IdP Connectors) │
+└─────────────────────────────────────────────────────────┘
+```
+
+Compare this to the external IdP architecture which requires separate containers for the IdP and its database.
+
+## Configuration
+
+### Enabling Embedded IdP
+
+The embedded IdP is enabled by default when using the new `getting-started.sh` quickstart script. For manual configuration, update your `management.json`:
+
+```json
+{
+ "EmbeddedIdP": {
+ "Enabled": true,
+ "DataDir": "/var/lib/netbird/idp"
+ },
+ "EncryptionKey": ""
+}
+```
+
+### Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `EmbeddedIdP.Enabled` | Enable/disable the embedded IdP | `true` (quickstart) |
+| `EmbeddedIdP.DataDir` | Directory for IdP data storage | `/var/lib/netbird/idp` |
+| `EncryptionKey` | Base64-encoded AES-256 key for encrypting user data | Auto-generated |
+
+### Environment Variables
+
+When using docker-compose, you can configure these via environment variables:
+
+```yaml
+environment:
+ - NETBIRD_EMBEDDED_IDP_ENABLED=true
+ - NETBIRD_EMBEDDED_IDP_DATA_DIR=/var/lib/netbird/idp
+ - NETBIRD_ENCRYPTION_KEY=${ENCRYPTION_KEY}
+```
+
+### Generating an Encryption Key
+
+If you need to generate an encryption key manually:
+
+```bash
+openssl rand -base64 32
+```
+
+
+Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures.
+
+
+
+## User Management
+
+### Creating Users via Dashboard
+
+When embedded IdP is enabled, the Dashboard shows a **"Create User"** button (instead of "Invite User" shown for cloud-hosted NetBird):
+
+1. Navigate to **Team** → **Users**
+2. Click **Create User**
+3. Fill in the user details:
+ - **Email** (required) - User's email address for login
+ - **Name** (required) - Display name
+ - **Groups** (optional) - Auto-assign to groups
+4. Click **Create**
+
+After creation, a modal displays with:
+- The **generated password** with a copy button
+- Warning: *"This password will only be shown once. Please copy it now."*
+- **Copy & Close** button to copy password and dismiss
+
+
+The generated password is only shown once at creation time. It cannot be retrieved later. Make sure to copy it and share it securely with the user.
+
+
+### User IdP Badges
+
+In the Users table, each user shows a badge indicating their identity provider:
+- Users created locally show no badge (or "Local" badge)
+- Users who authenticated via an external connector show that provider's icon (Google, Microsoft, etc.)
+- The badge links to the `idp_id` field in the user record
+
+### Creating Users via API
+
+```bash
+curl -X POST "https://netbird.example.com/api/users" \
+ -H "Authorization: Bearer ${TOKEN}" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "email": "user@example.com",
+ "name": "New User",
+ "auto_groups": ["group-id-1"]
+ }'
+```
+
+Response includes the generated password:
+
+```json
+{
+ "id": "user-abc123",
+ "email": "user@example.com",
+ "name": "New User",
+ "role": "user",
+ "status": "active",
+ "password": "generated-password-here"
+}
+```
+
+
+The `password` field is only included when creating users with embedded IdP. Store it immediately—it won't be returned in subsequent API calls.
+
+
+### User Roles
+
+Users created through the embedded IdP can be assigned roles:
+
+| Role | Permissions |
+|------|-------------|
+| **Owner** | Full administrative access, cannot be demoted |
+| **Admin** | Manage users, peers, policies, and settings |
+| **User** | Connect devices, view assigned resources |
+
+
+## Instance Setup (First Run)
+
+When NetBird starts with the embedded IdP and no existing accounts, the Dashboard redirects to the `/setup` route and displays the **Instance Setup Wizard**:
+
+1. The Dashboard checks `GET /instance` for `setup_required: true`
+2. If setup is required, users are redirected to `/setup`
+3. The wizard collects:
+ - **Email address** (required)
+ - **Password** (required, minimum 8 characters)
+ - **Name** (optional)
+4. On submit, the owner account is created via `POST /instance/setup`
+5. User is redirected to login with the credentials they just created
+
+
+The `/setup` route is unauthenticated and only accessible when `setup_required` is true. Once setup is complete, accessing `/setup` returns a 412 error and redirects to login.
+
+
+### Setup API
+
+For automated deployments, you can complete setup via API:
+
+```bash
+# Check if setup is required
+curl "https://netbird.example.com/api/instance"
+
+# Response when setup is needed:
+{
+ "setup_required": true
+}
+
+# Complete setup
+curl -X POST "https://netbird.example.com/api/instance/setup" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "email": "admin@example.com",
+ "password": "securepassword123",
+ "name": "Admin User"
+ }'
+
+# Response:
+{
+ "user_id": "user-abc123",
+ "account_id": "account-xyz789"
+}
+```
+
+## Data Encryption
+
+The embedded IdP encrypts sensitive user data at rest:
+
+| Field | Encryption |
+|-------|------------|
+| Email | AES-256-GCM |
+| Name | AES-256-GCM |
+| Password | bcrypt hash (via Dex) |
+
+The encryption key is configured in `management.json` and should be:
+
+- Generated using a cryptographically secure random generator
+- Stored securely (not in version control)
+- Included in backup procedures
+- Rotated according to your security policies
+
+## Security Considerations
+
+### Password Requirements
+
+Default password requirements for local users:
+
+- Minimum 8 characters
+- No specific complexity requirements (consider your security policy)
+
+### Session Management
+
+- JWT tokens are issued upon successful authentication
+- Token expiration follows OIDC best practices
+- Device authorization flow available for CLI clients
+
+### Audit Logging
+
+User authentication events are logged in the activity log:
+
+- Login attempts (successful and failed)
+- User creation/deletion
+- Connector configuration changes
+- Password resets
+
+## Troubleshooting
+
+### "Embedded IdP not available" error
+
+Ensure `EmbeddedIdP.Enabled` is `true` in `management.json` and the Management service has been restarted.
+
+### Users can't log in
+
+1. Check Management service logs: `docker compose logs management`
+2. Verify the encryption key hasn't changed
+3. Confirm the user exists: Check **Team** → **Users** in Dashboard
+
+### Password reset
+
+Use the management CLI:
+
+```bash
+docker compose exec management /go/bin/netbird-mgmt users reset-password \
+ --email user@example.com \
+ --new-password "newpassword123"
+```
+
+## Comparison with External IdP
+
+| Feature | Embedded IdP | External IdP |
+|---------|--------------|--------------|
+| Setup complexity | Minimal | Moderate to High |
+| Resource requirements | Low (~1GB RAM) | Higher (2-4GB+ RAM) |
+| Additional containers | None | IdP + Database |
+| User management | Dashboard/API | External IdP console |
+| External SSO | Via connectors | Native |
+| SCIM provisioning | Not available | Available (Enterprise) |
+| MFA | Via external connectors | Native IdP feature |
+| Backup complexity | Single database | Multiple databases |
+
+## Disabling Embedded IdP
+
+To switch from embedded IdP to an external IdP:
+
+1. Configure your external IdP following the [Advanced guide](/selfhosted/selfhosted-guide)
+2. Update `management.json`:
+
+ ```json
+ {
+ "EmbeddedIdP": {
+ "Enabled": false
+ },
+ "HttpConfig": {
+ "OIDCConfigEndpoint": "https://your-idp.example.com/.well-known/openid-configuration"
+ }
+ }
+ ```
+
+3. Restart the Management service
+4. Users will need to re-authenticate with the new IdP
+
+
+Disabling the embedded IdP will invalidate all local user accounts. Ensure users have accounts in the external IdP before switching.
+
+
diff --git a/src/pages/selfhosted/identity-providers/managed/auth0.mdx b/src/pages/selfhosted/identity-providers/managed/auth0.mdx
index 87b36937a..f2f06ea22 100644
--- a/src/pages/selfhosted/identity-providers/managed/auth0.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/auth0.mdx
@@ -65,7 +65,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
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-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
@@ -242,4 +242,4 @@ You've configured all required resources in Auth0. Continue with the [NetBird Se
- [Auth0 Documentation](https://auth0.com/docs/)
- [Auth0 Dashboard](https://manage.auth0.com/)
-- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
\ No newline at end of file
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
index d03c18fab..09c9b810f 100644
--- a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
@@ -86,7 +86,7 @@ Domain restrictions are configured in Google Cloud Console, not in NetBird.
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-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+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 [Connector Setup (Recommended)](#connector-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.
@@ -291,4 +291,4 @@ You've configured all required resources in Google Workspace. Continue with the
- [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-user-management)
\ No newline at end of file
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx b/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
index c5d6738d8..d3b17e888 100644
--- a/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
@@ -75,7 +75,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
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-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
### Prerequisites
@@ -251,4 +251,4 @@ You've configured all required resources in JumpCloud. Continue with the [NetBir
- [JumpCloud Documentation](https://jumpcloud.com/support)
- [JumpCloud Admin Console](https://console.jumpcloud.com/)
-- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
\ No newline at end of file
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx b/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
index ce37eb827..4803dd16f 100644
--- a/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
@@ -91,7 +91,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
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-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
@@ -277,4 +277,4 @@ You've configured all required resources in Azure AD. Continue with the [NetBird
- [Microsoft Identity Platform Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/)
- [Azure Portal](https://portal.azure.com/)
-- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
\ No newline at end of file
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/managed/okta.mdx b/src/pages/selfhosted/identity-providers/managed/okta.mdx
index 10ce517e6..601f789c3 100644
--- a/src/pages/selfhosted/identity-providers/managed/okta.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/okta.mdx
@@ -68,7 +68,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
Use Okta 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 Okta administrators as it also requires additional setup and ongoing maintenance.
-For most deployments, the [embedded IdP](/selfhosted/identity-providers#local-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak).
@@ -231,4 +231,4 @@ You've configured all required resources in Okta. Continue with the [NetBird Sel
- [Okta Developer Documentation](https://developer.okta.com/docs/)
- [Okta Admin Console](https://help.okta.com/en/prod/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm)
-- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
\ No newline at end of file
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/pocketid.mdx b/src/pages/selfhosted/identity-providers/pocketid.mdx
index 0f1e5f069..d506e2d6f 100644
--- a/src/pages/selfhosted/identity-providers/pocketid.mdx
+++ b/src/pages/selfhosted/identity-providers/pocketid.mdx
@@ -69,7 +69,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
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-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
### Prerequisites
@@ -178,5 +178,5 @@ You've configured all required resources in PocketID. Continue with the [NetBird
## Related Resources
- [PocketID Documentation](https://pocket-id.org/docs)
-- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
- [API Reference](/api/resources/identity-providers)
\ No newline at end of file
diff --git a/src/pages/selfhosted/identity-providers/zitadel.mdx b/src/pages/selfhosted/identity-providers/zitadel.mdx
index e89a363c9..9d331081d 100644
--- a/src/pages/selfhosted/identity-providers/zitadel.mdx
+++ b/src/pages/selfhosted/identity-providers/zitadel.mdx
@@ -72,7 +72,7 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
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-user-management) 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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
+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 [Connector Setup (Recommended)](#connector-setup-recommended) section above.
If you prefer not to self-host, Zitadel offers a managed cloud option at [zitadel.com](https://zitadel.com/).
@@ -285,5 +285,5 @@ If you deployed NetBird using the previous quickstart script with Zitadel:
- [Zitadel Documentation](https://zitadel.com/docs)
- [Zitadel GitHub](https://github.com/zitadel/zitadel)
-- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
+- [Embedded IdP Overview](/selfhosted/identity-providers/local)
- [Migration Guide](/selfhosted/identity-providers#migration-guide)
\ No newline at end of file
diff --git a/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx b/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx
index 9751fe8bf..93e80c2b8 100644
--- a/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx
+++ b/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx
@@ -20,7 +20,7 @@ a reliable manner. NetBird is not just one VPN server. You can read more about h
## What's New: No External IdP Required
-Starting with version X.XX, self-hosting NetBird has become significantly easier. Previously, self-hosting required setting up and maintaining a separate identity provider (like Zitadel, Keycloak, or Auth0). Now, the Management service supports **local user management** directly, which means:
+Starting with version 0.62, self-hosting NetBird has become significantly easier. Previously, self-hosting required setting up and maintaining a separate identity provider (like Zitadel, Keycloak, or Auth0). Now, the Management service supports **local user management** directly, which means:
- **No external IdP required** - Create and manage users directly in NetBird
- **Fewer containers** to deploy and maintain (4-5 vs 7+ previously)
diff --git a/src/pages/selfhosted/selfhosted-quickstart.mdx b/src/pages/selfhosted/selfhosted-quickstart.mdx
index c9081e60f..41e54e7ad 100644
--- a/src/pages/selfhosted/selfhosted-quickstart.mdx
+++ b/src/pages/selfhosted/selfhosted-quickstart.mdx
@@ -171,7 +171,7 @@ For more troubleshooting help, see the [Troubleshooting guide](/selfhosted/troub
## Legacy: Self-hosting with Zitadel IdP
-**Deprecated**: This method is no longer recommended for new installations. It is preserved as a reference for users who deployed NetBird using the Zitadel quickstart script prior to version X.XX. For new installations, use the [quickstart approach](#quick-self-hosting) above.
+**Deprecated**: This method is no longer recommended for new installations. It is preserved as a reference for users who deployed NetBird using the Zitadel quickstart script prior to version 0.62. For new installations, use the [quickstart approach](#quick-self-hosting) above.
The following instructions apply to deployments using the `getting-started-with-zitadel.sh` script, which bundled Zitadel as an external identity provider.
From 0645790eeb2421053131e07925963fb0baf24157 Mon Sep 17 00:00:00 2001
From: Brandon Hopkins
Date: Tue, 6 Jan 2026 16:00:17 -0800
Subject: [PATCH 13/18] Fixing Gaps
---
src/pages/selfhosted/identity-providers/index.mdx | 2 --
src/pages/selfhosted/identity-providers/local.mdx | 2 --
2 files changed, 4 deletions(-)
diff --git a/src/pages/selfhosted/identity-providers/index.mdx b/src/pages/selfhosted/identity-providers/index.mdx
index 6063d1afc..927602f3f 100644
--- a/src/pages/selfhosted/identity-providers/index.mdx
+++ b/src/pages/selfhosted/identity-providers/index.mdx
@@ -58,7 +58,6 @@ For organizations with specific requirements or existing IdP investments:
---
-
## Adding External Identity Providers
NetBird supports connecting **multiple external identity providers** alongside local user management. This allows users to sign in with their existing accounts from services like Google, Microsoft, or your corporate identity provider—while still maintaining the option for local username/password authentication.
@@ -297,7 +296,6 @@ Managed Identity Providers handle infrastructure and maintenance for you. See ea
In addition to OIDC-based authentication, NetBird supports provisioning users and groups through SCIM and the API. However, this functionality is not available in the open source Community Edition. It is offered only in the cloud-managed version of NetBird or through a [Commercial License](https://netbird.io/pricing#on-prem) for enterprise self-hosted deployments.
-
## Migration Guide
If you have an existing NetBird deployment using a standalone IdP (like Zitadel from the previous quickstart), you have several options:
diff --git a/src/pages/selfhosted/identity-providers/local.mdx b/src/pages/selfhosted/identity-providers/local.mdx
index d9eb13134..4e35ddeff 100644
--- a/src/pages/selfhosted/identity-providers/local.mdx
+++ b/src/pages/selfhosted/identity-providers/local.mdx
@@ -115,7 +115,6 @@ openssl rand -base64 32
Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures.
-
## User Management
### Creating Users via Dashboard
@@ -186,7 +185,6 @@ Users created through the embedded IdP can be assigned roles:
| **Admin** | Manage users, peers, policies, and settings |
| **User** | Connect devices, view assigned resources |
-
## Instance Setup (First Run)
When NetBird starts with the embedded IdP and no existing accounts, the Dashboard redirects to the `/setup` route and displays the **Instance Setup Wizard**:
From 16d96bcc45fe31fb0b0d05bdc9d29bef45bcf906 Mon Sep 17 00:00:00 2001
From: braginini
Date: Tue, 6 Jan 2026 23:59:41 -0500
Subject: [PATCH 14/18] Update idp doc
---
.../selfhosted/identity-providers/add-idp.png | Bin 0 -> 442025 bytes
.../identity-providers/idp-list.png | Bin 0 -> 279581 bytes
.../identity-providers/idp-login.png | Bin 0 -> 88526 bytes
.../identity-providers/idp-main-2.png | Bin 0 -> 118205 bytes
.../identity-providers/idp-main.png | Bin 0 -> 177819 bytes
.../identity-providers/user-list.png | Bin 0 -> 231046 bytes
src/components/NavigationDocs.jsx | 6 +-
.../selfhosted/identity-providers/index.mdx | 245 +++++-------------
8 files changed, 71 insertions(+), 180 deletions(-)
create mode 100644 public/docs-static/img/selfhosted/identity-providers/add-idp.png
create mode 100644 public/docs-static/img/selfhosted/identity-providers/idp-list.png
create mode 100644 public/docs-static/img/selfhosted/identity-providers/idp-login.png
create mode 100644 public/docs-static/img/selfhosted/identity-providers/idp-main-2.png
create mode 100644 public/docs-static/img/selfhosted/identity-providers/idp-main.png
create mode 100644 public/docs-static/img/selfhosted/identity-providers/user-list.png
diff --git a/public/docs-static/img/selfhosted/identity-providers/add-idp.png b/public/docs-static/img/selfhosted/identity-providers/add-idp.png
new file mode 100644
index 0000000000000000000000000000000000000000..ad78d01de7bc043ae8d1c4759840f889c7b3a8fa
GIT binary patch
literal 442025
zcmb5Vbyyrd_dg7j7AWo%C{jvsD7H8hFBF$9?hcDB?i7j?D^_H2hXodQDaDFYY+-RI
z?(Xn%KmPu{|J^tTkgG-8WIvZ0tx9E7W%Wt
zl6hU|^`x@xpFqxr!LsQ66CdBLL+
z2j~C^0-6M}C*s`(B*c1{%&&|jfzm`mG$cfo)r{wDS}Lkj-JkS5<58OSSr&yB`7Z7+
zGPxfF!25GtNJZ2eU%DHMo*{YWpvdXHM>18AXAYWpg7@xO>UR<{C(kRBj|vK?0RWHt
z=GJDM)@*&J1nax%hxXJrhF?dXAcY6=r)Q1~1YIH_dGIQ;G9d*puCf&ng_)B9ve*JK
zBwF5wa1%G^gp3n=#LO|!Mq@isAem{h1LH6P5cEH}pL?dLNS5K6SmGNpqP$B-u5>V1
zcrDsxjW;Vn&Dq7}YjKS$nBqUKKt1-`nLD(?gx#4A?fFS}z$yq0?t(&|!vdlUYHEF#3(%rok^Xd><&i%k)0f9@&RRn&`NM+gs#-5x
zxSVy$*IMb-hvEmp58qX{O>LyLG5YY-Y3o>t-bjm=KC4vsQ}SsTvvg4<5waPTeH9hI
z=78ap_Kt`kYqa+{_v;QP`G>fc+m0&}it6ArM*0Qd*F?OMBHXE-)&7%Ea0fevRB4y^
zOY!^Uu#U#Vr-9;M8cjz~bGkh8htZtG-=&$bDiLq=Fy1+V#qGl)`9i08+us@pkSH?;
zV5()uScYMm5D-vJDG8-b2rF=6?~
zsyW$Ka!Z_M!4F}>pQF%DhCVA!Jsez#p9^(9!u28u3JdH~F?st7hp)@m
z$w3%}>dqM4kI*6z
z{g^eV?OUBR;Y`XRx?9nDIhx`fjbD29$=Ohf)UfaooR!-!x>#5Filc0R`=(V
zJT%WJ9|=wk;z^k(Ra+O-ekpA${?veIS?*tbR`^Xw`d>a~@op;BAd3VVyn|)yZ(`O^
zKS_RG5RqaWO-5*H`b&%XTcBKpwid?6=t-k9E$)^PU_|qGL8=@N^9%<8ZK2p03vG1R~MvKE`O6{U2{`y7ER!&HcEpH&t
zehjVZ`AovD1kRhnIO*S>znzb9jyaFbkJXPYzdY;yvLYQ`aL6>yIKZgOIFt~PVBc?9
z@@6t*TT(I0LVZJxrRZ!zeWH1SkC~ZyojHTKl35~AfSH)tTVuFHSmmmyB;N+s|M6uZ
zv!;GYlj2#!Hrpg05BX5)y7Gs7;?ZwoHr5Q*7uM7hn>I=|l)P;SyISVjXSD-19Ft7j
zAGcZ0Ft(+)*S2paIZ7^URCr2xr^)rAw8=HeLwW42PHo3{Wo=|^*R9!q&1HKkourV+
z4d}4EkAT&_v#p+zE0cAJv=_G=_dLBiWjj?rwFl+YMFC`mbelE2liWhxGNZpmLzUu&
zHPV^Wa|QLAlFMt^W%+>aDf^=HJ58CVk!M<7D6QRIXI@EX3p=>u7jV+eq|Jk=_JW7L
z0AoC}ucj40vVJXP(Arx$klFHgJGL$}buJhqI$J`ILK3lN`F88@ZOj~qEP3Xws#Tj+
z+bhGJ!YZdd%8uk#4G8rK{p0Q8HQ)3qcqwcZv=vB>
zIaO{5km8!`3#jK*=E<~do4w6=I{C>u*0{1iXEJAGY=UddImA4D4aD+=c$|5_CTj8p
z^kNDy)i;G%Mp2eIvpMT%_r-48ZXYpbcW1{iJ2h=kONZdxbKaer(XW!-o8PV8h3;|)
zX5sAPNQAoLq<3O;iiAdlz_Hqwi?)9{v$~XmeU|ceh?aRqihpgbp%35}(|wHO=U#zS
zL%`)HBpX6>wK5@5X?#_lzimmqNi#kq4os@nsCML9#MqFZ^-p$aE;TKj6;RBxje)Xt
zp|e1DT=#JAR_~b5eA!gl+FtAe0Cz}Zu;*0#(u*a5*^{shSq^s?3e4BQ-&4qI!{gx4
z4}h?!F*^PBE5>Kgw?P!*)8zA_&AN@kxA}JPw!x3r5BHAk_Uc~uF0*P^Yo;{4Gzoba
zIW8aw`C!IiH)VG