netbird-docs/src/pages/selfhosted/identity-providers/index.mdx

# Supported Identity Providers (IdPs)

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.

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

This approach provides several key benefits:

- **Simplified setup** with the embedded IdP—no separate infrastructure required
- **Flexibility to integrate** with your existing identity infrastructure
- **Single Sign-On (SSO)** across your organization through connectors
- **Security through token-based authentication**
- **Privacy-conscious caching** of user information without storing sensitive data

## Choosing Your Authentication Approach

| Approach | Best For | Setup Complexity |
|----------|----------|------------------|
| **Local Users Only** | Homelabs, small teams, quick deployments | Minimal |
| **Local Users + External IdPs** | Organizations wanting SSO with existing providers | Low |
| **Standalone IdP (Advanced)** | Enterprises with existing IdP investments, SCIM requirements | Moderate to High |

### Local Users Only

The simplest approach—create and manage users directly in NetBird:

- Local username/password authentication
- No additional services required
- 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.

### Local Users + External Identity Providers

Combine local user management with your existing identity providers:

- Keep local user management as a fallback
- Add Google, Microsoft, Okta, or other providers for SSO
- **Configure multiple IdPs**—users see all options on the login page
- Configure everything directly from the Dashboard UI
- Best of both worlds

See the [Adding External Identity Providers](#adding-external-identity-providers) section below for setup details.

### Standalone IdP (Advanced)

For organizations with specific requirements or existing IdP investments:

- Full control over identity infrastructure
- Required for SCIM provisioning (Enterprise)
- Complex user lifecycle management needs
- Separate IdP container deployment

[Advanced IdP Setup →](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp)

---

<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/managed/google-workspace) | `google` | Google Workspace, personal Google accounts |
| [**Microsoft**](/selfhosted/identity-providers/managed/microsoft-entra-id) | `microsoft` / `entra` | Personal accounts, Azure AD / Entra ID |
| [**Okta**](/selfhosted/identity-providers/managed/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 Workspace](/selfhosted/identity-providers/managed/google-workspace)
- [Microsoft Entra ID](/selfhosted/identity-providers/managed/microsoft-entra-id)
- [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](/api/resources/identity-providers) for complete documentation. For instance setup endpoints, see [Accounts API](/api/resources/accounts). For user creation with embedded IdP, see [Users API](/api/resources/users).

### 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 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. See each provider's page for specific configuration instructions.

| Provider | Description |
|----------|-------------|
| [**Zitadel**](/selfhosted/identity-providers/zitadel) | Open-source identity platform with multi-tenancy, passwordless auth, and OIDC/SAML support |
| [**Keycloak**](/selfhosted/identity-providers/keycloak) | Popular open-source IAM with extensive documentation and community support |
| [**Authentik**](/selfhosted/identity-providers/authentik) | Flexible open-source IdP with SSO, MFA, and policy management |
| [**PocketID**](/selfhosted/identity-providers/pocketid) | Lightweight, easy-to-deploy identity solution for self-hosted environments |

### Cloud/Managed Providers

Managed Identity Providers handle infrastructure and maintenance for you. See each provider's page for specific configuration instructions.

| Provider | Description |
|----------|-------------|
| [**Google Workspace**](/selfhosted/identity-providers/managed/google-workspace) | Google accounts and Google Workspace authentication |
| [**Microsoft Entra ID**](/selfhosted/identity-providers/managed/microsoft-entra-id) | Microsoft personal accounts and Entra ID (Azure AD) for work accounts |
| [**Okta**](/selfhosted/identity-providers/managed/okta) | Enterprise identity and access management with extensive integrations |
| [**Auth0**](/selfhosted/identity-providers/managed/auth0) | Flexible authentication service with customization options |
| [**JumpCloud**](/selfhosted/identity-providers/managed/jumpcloud) | Cloud directory platform with identity and device management |

---

## User Provisioning

In addition to OIDC-based authentication, NetBird supports provisioning users and groups through SCIM and the API. However, this functionality is not available in the open source Community Edition. It is offered only in the cloud-managed version of NetBird or through a [Commercial License](https://netbird.io/pricing#on-prem) for enterprise self-hosted deployments.

<a id="migration-guide"></a>
## Migration Guide

If you have an existing NetBird deployment using a standalone IdP (like Zitadel from the previous quickstart), you have several options:

1. **Keep using your standalone IdP** - No changes required, your setup continues to work
2. **Add your IdP as an external provider** - Keep your IdP but add it as an OIDC provider alongside local users
3. **Migrate to local users** - Export users from your IdP and recreate them as local users

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