diff --git a/src/components/NavigationAPI.jsx b/src/components/NavigationAPI.jsx index 48d220c0..4f46572d 100644 --- a/src/components/NavigationAPI.jsx +++ b/src/components/NavigationAPI.jsx @@ -23,7 +23,6 @@ export const apiNavigation = [ links: [ { title: 'Accounts', href: '/api/resources/accounts' }, { title: 'Users', href: '/api/resources/users' }, - { title: 'Identity Providers', href: '/api/resources/identity-providers' }, { title: 'Tokens', href: '/api/resources/tokens' }, { title: 'Peers', href: '/api/resources/peers' }, { title: 'Ingress Ports', href: '/api/resources/ingress-ports' }, diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 59ca480e..2c705ad6 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -282,12 +282,13 @@ export const docsNavigation = [ { title: 'SELF-HOST NETBIRD', links: [ - { title: 'Quickstart guide', href: '/selfhosted/selfhosted-quickstart' }, + { title: 'Quickstart Guide', href: '/selfhosted/selfhosted-quickstart' }, { - title: 'Supported IdPs', + title: 'Accounts and IdPs', isOpen: false, links: [ - { title: 'Using IdPs on Self-Hosted', href: '/selfhosted/identity-providers' }, + { title: 'Identity Providers', href: '/selfhosted/identity-providers' }, + { title: 'Local User Accounts', href: '/selfhosted/identity-providers/local' }, { title: 'Self-hosted IdPs', isOpen: true, diff --git a/src/pages/selfhosted/identity-providers/authentik.mdx b/src/pages/selfhosted/identity-providers/authentik.mdx index 184f42a3..88141618 100644 --- a/src/pages/selfhosted/identity-providers/authentik.mdx +++ b/src/pages/selfhosted/identity-providers/authentik.mdx @@ -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#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. +For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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. If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like [Auth0](/selfhosted/identity-providers/managed/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#local-user-management) +- [Embedded IdP Overview](/selfhosted/identity-providers/local) - [API Reference](/api/resources/identity-providers) \ No newline at end of file diff --git a/src/pages/selfhosted/identity-providers/index.mdx b/src/pages/selfhosted/identity-providers/index.mdx index 667928cd..6063d1af 100644 --- a/src/pages/selfhosted/identity-providers/index.mdx +++ b/src/pages/selfhosted/identity-providers/index.mdx @@ -31,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 -See the [Local User Management](#local-user-management) section below for setup details. +See the [Local User Management](/selfhosted/identity-providers/local) page for setup details. ### Local Users + External Identity Providers @@ -56,343 +56,6 @@ For organizations with specific requirements or existing IdP investments: [Advanced IdP Setup →](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp) -## 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 - - -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. - - -[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. - - -### 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": "" -} -``` - -#### 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 -``` - - -Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures. - - - -### 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 - - -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. - - -#### 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" -} -``` - - -The `password` field is only included when creating users with embedded IdP. Store it immediately—it won't be returned in subsequent API calls. - - -#### 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 - - -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. - - -#### 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 - - -Disabling the embedded IdP will invalidate all local user accounts. Ensure users have accounts in the external IdP before switching. - - --- diff --git a/src/pages/selfhosted/identity-providers/keycloak.mdx b/src/pages/selfhosted/identity-providers/keycloak.mdx index 19130474..a94f5774 100644 --- a/src/pages/selfhosted/identity-providers/keycloak.mdx +++ b/src/pages/selfhosted/identity-providers/keycloak.mdx @@ -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#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. +For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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. If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like [Auth0](/selfhosted/identity-providers/managed/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#local-user-management) +- [Embedded IdP Overview](/selfhosted/identity-providers/local) - [API Reference](/api/resources/identity-providers) \ No newline at end of file diff --git a/src/pages/selfhosted/identity-providers/local.mdx b/src/pages/selfhosted/identity-providers/local.mdx new file mode 100644 index 00000000..d9eb1313 --- /dev/null +++ b/src/pages/selfhosted/identity-providers/local.mdx @@ -0,0 +1,336 @@ +# 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 0.62, 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 + + +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. + + +[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. + +## 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": "" +} +``` + +### 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 +``` + + +Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures. + + + +## 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 + + +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. + + +### 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" +} +``` + + +The `password` field is only included when creating users with embedded IdP. Store it immediately—it won't be returned in subsequent API calls. + + +### 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 + + +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. + + +### 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 + + +Disabling the embedded IdP will invalidate all local user accounts. Ensure users have accounts in the external IdP before switching. + + diff --git a/src/pages/selfhosted/identity-providers/managed/auth0.mdx b/src/pages/selfhosted/identity-providers/managed/auth0.mdx index 87b36937..f2f06ea2 100644 --- a/src/pages/selfhosted/identity-providers/managed/auth0.mdx +++ b/src/pages/selfhosted/identity-providers/managed/auth0.mdx @@ -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#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. +For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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. 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#local-user-management) \ No newline at end of file +- [Embedded IdP Overview](/selfhosted/identity-providers/local) \ No newline at end of file diff --git a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx index d03c18fa..09c9b810 100644 --- a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx +++ b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx @@ -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#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. +For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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. 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#local-user-management) \ No newline at end of file +- [Embedded IdP Overview](/selfhosted/identity-providers/local) \ No newline at end of file diff --git a/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx b/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx index c5d6738d..d3b17e88 100644 --- a/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx +++ b/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx @@ -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#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. +For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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#local-user-management) \ No newline at end of file +- [Embedded IdP Overview](/selfhosted/identity-providers/local) \ No newline at end of file diff --git a/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx b/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx index ce37eb82..4803dd16 100644 --- a/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx +++ b/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx @@ -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#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. +For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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. 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#local-user-management) \ No newline at end of file +- [Embedded IdP Overview](/selfhosted/identity-providers/local) \ No newline at end of file diff --git a/src/pages/selfhosted/identity-providers/managed/okta.mdx b/src/pages/selfhosted/identity-providers/managed/okta.mdx index 10ce517e..601f789c 100644 --- a/src/pages/selfhosted/identity-providers/managed/okta.mdx +++ b/src/pages/selfhosted/identity-providers/managed/okta.mdx @@ -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#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. +For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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. 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#local-user-management) \ No newline at end of file +- [Embedded IdP Overview](/selfhosted/identity-providers/local) \ No newline at end of file diff --git a/src/pages/selfhosted/identity-providers/pocketid.mdx b/src/pages/selfhosted/identity-providers/pocketid.mdx index 0f1e5f06..d506e2d6 100644 --- a/src/pages/selfhosted/identity-providers/pocketid.mdx +++ b/src/pages/selfhosted/identity-providers/pocketid.mdx @@ -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#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. +For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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#local-user-management) +- [Embedded IdP Overview](/selfhosted/identity-providers/local) - [API Reference](/api/resources/identity-providers) \ No newline at end of file diff --git a/src/pages/selfhosted/identity-providers/zitadel.mdx b/src/pages/selfhosted/identity-providers/zitadel.mdx index e89a363c..9d331081 100644 --- a/src/pages/selfhosted/identity-providers/zitadel.mdx +++ b/src/pages/selfhosted/identity-providers/zitadel.mdx @@ -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#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. +For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) 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. 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#local-user-management) +- [Embedded IdP Overview](/selfhosted/identity-providers/local) - [Migration Guide](/selfhosted/identity-providers#migration-guide) \ No newline at end of file diff --git a/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx b/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx index 9751fe8b..93e80c2b 100644 --- a/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx +++ b/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx @@ -20,7 +20,7 @@ a reliable manner. NetBird is not just one VPN server. You can read more about h ## What's New: No External IdP Required -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: +Starting with version 0.62, 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) diff --git a/src/pages/selfhosted/selfhosted-quickstart.mdx b/src/pages/selfhosted/selfhosted-quickstart.mdx index c9081e60..41e54e7a 100644 --- a/src/pages/selfhosted/selfhosted-quickstart.mdx +++ b/src/pages/selfhosted/selfhosted-quickstart.mdx @@ -171,7 +171,7 @@ For more troubleshooting help, see the [Troubleshooting guide](/selfhosted/troub ## Legacy: Self-hosting with Zitadel IdP -**Deprecated**: This method is no longer recommended for new installations. It is preserved as a reference for users who deployed NetBird using the Zitadel quickstart script prior to version X.XX. For new installations, use the [quickstart approach](#quick-self-hosting) above. +**Deprecated**: This method is no longer recommended for new installations. It is preserved as a reference for users who deployed NetBird using the Zitadel quickstart script prior to version 0.62. For new installations, use the [quickstart approach](#quick-self-hosting) above. The following instructions apply to deployments using the `getting-started-with-zitadel.sh` script, which bundled Zitadel as an external identity provider.