mirror of
https://github.com/netbirdio/docs.git
synced 2026-05-04 08:16:35 +00:00
No IdP required, Multiple IdPs supported, Onboarding flow
This commit is contained in:
Brandon Hopkins
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user