No IdP required, Multiple IdPs supported, Onboarding flow

Author: TechHutTV

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
 
 <Note>
-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).
 </Note>
 
 ### 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
 

src/pages/selfhosted/identity-providers/embedded-idp.mdx

@@ -1,51 +1,53 @@
-# 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 |
 | **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:
+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
 ```
 
 <Note>
-**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.
 </Note>
 
 ## User Management
@@ -117,7 +119,7 @@ After creation, a modal displays with:
 - **Copy & Close** button to copy password and dismiss
 
 <Note>
-**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.
 </Note>
 
 ### 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
 
 <Note>
-**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.
 </Note>

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
 
 <Note>
-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.
 </Note>
 
 [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
 
 <Note>
 User data and network configurations are preserved during migration. Only authentication changes—users may need to re-authenticate after the switch.

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+) |