sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-16 15:36:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

No IdP required, Multiple IdPs supported, Onboarding flow

Browse Source
This commit is contained in:
Brandon Hopkins
2026-01-05 14:01:25 -08:00
parent 5d31b84c22
commit 30112ebbae
5 changed files with 118 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
src/pages/selfhosted/identity-providers/connectors.mdx
View File

@@ -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

58
src/pages/selfhosted/identity-providers/embedded-idp.mdx
View File

@@ -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
```
<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>

41
src/pages/selfhosted/identity-providers/index.mdx
View File

@@ -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.

16
src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx
View File

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

61
src/pages/selfhosted/selfhosted-quickstart.mdx
View File

@@ -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)
</Note>
## 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.
<Note>
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).
</Note>
### 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.
</Note>
### 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.
<Note>
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.
</Note>
### 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**
For detailed setup guides, see [Identity Provider Connectors](/selfhosted/identity-providers/connectors).
**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 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
<Note>
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.
</Note>
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.