sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-19 08:56:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

DEX Docs Overall Updates

Browse Source
This commit is contained in:
Brandon Hopkins
2026-01-05 13:28:12 -08:00
parent ec76ca2524
commit 5d31b84c22
22 changed files with 4756 additions and 910 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
src/pages/selfhosted/identity-providers/index.mdx
View File

@@ -1,90 +1,123 @@
import { Note, Button } from '@/components/mdx'
# Supported Identity Providers (IdPs)
NetBird’s self-hosted implementation (Community Edition) 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.
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.
There are several Identity Provider (IdP) options available for running a self-hosted version of NetBird. This document provides
an overview of each option along with links to detailed setup guides.
## Embedded IdP (Recommended)
Starting with version X.XX, NetBird includes a **built-in identity provider** powered by [Dex](https://dexidp.io/). This is now the default for new deployments and eliminates the need for separate IdP infrastructure.
With the embedded IdP, you can:
- **Create local users** directly from the NetBird Dashboard
- **Add SSO connectors** (Google, Microsoft, Okta, etc.) through the Dashboard UI
- **Simplify your deployment** with fewer containers and reduced resource requirements
- **Get started faster** with automatic configuration and no additional setup
<Note>
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.
The embedded IdP uses [Dex](https://dexidp.io/), a lightweight, portable OIDC identity provider that supports federated authentication. Dex runs embedded within the NetBird Management service, requiring no additional containers or databases.
</Note>
## Our Approach
[Get Started →](/selfhosted/selfhosted-quickstart)
When a user attempts to access the NetBird network, the Management Service redirects them to your configured Identity Provider for authentication. After successful authentication, the IdP issues a JSON Web Token (JWT) that contains 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.
## How Authentication Works
This approach provides several key benefits: it leverages your existing identity infrastructure, enables Single Sign-On (SSO) across your organization, maintains security through token-based authentication, and allows NetBird to cache user information like names and email addresses without storing sensitive data.
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.
## Self-hosted IdPs
This approach provides several key benefits:
Self-hosted Identity Providers give you full control over authentication and authorization of your NetBird network. You manage and maintain the IdP infrastructure yourself.
- **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
### Zitadel
## Choosing Your Authentication Approach
[Zitadel](https://github.com/zitadel/zitadel) is an open-source identity infrastructure platform designed for cloud-native environments. It provides multi-tenancy, customizable branding, passwordless authentication, and supports protocols like OpenID Connect, OAuth2, SAML2, and LDAP. Zitadel offers features such as passkeys (FIDO2), OTP, SCIM 2.0 server, and unlimited audit trails.
| Approach | Best For | Setup Complexity |
|----------|----------|------------------|
| **Embedded IdP Only** | Homelabs, small teams, quick deployments | Minimal |
| **Embedded IdP + Connectors** | Organizations wanting SSO with existing providers | Low |
| **Standalone IdP (Advanced)** | Enterprises with existing IdP investments, SCIM requirements | Moderate to High |
<Button href="/selfhosted/identity-providers/zitadel" variant="outline">Setup Zitadel</Button>
### Embedded IdP Only
### Authentik
The simplest approach—create and manage users directly in NetBird:
[Authentik](https://github.com/goauthentik/authentik) is an open-source identity provider focused on flexibility and security. It serves as a self-hosted alternative to commercial solutions like Okta and Auth0, providing single sign-on (SSO), multi-factor authentication (MFA), access policies, user management, and support for SAML and OIDC protocols. Authentik includes audit logging, password policies, and full API access for automation.
- Local username/password authentication
- No additional services required
- User management through the Dashboard
- Ideal for homelabs, small teams, and proof-of-concept deployments
<Button href="/selfhosted/identity-providers/authentik" variant="outline">Setup Authentik</Button>
[Setup Guide →](/selfhosted/identity-providers/embedded-idp)
### Keycloak
### Embedded IdP with Connectors
[Keycloak](https://github.com/keycloak/keycloak) is an open-source Identity and Access Management solution aimed at modern applications and services. It's one of the most popular self-hosted IdP solutions with extensive documentation and community support. Keycloak provides single sign-on, social login, user federation, fine-grained authorization, and supports OpenID Connect, OAuth 2.0, and SAML 2.0 protocols.
Combine the simplicity of embedded IdP with your existing identity providers:
<Button href="/selfhosted/identity-providers/keycloak" variant="outline">Setup Keycloak</Button>
- Keep local user management as a fallback
- Add Google, Microsoft, Okta, or other SSO for convenience
- Configure connectors directly from the Dashboard UI
- Best of both worlds
### PocketID
[About Connectors →](/selfhosted/identity-providers/connectors)
[PocketID](https://pocket-id.org/) is a simplified identity management solution designed for self-hosted environments. It provides authentication and authorization services with a focus on security and effectiveness, making it a lightweight and easy-to-deploy option for organizations seeking a straightforward identity management solution.
### Standalone IdP (Advanced)
<Button href="/selfhosted/identity-providers/pocketid" variant="outline">Setup PocketID</Button>
For organizations with specific requirements or existing IdP investments:
## Managed IdPs
- Full control over identity infrastructure
- Required for SCIM provisioning (Enterprise)
- Complex user lifecycle management needs
- Separate IdP container deployment
Managed Identity Providers are third-party cloud services that handle the infrastructure and maintenance of your identity provider. These are ideal if you don't want to manage an IdP instance yourself.
[Advanced IdP Setup →](/selfhosted/selfhosted-guide#step-3-configure-identity-provider-idp)
### Microsoft Entra ID
---
[Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) (formerly Azure AD) is an enterprise identity service that provides single sign-on and multifactor authentication to your applications. It's a managed service that integrates seamlessly with Microsoft's ecosystem, offering conditional access policies, identity protection, and privileged identity management. Ideal for organizations already using Microsoft services.
## Identity Provider Options
<Button href="/selfhosted/identity-providers/managed/microsoft-entra-id" variant="outline">Setup Microsoft Entra ID</Button>
Each provider page includes both **connector setup** (recommended, for use with embedded IdP) and **standalone setup** (advanced) instructions.
### Okta
### Self-Hosted Providers
[Okta](https://www.okta.com/) is a cloud-based identity and access management service designed for enterprise use. It provides single sign-on, multifactor authentication, user management, and lifecycle management capabilities. Okta offers extensive integration options with thousands of pre-built connectors, adaptive authentication, and comprehensive API access management.
Self-hosted Identity Providers give you full control over authentication and authorization.
<Button href="/selfhosted/identity-providers/managed/okta" variant="outline">Setup Okta</Button>
| 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 |
### Google Workspace
### Cloud/Managed Providers
[Google Workspace](https://workspace.google.com/) (formerly G Suite) provides identity management through Google's cloud infrastructure. It offers single sign-on capabilities, multi-factor authentication, and seamless integration with Google services. It's an excellent choice for organizations already using Google Workspace for their business operations, providing unified identity across Google and third-party applications.
Managed Identity Providers handle infrastructure and maintenance for you.
<Button href="/selfhosted/identity-providers/managed/google-workspace" variant="outline">Setup Google Workspace</Button>
| Provider | Description |
|----------|-------------|
| [**Google**](/selfhosted/identity-providers/google) | Google accounts and Google Workspace authentication |
| [**Microsoft**](/selfhosted/identity-providers/microsoft) | Microsoft personal accounts and Entra ID (Azure AD) for work accounts |
| [**Okta**](/selfhosted/identity-providers/okta) | Enterprise identity and access management with extensive integrations |
| [**Auth0**](/selfhosted/identity-providers/auth0) | Flexible authentication service with customization options |
| [**JumpCloud**](/selfhosted/identity-providers/jumpcloud) | Cloud directory platform with identity and device management |
### JumpCloud
---
[JumpCloud](https://jumpcloud.com/) is a cloud-based directory platform that provides identity, access, and device management in a unified solution. It offers single sign-on, multi-factor authentication, directory services, device management, and network access control. JumpCloud provides a comprehensive approach to managing users, devices, and applications from a single platform.
## User Provisioning
<Button href="/selfhosted/identity-providers/managed/jumpcloud" variant="outline">Setup JumpCloud</Button>
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.
### Keycloak (Managed)
## Migration Guide
[Keycloak](https://www.keycloak.org/) can also be deployed as a managed service through various cloud providers, providing the same open-source features with the convenience of cloud hosting and management. This option offers the flexibility and features of Keycloak without the operational overhead of self-hosting.
If you have an existing NetBird deployment using a standalone IdP (like Zitadel from the previous quickstart), you can continue using it. To migrate to the embedded IdP:
<Button href="/selfhosted/identity-providers/managed/keycloak" variant="outline">Setup Keycloak</Button>
1. Export your user list from your current IdP
2. Deploy the new version with embedded IdP enabled
3. Recreate users through the Dashboard or API
4. (Optional) Add your previous IdP as a connector for SSO
### Auth0
<Note>
User data and network configurations are preserved during migration. Only authentication changes—users may need to re-authenticate after the switch.
</Note>
[Auth0](https://auth0.com/) is a flexible, drop-in solution to add authentication and authorization services to your applications. It's a managed service that's ideal if you don't want to manage an Identity Provider instance on your own. Auth0 offers extensive customization options, developer-friendly APIs, universal login, social identity providers, and advanced security features like anomaly detection and breached password detection.
<Button href="/selfhosted/identity-providers/managed/auth0" variant="outline">Setup Auth0</Button>
[Detailed Migration Guide →](/selfhosted/identity-providers/migration)