Update idp doc

src/components/NavigationDocs.jsx

@@ -284,11 +284,11 @@ export const docsNavigation = [
         links: [
             { title: 'Quickstart Guide', href: '/selfhosted/selfhosted-quickstart' },
             {
-                title: 'Accounts and IdPs',
+                title: 'Authentication',
                 isOpen: false,
                 links: [
-                    { title: 'Identity Providers', href: '/selfhosted/identity-providers' },
+                    { title: 'Authentication and IdPs', href: '/selfhosted/identity-providers' },
-                    { title: 'Local User Accounts', href: '/selfhosted/identity-providers/local' },
+                    { title: 'Local User Management', href: '/selfhosted/identity-providers/local' },
                     {
                         title: 'Self-hosted IdPs',
                         isOpen: true,

src/pages/selfhosted/identity-providers/index.mdx

@@ -1,78 +1,39 @@
-# Supported Identity Providers (IdPs)
+import {Note} from "../../../components/mdx";
 
-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.
+# Authentication and Identity Providers (IdPs)
 
-## How Authentication Works
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/idp-main.png" alt="Identity Providers List" className="imagewrapper-big"/>
+</p>
 
-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.
+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.
 
-This approach provides several key benefits:
+## How Authentication Works in NetBird
 
-- **Simplified setup** with the embedded IdP—no separate infrastructure required
+When a user attempts to access the NetBird dashboard from a web browser or an internal resource from their device,
-- **Flexibility to integrate** with your existing identity infrastructure
+authentication is handled by the configured identity provider. Upon successful authentication, the identity provider
-- **Single Sign-On (SSO)** across your organization through connectors
+issues a [JSON Web Token (JWT)](https://en.wikipedia.org/wiki/JSON_Web_Token) containing the user's identity and claims. The Management Service validates this token to
-- **Security through token-based authentication**
+verify the user's identity and grant access.
-- **Privacy-conscious caching** of user information without storing sensitive data
 
-## Choosing Your Authentication Approach
+By default, NetBird does not require an external identity provider. New installations include a built-in authentication
+system that lets you create and manage users directly through the Dashboard using local username and password authentication.
+External identity providers are entirely optional. Add them when you need SSO integration with Google, Microsoft, Okta, or
+self-hosted identity providers like Keycloak or Authentik.
 
-| Approach | Best For | Setup Complexity |
+## Local User Management
-|----------|----------|------------------|
-| **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 |
 
-### Local Users Only
+Refer to the [Local User Management](/selfhosted/identity-providers/local) page for detailed instructions on using local users
+authentication.
 
-The simplest approach—create and manage users directly in NetBird:
+## External Identity Providers
 
-- Local username/password authentication
+NetBird supports connecting **multiple external identity providers** [alongside local user management](/selfhosted/identity-providers/local).
-- No additional services required
+This allows users to sign in with their existing accounts from services like Google, Microsoft, or your corporate identity
-- User management through the Dashboard
+provider, while still maintaining the option for local username/password authentication.
-- Ideal for homelabs, small teams, and proof-of-concept deployments
 
-See the [Local User Management](/selfhosted/identity-providers/local) page for setup details.
+NetBird supports any OIDC-compliant identity providers. Here are some popular providers and their setup instructions:
-
-### Local Users + External Identity Providers
-
-Combine local user management with your existing identity providers:
-
-- Keep local user management as a fallback
-- 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
-
-See the [Adding External Identity Providers](#adding-external-identity-providers) section below for setup details.
-
-### Standalone IdP (Advanced)
-
-For organizations with specific requirements or existing IdP investments:
-
-- Full control over identity infrastructure
-- Required for SCIM provisioning (Enterprise)
-- Complex user lifecycle management needs
-- Separate IdP container deployment
-
-[Advanced IdP Setup →](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp)
-
----
-
-## 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 |
 |----------|------|----------|
@@ -80,15 +41,24 @@ External identity providers give you:
 | [**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 |
+| [**Zitadel**](/selfhosted/identity-providers/zitadel) | `zitadel` | Open-source IAM with multi-tenancy and passwordless auth |
-| [**Keycloak**](/selfhosted/identity-providers/keycloak) | `oidc` | Self-hosted Keycloak |
+| [**Keycloak**](/selfhosted/identity-providers/keycloak) | `keycloak` |  Popular open source IAM with extensive enterprise features |
-| [**Authentik**](/selfhosted/identity-providers/authentik) | `oidc` | Self-hosted Authentik |
+| [**Authentik**](/selfhosted/identity-providers/authentik) | `authentik` | Flexible open source IdP with SSO, MFA, and policy engine |
-| [**PocketID**](/selfhosted/identity-providers/pocketid) | `pocketid` | Lightweight self-hosted IdP |
+| [**PocketID**](/selfhosted/identity-providers/pocketid) | `pocketid` | Lightweight OIDC provider with passkey authentication |
 
-### Adding an Identity Provider
+<Note>
+    Any identity provider that supports OpenID Connect can be integrated with NetBird. If your provider isn't listed above,
+    use the generic OIDC configuration.
+</Note>
+
+    ### Adding an Identity Provider
 
 #### Via Dashboard
 
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/idp-list.png" alt="Identity Providers List" className="imagewrapper-big"/>
+</p>
+
 1. Log in to your NetBird Dashboard
 2. Navigate to **Settings** → **Identity Providers**
 3. Click **Add Identity Provider**
@@ -97,22 +67,18 @@ External identity providers give you:
    - **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
+   - **Issuer** - From your identity provider
-6. Click **Save**
+6. Copy the **Redirect URL** and configure it in your identity provider
-7. Copy the **Redirect URL** and configure it in your identity provider
+7. 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.
 
 <Note>
-The Identity Providers tab is only visible when `embedded_idp_enabled` is `true` in your account settings (default for new installations).
+    Make sure you are creating a confidential OIDC client in your identity provider. The secret will be stored privately in
+    your NetBird installation and will never be exposed to the public.
 </Note>
 
-For detailed setup instructions for each provider, see the individual provider pages:
+<p>
-- [Google Workspace](/selfhosted/identity-providers/managed/google-workspace)
+    <img src="/docs-static/img/selfhosted/identity-providers/add-idp.png" alt="Identity Providers List" className="imagewrapper-big"/>
-- [Microsoft Entra ID](/selfhosted/identity-providers/managed/microsoft-entra-id)
+</p>
-- [Keycloak](/selfhosted/identity-providers/keycloak)
-- [Zitadel](/selfhosted/identity-providers/zitadel)
-- [All Providers →](/selfhosted/identity-providers)
 
 #### Via API
 
@@ -131,35 +97,14 @@ curl -X POST "https://netbird.example.com/api/identity-providers" \
 
 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
+### Managing Identity Providers via API
 
 ```bash
-# List configured connectors
+# List configured identity providers
 curl "https://netbird.example.com/api/identity-providers" \
   -H "Authorization: Bearer ${TOKEN}"
 
-# Add a Google connector
+# Update an identity provider
-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" \
@@ -167,27 +112,11 @@ curl -X PUT "https://netbird.example.com/api/identity-providers/{id}" \
     "name": "Updated Name"
   }'
 
-# Delete a connector
+# Delete an identity providers
 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
@@ -196,7 +125,11 @@ Some providers also require:
 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.
+Users who authenticate via an external identity provider appear in your Users list with a badge showing their identity provider.
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/user-list.png" alt="Identity Providers List" className="imagewrapper-big"/>
+</p>
 
 ### Multiple Identity Providers
 
@@ -207,16 +140,11 @@ You can configure **multiple identity providers simultaneously**:
 - 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.
+This allows you to support different authentication methods for different user groups.
 
-### Login Flow
+<p>
-
+    <img src="/docs-static/img/selfhosted/identity-providers/idp-login.png" alt="Multiple Identity Providers" className="imagewrapper"/>
-When embedded IdP is enabled with external connectors, the login page displays:
+</p>
-
-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
 
@@ -253,57 +181,20 @@ Users can choose their preferred authentication method.
 
 For provider-specific troubleshooting, see the individual provider pages.
 
----
+## User Provisioning (SCIM)
 
-## Identity Provider Options
+In addition to OIDC-based authentication, NetBird supports provisioning users and groups through SCIM.
+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.
 
-Each provider page includes specific setup instructions for both **connector setup** (recommended, for adding to local user management) and **standalone setup** (advanced).
+## Migration Guide and Backwards Compatibility
-
-### 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. See each provider's page for specific configuration instructions.
-
-| 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 |
-
-### Cloud/Managed Providers
-
-Managed Identity Providers handle infrastructure and maintenance for you. See each provider's page for specific configuration instructions.
-
-| Provider | Description |
-|----------|-------------|
-| [**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 |
-
----
-
-## 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.
-
-## Migration Guide
 
 If you have an existing NetBird deployment using a standalone IdP (like Zitadel from the previous quickstart), you have several options:
 
 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
+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
+This option requires a migration as user IDs have a different format. See below.
 
 <Note>
-User data and network configurations are preserved during migration. Only authentication changes—users may need to re-authenticate after the switch.
+    We are working on a migration tool to automate the process of switching from standalone IdPs to external providers.
+    Please contact us at [](mailto:support@netbird.io) if you are interested in this feature.
 </Note>