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

import {Note} from "../../../components/mdx";

# Authentication and Identity Providers (IdPs)

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/idp-main.png" alt="Identity Providers List" className="imagewrapper-big"/>
</p>

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.

<Note> 
While we maintain a list of 'supported' (tested) IdPs, **any OIDC provider should work with NetBird's 'OIDC (Generic)' connector**.
</Note>

## How Authentication Works in NetBird

When a user attempts to access the NetBird dashboard from a web browser or an internal resource from their device,
authentication is handled by the configured identity provider. Upon successful authentication, the identity provider
issues a [JSON Web Token (JWT)](https://en.wikipedia.org/wiki/JSON_Web_Token) containing the user's identity and claims. The Management Service validates this token to
verify the user's identity and grant access.

By default, NetBird does not require an external identity provider. New installations include a built-in authentication
system that lets you create and manage users directly through the Dashboard using local username and password authentication.
External identity providers are entirely optional. Add them when you need SSO integration with Google, Microsoft, Okta, or
self-hosted identity providers like Keycloak or Authentik, and more.

## Local User Management

Refer to the [Local User Management](/selfhosted/identity-providers/local) page for detailed instructions on using local users
authentication.

## External Identity Providers

NetBird supports connecting **multiple external identity providers** [alongside local user management](/selfhosted/identity-providers/local).
This allows users to sign in with their existing accounts from services like Google, Microsoft and your corporate or self-hosted identity
provider, while still maintaining the option for local username/password authentication.

NetBird supports any OIDC-compliant identity providers. Here are some popular providers and their setup instructions:

| Provider | Type | Best For |
|----------|------|----------|
| [**Generic OIDC**](/selfhosted/identity-providers/generic-oidc) | `oidc` | Any OIDC-compliant provider (custom/unsupported IdPs) |
| [**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` | Open-source IAM with multi-tenancy and passwordless auth |
| [**Keycloak**](/selfhosted/identity-providers/keycloak) | `keycloak` |  Popular open source IAM with extensive enterprise features |
| [**Authentik**](/selfhosted/identity-providers/authentik) | `authentik` | Flexible open source IdP with SSO, MFA, and policy engine |
| [**Pocket ID**](/selfhosted/identity-providers/pocketid) | `pocketid` | Lightweight OIDC provider with passkey authentication |
| [**Duo SSO**](/selfhosted/identity-providers/managed/duo) | `oidc` | Provides secure one-login access with MFA |

<Note>
    Any identity provider that supports OpenID Connect can be integrated with NetBird. If your provider isn't listed above,
    use the generic OIDC configuration.
</Note>

### Adding an Identity Provider

#### Via Dashboard

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/idp-list.png" alt="Identity Providers List" className="imagewrapper-big"/>
</p>

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** - From your identity provider
6. Copy the **Redirect URL** and configure it in your identity provider
7. Click **Save**

<Note>
    Make sure you are creating a confidential OIDC client in your identity provider. The secret will be stored privately in
    your NetBird installation and will never be exposed to the public.
</Note>

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/add-idp.png" alt="Identity Providers List" className="imagewrapper-big"/>
</p>

#### 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"
  }'
```

For instance setup endpoints, see [Accounts API](/api/resources/accounts). For user creation with embedded IdP, see [Users API](/api/resources/users).

### Managing Identity Providers via API

```bash
# List configured identity providers
curl "https://netbird.example.com/api/identity-providers" \
  -H "Authorization: Bearer ${TOKEN}"

# Update an identity provider
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 an identity providers
curl -X DELETE "https://netbird.example.com/api/identity-providers/{id}" \
  -H "Authorization: Bearer ${TOKEN}"
```

### 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 an external identity provider appear in your Users list with a badge showing their identity provider.

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/user-list.png" alt="Identity Providers List" className="imagewrapper-big"/>
</p>

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

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/idp-login.png" alt="Multiple Identity Providers" className="imagewrapper"/>
</p>

### User Provisioning

#### JWT Group Sync 

If you've connected an external IdP, NetBird can optionally fetch a user's groups via JWT claim. These groups automatically obtain representations within NetBird and will be applied to the corresponding NetBird user. To enable JWT group sync, 
navigate to Settings > Groups and toggle 'Enable JWT group sync'. 

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/jwt-group-sync.png" alt="JWT Group Sync Settings" className="imagewrapper"/>
</p>

Specify the JWT claim to be used as the user's groups list (normally 'groups'). You can optionally specify a 'JWT allow groups' - this group will need to exist in your chosen claim for the user in order for that user to be granted access to NetBird. 
Your IdP may require specific configuration in order to pass a groups claim to NetBird. For detailed per-IdP implementation steps, see below. If your IdP isn't on the list, refer to the project's documentation. 

- [Google](/selfhosted/identity-providers/managed/google-workspace#configuring-jwt-groups-claim)
- [Microsoft Entra ID](/selfhosted/identity-providers/managed/microsoft-entra-id#configuring-jwt-groups-claim)
- [Okta](/selfhosted/identity-providers/managed/okta#configuring-jwt-groups-claim)
- [JumpCloud](/selfhosted/identity-providers/managed/jumpcloud#configuring-jwt-groups-claim)
- [Zitadel](/selfhosted/identity-providers/zitadel#configuring-jwt-groups-claim)
- [PocketID](/selfhosted/identity-providers/pocketid#configuring-jwt-groups-claim)
- [Authentik](/selfhosted/identity-providers/authentik#configuring-jwt-groups-claim)
- [Keycloak](/selfhosted/identity-providers/keycloak#configuring-jwt-groups-claim)

<Note> 
Groups with matching names in NetBird and your IdP will **not** sync. To import a group from your IdP, first delete the existing group with that name in NetBird.
</Note>

#### SCIM 
NetBird supports provisioning users and groups through SCIM. 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.

### 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 in your IdP. Some providers like Pocket ID block all users by default unless you unrestrict groups in the OIDC client configuration.

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

## Migration Guide and Backwards Compatibility

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.
This option requires a migration as user IDs have a different format. See below.

<Note>
    We are working on a migration tool to automate the process of switching from standalone IdPs to external providers.
    Please contact us at [](mailto:support@netbird.io) if you are interested in this feature.
</Note>