mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-16 07:26:35 +00:00
Condense Pages to index.mdx and Extra Remove Idp Info Quickstart
This commit is contained in:
Brandon Hopkins
@@ -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',
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
<Note>
|
||||
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)
|
||||
@@ -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": "<auto-generated-base64-key>"
|
||||
}
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
<Note>
|
||||
Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures.
|
||||
</Note>
|
||||
|
||||
## 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
|
||||
|
||||
<Note>
|
||||
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
|
||||
|
||||
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"
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
The `password` field is only included when creating users with embedded IdP. Store it immediately—it won't be returned in subsequent API calls.
|
||||
</Note>
|
||||
|
||||
### 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
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
### 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.
|
||||
|
||||
<Note>
|
||||
The Identity Providers tab is only visible when `embedded_idp_enabled` is `true` in your account settings.
|
||||
</Note>
|
||||
|
||||
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
|
||||
|
||||
<Note>
|
||||
Disabling the embedded IdP will invalidate all local user accounts. Ensure users have accounts in the external IdP before switching.
|
||||
</Note>
|
||||
@@ -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
|
||||
|
||||
<Note>
|
||||
The Identity Providers tab is only visible when local user management is enabled (default for new installations).
|
||||
</Note>
|
||||
|
||||
### 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.
|
||||
|
||||
@@ -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
|
||||
|
||||
<Note>
|
||||
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)
|
||||
|
||||
## 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:
|
||||
|
||||
---
|
||||
|
||||
<a id="local-user-management"></a>
|
||||
## 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
|
||||
|
||||
<Note>
|
||||
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)
|
||||
|
||||
### 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.
|
||||
|
||||
<a id="configuration"></a>
|
||||
### 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": "<auto-generated-base64-key>"
|
||||
}
|
||||
```
|
||||
|
||||
#### 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
|
||||
```
|
||||
|
||||
<Note>
|
||||
Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures.
|
||||
</Note>
|
||||
|
||||
<a id="user-management"></a>
|
||||
### 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
|
||||
|
||||
<Note>
|
||||
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
|
||||
|
||||
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"
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
The `password` field is only included when creating users with embedded IdP. Store it immediately—it won't be returned in subsequent API calls.
|
||||
</Note>
|
||||
|
||||
#### 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 |
|
||||
|
||||
<a id="instance-setup-first-run"></a>
|
||||
### 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
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
#### 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
|
||||
|
||||
<Note>
|
||||
Disabling the embedded IdP will invalidate all local user accounts. Ensure users have accounts in the external IdP before switching.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
<a id="adding-external-identity-providers"></a>
|
||||
## 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.
|
||||
|
||||
<Note>
|
||||
The Identity Providers tab is only visible when `embedded_idp_enabled` is `true` in your account settings (default for new installations).
|
||||
</Note>
|
||||
|
||||
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
|
||||
|
||||
<Note>
|
||||
User data and network configurations are preserved during migration. Only authentication changes—users may need to re-authenticate after the switch.
|
||||
</Note>
|
||||
|
||||
[Detailed Migration Guide →](/selfhosted/identity-providers/migration)
|
||||
</Note>
|
||||
@@ -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.
|
||||
|
||||
<Note>
|
||||
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)
|
||||
@@ -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.
|
||||
|
||||
<Note>
|
||||
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)
|
||||
- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
|
||||
@@ -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.
|
||||
|
||||
<Note>
|
||||
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)
|
||||
- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
|
||||
@@ -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)
|
||||
- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
|
||||
@@ -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.
|
||||
|
||||
<Note>
|
||||
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)
|
||||
- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
|
||||
@@ -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.
|
||||
|
||||
<Note>
|
||||
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)
|
||||
- [Embedded IdP Overview](/selfhosted/identity-providers#local-user-management)
|
||||
@@ -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)
|
||||
@@ -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.
|
||||
|
||||
<Note>
|
||||
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)
|
||||
@@ -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.
|
||||
|
||||
<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 standalone IdPs, see the [Advanced guide](/selfhosted/selfhosted-guide).
|
||||
For advanced setups, 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:**
|
||||
@@ -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.
|
||||
|
||||
<Note>
|
||||
The `/setup` page is only accessible when no users exist. After creating the first user, it redirects to the regular login page.
|
||||
|
||||
Reference in New Issue
Block a user