diff --git a/public/docs-static/img/selfhosted/identity-providers/add-idp.png b/public/docs-static/img/selfhosted/identity-providers/add-idp.png new file mode 100644 index 00000000..ad78d01d Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/add-idp.png differ diff --git a/public/docs-static/img/selfhosted/identity-providers/idp-list.png b/public/docs-static/img/selfhosted/identity-providers/idp-list.png new file mode 100644 index 00000000..cbd49252 Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/idp-list.png differ diff --git a/public/docs-static/img/selfhosted/identity-providers/idp-login.png b/public/docs-static/img/selfhosted/identity-providers/idp-login.png new file mode 100644 index 00000000..cfe19115 Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/idp-login.png differ diff --git a/public/docs-static/img/selfhosted/identity-providers/idp-main-2.png b/public/docs-static/img/selfhosted/identity-providers/idp-main-2.png new file mode 100644 index 00000000..c9e42e94 Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/idp-main-2.png differ diff --git a/public/docs-static/img/selfhosted/identity-providers/idp-main.png b/public/docs-static/img/selfhosted/identity-providers/idp-main.png new file mode 100644 index 00000000..0ea2d361 Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/idp-main.png differ diff --git a/public/docs-static/img/selfhosted/identity-providers/user-list.png b/public/docs-static/img/selfhosted/identity-providers/user-list.png new file mode 100644 index 00000000..a5ea2d02 Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/user-list.png differ diff --git a/public/docs-static/img/selfhosted/quickstart/create-user.png b/public/docs-static/img/selfhosted/quickstart/create-user.png new file mode 100644 index 00000000..aec1caa6 Binary files /dev/null and b/public/docs-static/img/selfhosted/quickstart/create-user.png differ diff --git a/public/docs-static/img/selfhosted/quickstart/setup.png b/public/docs-static/img/selfhosted/quickstart/setup.png new file mode 100644 index 00000000..875c11da Binary files /dev/null and b/public/docs-static/img/selfhosted/quickstart/setup.png differ diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 51310318..00c0d958 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -279,31 +279,16 @@ export const docsNavigation = [ { title: 'Profiles', href: '/client/profiles' }, ], }, - { - title: 'USE CASES', - links: [ - { title: 'Site-to-Site and Site-to-VPN', href: '/use-cases/setup-site-to-site-access' }, - { title: 'Serverless and NetBird', href: '/use-cases/netbird-on-faas' }, - { title: 'Routing peers and Kubernetes', href: '/use-cases/routing-peers-and-kubernetes' }, - { title: 'NetBird Client on AWS ECS', href: '/use-cases/examples' }, - { title: 'NetBird on Mikrotik Router', href: '/use-cases/client-on-mikrotik-router' }, - { title: 'Distributed AI on Kubernetes', href: '/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm' }, - { title: 'Self-hosted vs. Cloud-hosted NetBird', href: '/selfhosted/self-hosted-vs-cloud-netbird' }, - ], - }, { title: 'SELF-HOST NETBIRD', links: [ - { title: 'Quickstart guide', href: '/selfhosted/selfhosted-quickstart' }, - { title: 'Advanced guide', href: '/selfhosted/selfhosted-guide' }, - { title: 'Management SQLite Store', href: '/selfhosted/sqlite-store' }, - { title: 'Management Postgres Store', href: '/selfhosted/postgres-store' }, - { title: 'Activity Events Postgres Store', href: '/selfhosted/activity-postgres-store' }, + { title: 'Quickstart Guide', href: '/selfhosted/selfhosted-quickstart' }, { - title: 'Supported IdPs', + title: 'Authentication', isOpen: false, links: [ - { title: 'Using IdPs on Self-Hosted', href: '/selfhosted/identity-providers' }, + { title: 'Authentication and IdPs', href: '/selfhosted/identity-providers' }, + { title: 'Local User Management', href: '/selfhosted/identity-providers/local' }, { title: 'Self-hosted IdPs', isOpen: true, @@ -327,10 +312,26 @@ export const docsNavigation = [ }, ] }, + { title: 'Advanced guide', href: '/selfhosted/selfhosted-guide' }, + { title: 'Management SQLite Store', href: '/selfhosted/sqlite-store' }, + { title: 'Management Postgres Store', href: '/selfhosted/postgres-store' }, + { title: 'Activity Events Postgres Store', href: '/selfhosted/activity-postgres-store' }, { title: 'Management geolocation', href: '/selfhosted/geo-support' }, { title: 'Troubleshooting', href: '/selfhosted/troubleshooting' }, ], }, + { + title: 'USE CASES', + links: [ + { title: 'Site-to-Site and Site-to-VPN', href: '/use-cases/setup-site-to-site-access' }, + { title: 'Serverless and NetBird', href: '/use-cases/netbird-on-faas' }, + { title: 'Routing peers and Kubernetes', href: '/use-cases/routing-peers-and-kubernetes' }, + { title: 'NetBird Client on AWS ECS', href: '/use-cases/examples' }, + { title: 'NetBird on Mikrotik Router', href: '/use-cases/client-on-mikrotik-router' }, + { title: 'Distributed AI on Kubernetes', href: '/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm' }, + { title: 'Self-hosted vs. Cloud-hosted NetBird', href: '/selfhosted/self-hosted-vs-cloud-netbird' }, + ], + }, { title: 'GET MORE HELP', links: [ diff --git a/src/components/announcement-banner/AnnouncementBannerProvider.jsx b/src/components/announcement-banner/AnnouncementBannerProvider.jsx index 6b426ef7..94a860cf 100644 --- a/src/components/announcement-banner/AnnouncementBannerProvider.jsx +++ b/src/components/announcement-banner/AnnouncementBannerProvider.jsx @@ -12,11 +12,11 @@ import { useLocalStorage } from '@/hooks/useLocalStorage' const BANNER_ENABLED = true export const announcement = { - tag: '', - text: 'NetBird v0.60 Released - Native SSH Access', - link: '/manage/peers/ssh', - linkText: 'Read Release Documentation', - linkAlt: 'Learn more about the NetBird v0.60 release', + tag: 'New', + text: 'Simplified IdP Integration', + link: '/selfhosted/identity-providers', + linkText: 'Learn More', + linkAlt: 'Learn more about the embedded Identity Provider powered by DEX for self-hosted installations', isExternal: false, closeable: true, } diff --git a/src/pages/selfhosted/identity-providers/authentik.mdx b/src/pages/selfhosted/identity-providers/authentik.mdx index 448f6ae8..34a1eb09 100644 --- a/src/pages/selfhosted/identity-providers/authentik.mdx +++ b/src/pages/selfhosted/identity-providers/authentik.mdx @@ -1,135 +1,194 @@ import {Note} from "@/components/mdx"; -# Authentik with NetBird Self-Hosted +# Authentik -This guide is a part of the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide) and explains how to integrate -**self-hosted** NetBird with [Authentik](https://goauthentik.io). +[Authentik](https://goauthentik.io) 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. + +## Connector Setup (Recommended) + +Add Authentik as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments. + +### Prerequisites + +- NetBird self-hosted with embedded IdP enabled +- Authentik instance with admin access + +### Step 1: Create OAuth2/OpenID Provider in Authentik + +1. Navigate to Authentik admin interface +2. Click **Applications** on the left menu, then click **Providers** +3. Click **Create** to create a new provider +4. Select **OAuth2/OpenID Provider** and click **Next** + +

+ Select provider type +

+ +5. Fill in the form with the following values: + - **Name**: `NetBird` + - **Authentication Flow**: `default-authentication-flow (Welcome to authentik!)` + - **Authorization Flow**: `default-provider-authorization-explicit-consent (Authorize Application)` + - **Client type**: `Confidential` + - **Redirect URIs/Origins**: Leave empty for now (you'll add this after creating the connector in NetBird) + - **Signing Key**: Select any cert present, e.g., `authentik Self-signed Certificate` + +6. Click **Finish** +7. Note the **Client ID** and **Client Secret** + +### Step 2: Create Application in Authentik + +1. Click **Applications** on the left menu, then click **Applications** +2. Click **Create** to create a new application +3. Fill in the form: + - **Name**: `NetBird` + - **Slug**: `netbird` + - **Provider**: Select the `NetBird` provider you created +4. Click **Create** + +

+ Create application +

+ +### Step 3: Add Connector in NetBird + +1. Log in to your NetBird Dashboard +2. Navigate to **Settings** → **Identity Providers** +3. Click **Add Identity Provider** +4. Fill in the fields: + +| Field | Value | +|-------|-------| +| Type | Generic OIDC | +| Name | Authentik (or your preferred display name) | +| Client ID | From Authentik provider | +| Client Secret | From Authentik provider | +| Issuer | `https://authentik.example.com/application/o/netbird/` | + +5. Click **Save** + +### Step 4: Configure Redirect URI + +After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Authentik provider: + +1. Return to Authentik admin → **Providers** → **NetBird** +2. Click **Edit** +3. Under **Redirect URIs/Origins**, add the redirect URL from NetBird +4. Click **Update** + +### Step 5: Test the Connection + +1. Log out of NetBird Dashboard +2. On the login page, you should see an "Authentik" button +3. Click it and authenticate with your Authentik credentials +4. You should be redirected back to NetBird and logged in + +--- + +## Standalone Setup (Advanced) + +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) 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, then you could use a managed alternative like - [Auth0](/selfhosted/identity-providers#auth0). +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). -## Step 1: Create OAuth2/OpenID Provider -In this step, we will create OAuth2/OpenID Provider in Authentik. +### Prerequisites -- Navigate to authentik admin interface -- Click `Applications` on the left menu, then click `Providers` -- Click `Create` to create new provider -- Fill in the form with the following values and click `Next` - - type: `OAuth2/OpenID Provider` +- Authentik instance running with SSL +- Docker and Docker Compose installed for NetBird + +### Step 1: Create OAuth2/OpenID Provider + +Follow steps 1-2 from the connector setup above, but configure the provider as follows: + +- **Client type**: `Public` +- **Redirect URIs/Origins (RegEx)**: + - Regex: `https:///.*` + - Strict: `http://localhost:53000` +- **Advanced protocol settings**: + - Access code validity: `minutes=10` + - Subject mode: `Based on the User's ID`

- high-level-dia + Provider configuration

-- Fill in the form with the following values and click `Finish` - - Name: `Netbird` - - Authentication Flow: `default-authentication-flow (Welcome to authentik!)` - - Authorization Flow: `default-provider-authorization-explicit-consent (Authorize Application)` - - Protocol Settings: - - Client type: `Public` - - Redirect URIs/Origins (RegEx): - - Regex: `https:///.*` - - Strict: `http://localhost:53000` - - Signing Key: Must be selected! Can be any cert present, e.g. `authentik Self-signed Certificate` - - Advanced protocol settings: - - Access code validity: `minutes=10` - - Subject mode: `Based on the User's ID` +Take note of **Client ID** for later use. -Take note of `Client ID`, we will use it later -

- high-level-dia -

+### Step 2: Create Application -## Step 2: Create external applications -In this step, we will create external applications in Authentik. +Follow step 2 from the connector setup to create the NetBird application. -- Navigate to authentik admin interface -- Click `Applications` on the left menu, then click `Applications` -- Click `Create` to create new application -- Fill in the form with the following values and click `Create` - - Name: `Netbird` - - Slug: `netbird` - - Provider: `Netbird` +### Step 3: Create Service Account + +1. Navigate to Authentik admin interface +2. Click **Directory** on the left menu, then click **Users** +3. Click **Create Service Account** +4. Fill in the form: + - **Username**: `Netbird` + - **Create Group**: Disable +5. Click **Create**

- high-level-dia + Create service account

-## Step 3: Create service account -In this step, we will create service account. +6. Note the service account username +7. Create an app password: Go to **Directory** → **Tokens and App passwords** +8. Create a new app password, selecting the NetBird service account as the **User** +9. Save the app password for later use -- Navigate to authentik admin interface -- Click `Directory` on the left menu, then click `Users` -- Click `Create Service Account` to create service account -- Fill in the form with the following values and click `Create` - - Username: `Netbird` - - Create Group: `Disable` - -

- high-level-dia -

+### Step 4: Add Service Account to Admin Group -- Take note of the NetBird service account `username`, we will need it later. -- N.B. The `password` defined when creating the NetBird service account is not required. -Users should instead create an app password for the NetBird service account within `Directory > Tokens and App passwords` in authentik's `Admin interface. -Be sure to select the NetBird Service account object as the `User` when creating the app password. -Take note of the app password as we will need it later. +1. Click **Directory** on the left menu, then click **Groups** +2. Click **authentik Admins** from the list and select **Users** tab +3. Click **Add existing user** and click **+** button +4. Select **Netbird** and click **Add** +5. Disable **Hide service-accounts** and verify the user is added

- high-level-dia + Add user to group

-## Step 4: Add service account to admin group -In this step, we will add `Netbird` service account to `authentik Admins` group. +### Step 5: Create Device Code Flow -- Navigate to authentik admin interface -- Click `Directory` on the left menu, then click `Groups` -- Click `authentik Admins` from list of groups and select `Users` tab at the top -- Click `Add existing user` and click `+` button to add user -- Select `Netbird` and click `Add` -- Disable `Hide service-accounts` and verify if user `Netbird` is added to the group +1. Click **Flows and Stages** on the left menu, then click **Flows** → **Create** +2. Fill in the form: + - **Name**: `default-device-code-flow` + - **Title**: `Device Code Flow` + - **Designation**: `Stage Configuration` + - **Authentication**: `Require authentication` +3. Click **Create**

- high-level-dia + Create device flow

-#### Step 5: Create a authentication flow for device token authentication - -- Navigate to authentik admin interface -- Click `Flows and Stages` on the left menu, then click `Flows` then `Create` -- Fill in the form with the following values and click `Create` - - Name: `default-device-code-flow` - - Title: `Device Code Flow` - - Designation: `Stage Configuration` - - Authentication: `Require authentication` +4. Click **System** on the left menu, then click **Brands** +5. Click edit on **authentik-default** +6. Under **Default flows**, set **Device code flow** to `default-device-code-flow` +7. Click **Update**

- high-level-dia + Configure brand device flow

-- Navigate to authentik admin interface -- Click `System` on the left menu, then click `Brands` -- Click on the edit button of domain `authentik-default` -- Under Default flows set Device code flow to `default-device-code-flow` -- Click `Update` +### Step 6: Configure NetBird -

- high-level-dia -

- -Your authority OIDC configuration will be available under: +Your authority OIDC configuration will be available at: ```bash -https://< YOUR_AUTHENTIK_HOST_AND_PORT >/application/o/netbird/.well-known/openid-configuration +https:///application/o/netbird/.well-known/openid-configuration ``` Double-check if the endpoint returns a JSON response by calling it from your browser. -- Set properties in the `setup.env` file: +Set properties in the `setup.env` file: + ```shell NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///application/o/netbird/.well-known/openid-configuration" NETBIRD_USE_AUTH0=false @@ -146,10 +205,37 @@ NETBIRD_IDP_MGMT_CLIENT_ID="" NETBIRD_IDP_MGMT_EXTRA_USERNAME="Netbird" NETBIRD_IDP_MGMT_EXTRA_PASSWORD="" -# needs disabling due to issue with IdP. Learn more [here](https://github.com/netbirdio/netbird/issues/3654) +# Needs disabling due to issue with IdP. Learn more: https://github.com/netbirdio/netbird/issues/3654 NETBIRD_AUTH_PKCE_DISABLE_PROMPT_LOGIN=true - ``` -## Step 6: Continue with the NetBird Self-hosting Guide -You've configured all required resources in Authentik. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). \ No newline at end of file +### Step 7: Continue with NetBird Setup + +You've configured all required resources in Authentik. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). + +--- + +## Troubleshooting + +### "Invalid redirect URI" error + +- Ensure the redirect URI exactly matches what NetBird provides +- For connector setup: Copy the exact URL from the success modal +- For standalone: Use regex pattern `https:///.*` + +### Authentication fails silently + +- Verify a signing key is selected in the provider configuration +- Check that the application is linked to the correct provider + +### Service account authentication fails + +- Ensure you're using the app password, not the account password +- Verify the service account is in the authentik Admins group + +--- + +## Related Resources + +- [Authentik Documentation](https://goauthentik.io/docs/) +- [Embedded IdP Overview](/selfhosted/identity-providers/local) \ 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 c383f83b..d12cb8d5 100644 --- a/src/pages/selfhosted/identity-providers/index.mdx +++ b/src/pages/selfhosted/identity-providers/index.mdx @@ -1,90 +1,200 @@ -import { Note, Button } from '@/components/mdx' +import {Note} from "../../../components/mdx"; -# Supported Identity Providers (IdPs) +# Authentication and 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. +

+ Identity Providers List +

-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. +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 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**](#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` | 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 | - 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. + Any identity provider that supports OpenID Connect can be integrated with NetBird. If your provider isn't listed above, + use the generic OIDC configuration. -## Our Approach + ### Adding an Identity Provider -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. +#### Via Dashboard -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. +

+ Identity Providers List +

-## Self-hosted IdPs +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** -Self-hosted Identity Providers give you full control over authentication and authorization of your NetBird network. You manage and maintain the IdP infrastructure yourself. + + 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. + -### Zitadel +

+ Identity Providers List +

-[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. +#### 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" + }' +``` -### Authentik +For instance setup endpoints, see [Accounts API](/api/resources/accounts). For user creation with embedded IdP, see [Users API](/api/resources/users). -[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. +### Managing Identity Providers via API - +```bash +# List configured identity providers +curl "https://netbird.example.com/api/identity-providers" \ + -H "Authorization: Bearer ${TOKEN}" -### Keycloak +# 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" + }' -[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. +# Delete an identity providers +curl -X DELETE "https://netbird.example.com/api/identity-providers/{id}" \ + -H "Authorization: Bearer ${TOKEN}" +``` - +### How It Works -### PocketID +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 -[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. +Users who authenticate via an external identity provider appear in your Users list with a badge showing their identity provider. - +

+ Identity Providers List +

-## Managed IdPs +### Multiple Identity Providers -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. +You can configure **multiple identity providers simultaneously**: -### Microsoft Entra ID +- 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 -[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. +This allows you to support different authentication methods for different user groups. - +

+ Multiple Identity Providers +

-### Okta +### Best Practices -[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. +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 -### Google Workspace +#### Provider not appearing on login page -[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. +- 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 -### JumpCloud +- Copy the exact Redirect URL from NetBird after creating the provider +- Ensure no trailing slashes or typos +- Some providers are case-sensitive -[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. +#### 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. -### Keycloak (Managed) +#### External connector not working -[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. +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. -### Auth0 +## User Provisioning (SCIM) -[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. +In addition to OIDC-based authentication, 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. - \ No newline at end of file +## 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. + + + 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. + \ No newline at end of file diff --git a/src/pages/selfhosted/identity-providers/keycloak.mdx b/src/pages/selfhosted/identity-providers/keycloak.mdx index c1474859..5fa4576e 100644 --- a/src/pages/selfhosted/identity-providers/keycloak.mdx +++ b/src/pages/selfhosted/identity-providers/keycloak.mdx @@ -1,265 +1,323 @@ import {Note} from "@/components/mdx"; -# Keycloak with NetBird Self-Hosted +# Keycloak -This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate -**self-hosted** NetBird with [Keycloak](https://www.keycloak.org/). +[Keycloak](https://www.keycloak.org/) is an open-source Identity and Access Management solution maintained by Red Hat. It provides single sign-on, social login, user federation, fine-grained authorization, and supports OpenID Connect, OAuth 2.0, and SAML 2.0 protocols. -Keycloak is an open source software product to allow single sign-on with Identity and Access Management aimed at modern applications and services. +## Connector Setup (Recommended) + +Add Keycloak as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments. + +### Prerequisites + +- NetBird self-hosted with embedded IdP enabled +- Keycloak instance running with SSL + +### Step 1: Create Client in Keycloak + +1. Open the Keycloak Admin Console +2. Select your realm (or create a new one, e.g., `netbird`) +3. Click **Clients** → **Create client** +4. Fill in the form: + - **Client type**: `OpenID Connect` + - **Client ID**: `netbird` +5. Click **Next** +6. On Capability config: + - Enable **Client authentication** +7. Click **Next** +8. On Login settings: + - Leave redirect URIs empty for now +9. Click **Save** +10. Go to the **Credentials** tab and copy the **Client secret** + +### Step 2: Add Connector in NetBird + +1. Log in to your NetBird Dashboard +2. Navigate to **Settings** → **Identity Providers** +3. Click **Add Identity Provider** +4. Fill in the fields: + +| Field | Value | +|-------|-------| +| Type | Generic OIDC | +| Name | Keycloak (or your preferred display name) | +| Client ID | `netbird` (from Step 1) | +| Client Secret | From Keycloak Credentials tab | +| Issuer | `https://keycloak.example.com/realms/your-realm` | + +5. Click **Save** + +### Step 3: Configure Redirect URI + +After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Keycloak client: + +1. Return to Keycloak Admin Console +2. Go to your client → **Settings** tab +3. Under **Valid redirect URIs**, add the redirect URL from NetBird +4. Click **Save** + +### Step 4: Test the Connection + +1. Log out of NetBird Dashboard +2. On the login page, you should see a "Keycloak" button +3. Click it and authenticate with your Keycloak credentials +4. You should be redirected back to NetBird and logged in - If you prefer not to self-host an Identity and Access Management solution, then you could use a managed alternative like - [Auth0](/selfhosted/identity-providers#auth0). +Users who authenticate via Keycloak will appear in your NetBird Users list with a Keycloak badge next to their name. -The following guide is an adapted version of the original -[Keycloak on Docker](https://www.keycloak.org/getting-started/getting-started-docker) guide from the official website. +--- -## Expected Result +## Standalone Setup (Advanced) -After completing this guide, you can log in to your self-hosted NetBird Dashboard and add your machines -to your network using the [Interactive SSO Login feature](/get-started/install#running-net-bird-with-sso-login) -over Keycloak. +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) 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). + + +### Expected Result + +After completing this guide, you can log in to your self-hosted NetBird Dashboard and add machines to your network using the [Interactive SSO Login feature](/get-started/install#running-net-bird-with-sso-login) over Keycloak.

- high-level-dia + Keycloak auth flow

-## Step 1: Check your Keycloak Instance +### Prerequisites -For this guide, you need a fully configured Keycloak instance running with SSL. +- Keycloak instance running with SSL +- Docker and Docker Compose for NetBird -We assume that your Keycloak instance is available at **`https://YOUR-KEYCLOAK-HOST-AND_PORT`**. -Feel free to change the port if you have configured Keycloak with a different one. +### Step 1: Check Your Keycloak Instance -Most of the OIDC software requires SSL for production use. -We encourage you to comply with this requirement to make the world more secure 😊. +Ensure your Keycloak instance is available at `https://YOUR-KEYCLOAK-HOST-AND-PORT` with SSL enabled. -## Step 2: Create a realm +### Step 2: Create a Realm -To create a realm you need to: - -- Open the Keycloak Admin Console -- Hover the mouse over the dropdown in the top-left corner where it says `Master`, then click on `Create Realm` -- Fill in the form with the following values: -- Realm name: `netbird` -- Click `Create` +1. Open the Keycloak Admin Console +2. Hover over the dropdown in the top-left corner where it says `Master` +3. Click **Create Realm** +4. Fill in: + - **Realm name**: `netbird` +5. Click **Create**

- high-level-dia + Create realm

+### Step 3: Create a User -## Step 3: Create a user - -In this step we will create a NetBird administrator user. - -- Open the Keycloak Admin Console -- Make sure, that the selected realm is `Netbird` -- Click `Users` (left-hand menu) -- Click `Create new user` -- Fill in the form with the following values: -- Username: `netbird` -- Click `Create` +1. Make sure the selected realm is `netbird` +2. Click **Users** (left-hand menu) +3. Click **Create new user** +4. Fill in: + - **Username**: `netbird` +5. Click **Create**

- high-level-dia + Create user

-The user will need an initial password set to be able to log in. To do this: -- Click `Credentials` tab -- Click `Set password` button -- Fill in the password form with a password -- Set the `Temporary` field to `Off` to prevent having to update password on first login -- Click `Save` +6. Click **Credentials** tab +7. Click **Set password** +8. Fill in the password and set **Temporary** to `Off` +9. Click **Save**

- high-level-dia + Set password

-## Step 4: Create a NetBird client +### Step 4: Create NetBird Client -In this step we will create NetBird application client and register with the Keycloak instance. - -- Open the Keycloak Admin Console -- Make sure, that the selected realm is `Netbird` -- Click `Clients` -- Click `Create client` button -- Fill in the form with the following values and click Next: -- Client Type: `OpenID Connect` -- Client ID: `netbird-client` -- Your newly client `netbird-client` will be used later to set `NETBIRD_AUTH_CLIENT_ID` in the `setup.env` +1. Click **Clients** → **Create client** +2. Fill in: + - **Client Type**: `OpenID Connect` + - **Client ID**: `netbird-client` +3. Click **Next**

- high-level-dia + Create client

- -- Check the checkboxes as on the screenshot below and click Save +4. Enable the authentication options as shown:

- high-level-dia + Enable auth

-## Step 5: Adjust NetBird client access settings +5. Click **Save** -In this step we will configure NetBird application client access with the NetBird URLs. +### Step 5: Configure Client Access Settings -- Open the Keycloak Admin Console -- Make sure, that the selected realm is `Netbird` -- Click `Clients` -- Choose `netbird-client` from the list -- Go to `Access Settings` section -- Fill in the fields with the following values: -- Root URL: `https://YOUR DOMAIN/` (this is the NetBird Dashboard root URL) -- Valid redirect URIs: `https://YOUR DOMAIN/*` and `http://localhost:53000` -- Valid post logout redirect URIs: `https://YOUR DOMAIN/*` -- Web origins: `+` -- Click `Save` +1. Go to **Clients** → **netbird-client** +2. In **Access Settings**, fill in: + - **Root URL**: `https://YOUR_DOMAIN/` + - **Valid redirect URIs**: `https://YOUR_DOMAIN/*` and `http://localhost:53000` + - **Valid post logout redirect URIs**: `https://YOUR_DOMAIN/*` + - **Web origins**: `+` +3. Click **Save**

- high-level-dia + Access settings

-## Step 6: Create a NetBird client scope +### Step 6: Create Client Scope -In this step, we will create and configure the NetBird client audience for Keycloak to add it to the generated JWT tokens. - -- Open the Keycloak Admin Console -- Make sure, that the selected realm is `Netbird` -- Click `Client scopes` (left-hand menu) -- Click `Create client scope` button -- Fill in the form with the following values: -- Name: `api` -- Type: `Default` -- Protocol: `OpenID Connect` -- Click `Save` +1. Click **Client scopes** (left-hand menu) +2. Click **Create client scope** +3. Fill in: + - **Name**: `api` + - **Type**: `Default` + - **Protocol**: `OpenID Connect` +4. Click **Save**

- high-level-dia + Create client scope

-- While in the newly created Client Scope, switch to the `Mappers` tab -- Click `Configure a new mapper` -- Choose the `Audience` mapping +5. Switch to the **Mappers** tab +6. Click **Configure a new mapper** +7. Choose **Audience** mapping

- high-level-dia + Configure audience mapper

-- Fill in the form with the following values: -- Name: `Audience for NetBird Management API` -- Included Client Audience: `netbird-client` -- Add to access token: `On` -- Click `Save` +8. Fill in: + - **Name**: `Audience for NetBird Management API` + - **Included Client Audience**: `netbird-client` + - **Add to access token**: `On` +9. Click **Save**

- high-level-dia + Audience mapper config

-## Step 7: Add client scope to NetBird client +### Step 7: Add Client Scope to NetBird Client -- Open the Keycloak Admin Console -- Make sure, that the selected realm is `Netbird` -- Click `Clients` -- Choose `netbird-client` from the list -- Switch to `Client scopes` tab -- Click `Add client scope` button -- Choose `api` -- Click `Add` choosing `Default` -- The value `netbird-client` will be used as audience +1. Go to **Clients** → **netbird-client** +2. Switch to **Client scopes** tab +3. Click **Add client scope** +4. Choose `api` +5. Click **Add** choosing `Default`

- high-level-dia + Add client scope

-## Step 8: Create a NetBird-Backend client +### Step 8: Create NetBird-Backend Client -In this step we will create NetBird backend client and register with the Keycloak instance. - -- Open the Keycloak Admin Console -- Make sure, that the selected realm is `Netbird` -- Click `Clients` -- Click `Create client` button -- Fill in the form with the following values and click Next: -- Client Type: `OpenID Connect` -- Client ID: `netbird-backend` -- Your newly client `netbird-backend` will be used later to set `NETBIRD_IDP_MGMT_CLIENT_ID` in the `setup.env` +1. Click **Clients** → **Create client** +2. Fill in: + - **Client Type**: `OpenID Connect` + - **Client ID**: `netbird-backend` +3. Click **Next**

- high-level-dia + Create backend client

-- Check the checkboxes as on the screenshot below and click Save +4. Enable authentication as shown:

- high-level-dia + Backend client auth

-The client will need secret to authenticate. To do this: -- Click `Credentials` tab -- Copy `client secret` will be used later to set `NETBIRD_IDP_MGMT_CLIENT_SECRET` in the `setup.env` +5. Click **Save** +6. Go to **Credentials** tab +7. Copy the **Client secret**

- high-level-dia + Backend client credentials

-## Step 9: Add view-users role to netbird-backend +### Step 9: Add View-Users Role -- Open the Keycloak Admin Console -- Make sure, that the selected realm is `Netbird` -- Click `Clients` -- Choose `netbird-backend` from the list -- Switch to `Service accounts roles` tab -- Click `Assign roles` button -- Select `Filter by clients` and search for `view-users` +1. Go to **Clients** → **netbird-backend** +2. Switch to **Service accounts roles** tab +3. Click **Assign roles** +4. Select **Filter by clients** and search for `view-users`

- high-level-dia + Service account role

-- Check the role checkbox and click assign +5. Check the role checkbox and click **Assign**

- high-level-dia + Add role

-Optional - -NetBird offers the ability to automatically delete a user from the Keycloak side when the user is deleted from the associated account. - To enable this functionality, simply include the `--user-delete-from-idp` flag in the management startup command within your Docker Compose configuration. If you choose to enable this feature, - please ensure that you assign the `manage-users` role to the `netbird-backend` following the steps outlined above. +**Optional**: To enable automatic user deletion from Keycloak when deleted from NetBird, add the `--user-delete-from-idp` flag to the management startup command and assign the `manage-users` role instead. -Your authority OIDC configuration will be available under: +### Step 10: Configure NetBird + +Your authority OIDC configuration will be available at: + ```bash https:///realms/netbird/.well-known/openid-configuration ``` + - Double-check if the endpoint returns a JSON response by calling it from your browser. +Double-check if the endpoint returns a JSON response by calling it from your browser. -- Set properties in the `setup.env` file: -```shell -NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=`https:///realms/netbird/.well-known/openid-configuration`. -NETBIRD_USE_AUTH0=false -NETBIRD_AUTH_CLIENT_ID=`netbird-client` -NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api" -NETBIRD_AUTH_AUDIENCE=`netbird-client` +Set properties in the `setup.env` file: -NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=`netbird-client` -NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE=`netbird-client` +```shell +NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///realms/netbird/.well-known/openid-configuration" +NETBIRD_USE_AUTH0=false +NETBIRD_AUTH_CLIENT_ID="netbird-client" +NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api" +NETBIRD_AUTH_AUDIENCE="netbird-client" + +NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="netbird-client" +NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="netbird-client" NETBIRD_MGMT_IDP="keycloak" NETBIRD_IDP_MGMT_CLIENT_ID="netbird-backend" NETBIRD_IDP_MGMT_CLIENT_SECRET="" NETBIRD_IDP_MGMT_EXTRA_ADMIN_ENDPOINT="https:///admin/realms/netbird" - ``` + - Make sure that your Keycloak instance use HTTPS. Otherwise, the setup won't work. +Make sure your Keycloak instance uses HTTPS. Otherwise, the setup won't work. -#### Step 10: Continue with the NetBird Self-hosting Guide -You've configured all required resources in Keycloak. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). \ No newline at end of file +### Step 11: Continue with NetBird Setup + +You've configured all required resources in Keycloak. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). + +--- + +## Troubleshooting + +### "Invalid redirect URI" error + +- Ensure the redirect URI matches exactly what's configured +- For connector: Use the exact URL from the NetBird success modal +- For standalone: Include both `https://YOUR_DOMAIN/*` and `http://localhost:53000` + +### "Invalid token" errors + +- Verify the issuer URL includes `/realms/your-realm` +- Ensure the client ID matches in both Keycloak and NetBird +- Check clock synchronization between servers + +### Users not appearing in NetBird + +- For connector: Users appear after their first successful login +- For standalone: Verify the backend client has `view-users` role + +--- + +## Related Resources + +- [Keycloak Documentation](https://www.keycloak.org/documentation) +- [Embedded IdP Overview](/selfhosted/identity-providers/local) \ 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..96a7c45e --- /dev/null +++ b/src/pages/selfhosted/identity-providers/local.mdx @@ -0,0 +1,292 @@ +# 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) + +## 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 + +## Configuration + +### Enabling Embedded IdP + +The embedded IdP is enabled by default when using the new [`getting-started.sh`](/selfhosted/selfhosted-quickstart) 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 + +## 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 + +## 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 23a65082..f2f06ea2 100644 --- a/src/pages/selfhosted/identity-providers/managed/auth0.mdx +++ b/src/pages/selfhosted/identity-providers/managed/auth0.mdx @@ -1,22 +1,85 @@ import {Note} from "@/components/mdx"; -# Auth0 with NetBird Self-Hosted +# Auth0 -This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate **self-hosted** NetBird with [Auth0](https://auth0.com/). +[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 handles identity infrastructure so you don't have to. -Auth0 is a flexible, drop-in solution to add authentication and authorization services to your applications. -It is a 3rd party managed service and can't be self-hosted. Auth0 is the right choice if you don't want to manage an Identity Provider (IDP) -instance on your own. +## Connector Setup (Recommended) + +Add Auth0 as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments. + +### Prerequisites + +- NetBird self-hosted with embedded IdP enabled +- Auth0 account (sign up at https://auth0.com/) + +### Step 1: Create Application in Auth0 + +1. Log in to your Auth0 dashboard at https://manage.auth0.com/ +2. Go to **Applications** → **Applications** +3. Click **Create Application** +4. Fill in: + - **Name**: `NetBird` + - **Application type**: `Regular Web Application` +5. Click **Create** +6. Go to **Settings** tab +7. Note the **Client ID** and **Client Secret** +8. Note the **Domain** (e.g., `your-tenant.auth0.com`) + +### Step 2: Add Connector in NetBird + +1. Log in to your NetBird Dashboard +2. Navigate to **Settings** → **Identity Providers** +3. Click **Add Identity Provider** +4. Fill in the fields: + +| Field | Value | +|-------|-------| +| Type | Generic OIDC | +| Name | Auth0 (or your preferred display name) | +| Client ID | From Auth0 application | +| Client Secret | From Auth0 application | +| Issuer | `https://your-tenant.auth0.com` | + +5. Click **Save** + +### Step 3: Configure Redirect URI + +After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Auth0 application: + +1. Return to Auth0 Dashboard → **Applications** → **NetBird** +2. Go to **Settings** tab +3. Under **Allowed Callback URLs**, add the redirect URL from NetBird +4. Click **Save Changes** + +### Step 4: Test the Connection + +1. Log out of NetBird Dashboard +2. On the login page, you should see an "Auth0" button +3. Click it and authenticate +4. You should be redirected back to NetBird and logged in + +--- + +## Standalone Setup (Advanced) + +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) 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 and authorization of your NetBird network, there are good - self-hosted alternatives to the managed Auth0 service like [Keycloak](/selfhosted/identity-providers#keycloak). +If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak). -## Step 1: Create Auth0 account -To create an Auth0 account, sign up at [https://auth0.com](https://auth0.com/). +### Prerequisites + +- Auth0 account (sign up at https://auth0.com/) +- Docker and Docker Compose for NetBird + +### Configuration Properties + +You will configure these properties in `setup.env`: -There are multiple properties of the **`setup.env`** file that we will configure in this guide: - `NETBIRD_AUTH_CLIENT_ID` - `NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT` - `NETBIRD_USE_AUTH0` @@ -27,115 +90,113 @@ There are multiple properties of the **`setup.env`** file that we will configure - `NETBIRD_IDP_MGMT_CLIENT_SECRET` - `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE` -## Step 2: Create and configure Auth0 application +### Step 1: Create Dashboard Application -This Auth0 application will be used to authorize access to NetBird Dashboard (Web UI). +This application authorizes access to NetBird Dashboard. + +1. Follow the [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0) up to "Install the Auth0 React SDK" +2. Set **Allowed Callback URLs**: `https://YOUR_DOMAIN` and `http://localhost:53000` +3. Set **Allowed Logout URLs**, **Allowed Web Origins**, **Allowed Origins (CORS)**: `https://YOUR_DOMAIN` and `http://localhost` -- Follow the steps in the [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0) -up until "Install the Auth0 React SDK". -- Use **`https://YOUR DOMAIN`** and **`http://localhost:53000`** as: `Allowed Callback URLs`, -- Use **`https://YOUR DOMAIN`** and **`http://localhost`** as: `Allowed Logout URLs`, `Allowed Web Origins`, `Allowed Origins (CORS)` - Make sure that **`Token Endpoint Authentication Method`** is set to **`None`**. +Ensure **Token Endpoint Authentication Method** is set to **None**. -- Use **`Client ID`** to set ```NETBIRD_AUTH_CLIENT_ID``` property in the `setup.env` file. -- Use **`Domain`** to configure ```NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT``` property in the `setup.env` file like so: +4. Use **Client ID** for `NETBIRD_AUTH_CLIENT_ID` +5. Use **Domain** to configure `NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT`: ```bash - https:///.well-known/openid-configuration +https:///.well-known/openid-configuration ``` + - Double-check if the endpoint returns a JSON response by calling it from your browser. +Double-check if the endpoint returns a JSON response by calling it from your browser. -#### Step 3: Create and configure Auth0 API +### Step 2: Create API -This Auth0 API will be used to access NetBird Management Service API. +This API is used to access NetBird Management Service. -- Follow the steps in the [Auth0 Create An API](https://auth0.com/docs/quickstart/backend/golang#create-an-api). -- Use API **`Identifier`** to set ```NETBIRD_AUTH_AUDIENCE``` property in the `setup.env` file. -- Set ```NETBIRD_USE_AUTH0``` to `true`in the `setup.env` file. +1. Follow the [Auth0 Create An API](https://auth0.com/docs/quickstart/backend/golang#create-an-api) guide +2. Use the API **Identifier** for `NETBIRD_AUTH_AUDIENCE` +3. Set `NETBIRD_USE_AUTH0=true` -## Step 4: Enable Interactive SSO Login (Optional) +### Step 3: Enable Interactive SSO Login (Optional) -The [Interactive SSO Login feature](/get-started/install#running-net-bird-with-sso-login) allows for machine -authorization with your Identity Provider. This feature can be used as an alternative to [setup keys](/manage/peers/register-machines-using-setup-keys) -and is optional. +This enables machine authorization via your Identity Provider as an alternative to [setup keys](/manage/peers/register-machines-using-setup-keys). -You can enable it by following these steps: -- Log in to your Auth0 account https://manage.auth0.com/ -- Go to `Applications` (left-hand menu) -- Click `Create Application` button (top right) -- Fill in the form with the following values: - - Name: `Interactive Login` - - Application type: `Native` -- Click `Create` +1. Go to **Applications** +2. Click **Create Application** +3. Fill in: + - **Name**: `Interactive Login` + - **Application type**: `Native` +4. Click **Create**

- high-level-dia + Create interactive login app

-- Click `Settings` tab -- Copy **`Client ID`** to `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID` in the `setup.env` file +5. Click **Settings** tab +6. Copy **Client ID** to `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID`

- high-level-dia + Interactive login settings

-- Scroll down to the `Advanced Settings` section -- Enable **`Device Code`** -- Click `Save Changes` +7. Scroll to **Advanced Settings** +8. Enable **Device Code** +9. Click **Save Changes**

- high-level-dia + Grant types

-## Step 5: Create and configuire Machine to Machine application. -This application will be used to authorize access to Auth0 Management API. +### Step 4: Create Machine to Machine Application -- Log in to your Auth0 account https://manage.auth0.com/ -- Go to `Applications` (left-hand menu) -- Click `Create Application` button (top right) -- Fill in the form with the following values: - - Name: `Netbird API` - - Application type: `Machine to Machine Applications` -- Click `Create` +This application authorizes access to Auth0 Management API. + +1. Go to **Applications** +2. Click **Create Application** +3. Fill in: + - **Name**: `Netbird API` + - **Application type**: `Machine to Machine Applications` +4. Click **Create**

- high-level-dia + Create machine app

-- Fill the form with the following values: - - API: `Auth0 Management API` - - Permissions: `read:users`, `update:users`, `create:users`, `read:users_app_metadata`, `update:users_app_metadata`, `create:users_app_metadata` - - Click `Authorize` +5. Configure: + - **API**: `Auth0 Management API` + - **Permissions**: `read:users`, `update:users`, `create:users`, `read:users_app_metadata`, `update:users_app_metadata`, `create:users_app_metadata` +6. Click **Authorize**

- high-level-dia + Machine authorization

-Optional - -NetBird offers the ability to automatically delete a user from the Auth0 side when the user is deleted from the associated account. -To enable this functionality, include the `--user-delete-from-idp` flag in the management startup command within your Docker Compose configuration. If you choose to enable this feature, please ensure that you assign the `delete:users` permission following the steps outlined above. +**Optional**: To enable automatic user deletion from Auth0 when deleted from NetBird, add the `--user-delete-from-idp` flag to the management startup command and assign the `delete:users` permission. -- Click `Settings` tab -- Copy **`Client ID`** to `NETBIRD_IDP_MGMT_CLIENT_ID` in the `setup.env` file -- Copy **`Client SECRET`** to `NETBIRD_IDP_MGMT_CLIENT_SECRET` in the `setup.env` file -- Copy **`DOMAIN`** to `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE` in the `setup.env` file +7. Click **Settings** tab +8. Copy values: + - **Client ID** → `NETBIRD_IDP_MGMT_CLIENT_ID` + - **Client Secret** → `NETBIRD_IDP_MGMT_CLIENT_SECRET` + - **Domain** → `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE` (format: `https:///api/v2/`)

- high-level-dia + Machine settings

-- Set properties in the `setup.env` file: +### Step 5: Configure NetBird + +Set properties in the `setup.env` file: + ```shell NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///.well-known/openid-configuration" NETBIRD_USE_AUTH0=true -NETBIRD_AUTH_CLIENT_ID="" +NETBIRD_AUTH_CLIENT_ID="" NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api email_verified" NETBIRD_AUTH_AUDIENCE="" NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="" @@ -146,6 +207,39 @@ NETBIRD_IDP_MGMT_CLIENT_SECRET="" NETBIRD_IDP_MGMT_EXTRA_AUDIENCE="https:///api/v2/" ``` +### Step 6: Continue with NetBird Setup -## Step 6: Continue with the NetBird Self-hosting Guide -You've configured all required resources in Auth0. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). \ No newline at end of file +You've configured all required resources in Auth0. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). + +--- + +## Troubleshooting + +### "Invalid redirect URI" error + +- Ensure all callback URLs are configured in Auth0 +- Check for trailing slashes +- Verify URLs match exactly + +### "Unauthorized" errors for Management API + +- Verify the Machine to Machine application has correct permissions +- Check that `NETBIRD_IDP_MGMT_EXTRA_AUDIENCE` includes `/api/v2/` + +### Device authorization not working + +- Ensure Device Code grant is enabled in Advanced Settings +- Verify the native application Client ID is used + +### Token validation errors + +- Verify `NETBIRD_USE_AUTH0=true` is set +- Check the audience matches the API identifier + +--- + +## Related Resources + +- [Auth0 Documentation](https://auth0.com/docs/) +- [Auth0 Dashboard](https://manage.auth0.com/) +- [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 b6da5959..09c9b810 100644 --- a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx +++ b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx @@ -1,127 +1,239 @@ import {Note} from "@/components/mdx"; -# Google Workspace with NetBird Self-Hosted +# Google Workspace -This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate -**self-hosted** NetBird with [Google Workspace](https://workspace.google.com/). +Use Google accounts for authentication with NetBird. This supports both personal Google accounts and Google Workspace (formerly G Suite) organizations. + +## Connector Setup (Recommended) + +Add Google as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments. + +### Prerequisites + +- NetBird self-hosted with embedded IdP enabled +- Access to [Google Cloud Console](https://console.cloud.google.com/) + +### Step 1: Create OAuth Credentials + +1. Go to [Google Cloud Console](https://console.cloud.google.com/) +2. Select or create a project +3. Navigate to **APIs & Services** → **Credentials** +4. Click **Create Credentials** → **OAuth client ID** +5. If prompted, configure the OAuth consent screen first: + - Choose **Internal** (for Workspace) or **External** (for any Google account) + - Fill in required fields (app name, support email) + - Add scopes: `email`, `profile`, `openid` + - Save and continue +6. Back in Credentials, create the OAuth client: + - **Application type**: `Web application` + - **Name**: `NetBird` + - Leave redirect URIs empty for now +7. Click **Create** +8. Note the **Client ID** and **Client Secret** + +### Step 2: Add Connector in NetBird + +1. Log in to your NetBird Dashboard +2. Navigate to **Settings** → **Identity Providers** +3. Click **Add Identity Provider** +4. Fill in the fields: + +| Field | Value | +|-------|-------| +| Type | Google | +| Name | Google (or your preferred display name) | +| Client ID | From Google Cloud Console | +| Client Secret | From Google Cloud Console | -Beginning with NetBird version v0.23.6 and onwards, the Google Workspace IdP manager no longer requires the creation of a custom admin role called `User and Schema Management`. -Instead, we are transitioning towards a more tailored role explicitly designed for managing read-only user information. -Consequently, you have the option to remove the previously established custom admin role and refer to the documentation to configure the admin role scope for read-only access correctly. +Google connectors don't require an Issuer field—it's determined automatically. -Before you start creating and configuring an Google Workspace application, ensure that you have the following: -- An Google Workspace account: To create an Google Work application, you must have an Google Workspace. If you don't have one, sign up at https://workspace.google.com/business/signup/welcome. -- User account with admin permissions: You must have an Google Workspace user account with the admin permissions to create and manage Google Workspace applications. If you don't have the required permissions, ask your workspace administrator to grant them to you. -- Create new `Netbird` project in Google cloud console https://console.cloud.google.com. -- Enable `Admin SDK API` for `Netbird` project at https://console.cloud.google.com/apis/library/admin.googleapis.com. +5. Click **Save** -## Step 1: Configure OAuth consent screen -- Navigate to [OAuth consent](https://console.cloud.google.com/apis/credentials/consent) page -- Select `Internal` User Type and click create -

- high-level-dia -

+### Step 3: Configure Redirect URI -- Fill in the form with the following values and click `SAVE AND CONTINUE` - - App name: `Netbird` - - User support email: `` - - Authorized domain: `` - - Developer contact information: `` -- Click `ADD OR REMOVE SCOPES` -- Select `/auth/userinfo.email`, `/auth/userinfo.profile` and `openid` scopes and then click `UPDATE` -

- high-level-dia -

-- Click `SAVE AND CONTINUE` -- Verify the summary of the OAuth consent screen to ensure that everything is properly configured, and then click `BACK TO DASHBOARD` -

- high-level-dia -

+After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Google OAuth client: -## Step 2: Create OAuth 2.0 credentials -- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page -- Click `CREATE CREDENTIALS` at the top and select `OAuth client ID` -- Fill in the form with the following values and click `CREATE` - - Application type: `Web application` - - Name: `netbird` - - Authorized JavaScript origins: `https://` and `http://localhost` - - Authorized redirect URIs: `https:///auth`, `https:///silent-auth` and `http://localhost:53000` -

- high-level-dia -

-- Take note of `Client ID` and `Client Secret` and click `OK` -

- high-level-dia -

+1. Return to Google Cloud Console → **Credentials** +2. Click on your OAuth client +3. Under **Authorized redirect URIs**, click **Add URI** +4. Paste the redirect URL from NetBird +5. Click **Save** -## Step 3: Create service account -- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page -- Click `CREATE CREDENTIALS` at the top and select `Service account` -- Fill in the form with the following values and click `CREATE` - - Service account name: `netbird` - - Service account ID: `netbird` -- Take note of service account email address, we will use it later -- Click `DONE` -

- high-level-dia -

+### Step 4: Test the Connection -## Step 4: Create service account keys -- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page -- Under `Service Accounts` click the `netbird` to edit the service account -

- high-level-dia -

-- Click the `Keys` tab -- Click the `Add key` drop-down menu, then select `Create new key` -- Select `JSON` as the Key type and click `Create` +1. Log out of NetBird Dashboard +2. On the login page, you should see a "Google" button +3. Click it and sign in with your Google account +4. You should be redirected back to NetBird and logged in + +### Restricting to Google Workspace Domains + +To limit authentication to specific Google Workspace domains: + +1. Go to **APIs & Services** → **OAuth consent screen** +2. Under **User type**, select **Internal** (Workspace only) +3. For external apps, verify your domain to restrict access -When you create a service account key by using the Google Cloud console, most browsers immediately download the new key and save it in a download folder on your computer. -Read how to manage and secure your service keys [here](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys#temp-locations) +Domain restrictions are configured in Google Cloud Console, not in NetBird. -- Open downloaded json file and take note of `client_id` will be used later as `Service Account Client ID` +--- + +## Standalone Setup (Advanced) + +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) 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. + + +### Prerequisites + +- A Google Workspace account (not just personal Google) +- Admin permissions in Google Workspace +- A project in [Google Cloud Console](https://console.cloud.google.com) +- Enable **Admin SDK API** for your project at https://console.cloud.google.com/apis/library/admin.googleapis.com + +### Step 1: Configure OAuth Consent Screen + +1. Navigate to [OAuth consent](https://console.cloud.google.com/apis/credentials/consent) +2. Select **Internal** User Type and click **Create** -## Step 5: Grant user management admin role to service account -- Navigate to [Admin Console](https://admin.google.com/ac/home) page -- Select `Account` on the left menu and then click `Admin Roles` -- Click `Create new role` -- Fill in the form with the following values and click `CREATE` - - name: `User Management ReadOnly` - - description: `User Management ReadOnly` -- Click `CONTINUE`

- high-level-dia + Consent screen type

-- Scroll down to `Admin API privileges` and add the following privileges - - Users: `Read` -- Click `CONTINUE` +3. Fill in the form: + - **App name**: `Netbird` + - **User support email**: `` + - **Authorized domain**: `` + - **Developer contact information**: `` +4. Click **SAVE AND CONTINUE** +5. Click **ADD OR REMOVE SCOPES** +6. Select `/auth/userinfo.email`, `/auth/userinfo.profile`, and `openid` +7. Click **UPDATE** +

- high-level-dia -

-- Verify preview of assigned Admin API privileges to ensure that everything is properly configured, and then click `CREATE ROLE` -- Click `Assign service accounts`, add service account email address and then click `ADD` -

- high-level-dia -

-- Click `ASSIGN ROLE` to assign service account to `User Management ReadOnly` role -

- high-level-dia + Consent screen scopes

-- Navigate to [Account Settings](https://admin.google.com/ac/accountsettings/profile?hl=en_US) page and take note of `Customer ID` +8. Click **SAVE AND CONTINUE** +9. Review the summary and click **BACK TO DASHBOARD** -- Encode service account json key into base64 format - ```sh - base64 -i - ``` +

+ Consent screen summary +

-- Set properties in the `setup.env` file: -```json +### Step 2: Create OAuth 2.0 Credentials + +1. Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) +2. Click **CREATE CREDENTIALS** → **OAuth client ID** +3. Fill in: + - **Application type**: `Web application` + - **Name**: `netbird` + - **Authorized JavaScript origins**: `https://` and `http://localhost` + - **Authorized redirect URIs**: + - `https:///auth` + - `https:///silent-auth` + - `http://localhost:53000` +4. Click **CREATE** + +

+ OAuth client +

+ +5. Note **Client ID** and **Client Secret** + +

+ OAuth client created +

+ +### Step 3: Create Service Account + +1. Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) +2. Click **CREATE CREDENTIALS** → **Service account** +3. Fill in: + - **Service account name**: `netbird` + - **Service account ID**: `netbird` +4. Note the service account email address +5. Click **DONE** + +

+ Create service account +

+ +### Step 4: Create Service Account Keys + +1. Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) +2. Under **Service Accounts**, click **netbird** to edit + +

+ Edit service account +

+ +3. Click the **Keys** tab +4. Click **Add key** → **Create new key** +5. Select **JSON** and click **Create** + + +The key file downloads automatically. Store it securely. Read about [managing service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys#temp-locations). + + +6. Open the downloaded JSON file and note the `client_id` (Service Account Client ID) + +### Step 5: Grant User Management Admin Role + +1. Navigate to [Admin Console](https://admin.google.com/ac/home) +2. Select **Account** → **Admin Roles** +3. Click **Create new role** +4. Fill in: + - **Name**: `User Management ReadOnly` + - **Description**: `User Management ReadOnly` +5. Click **CONTINUE** + +

+ New role info +

+ +6. Scroll to **Admin API privileges** and add: + - **Users**: `Read` +7. Click **CONTINUE** + +

+ Privileges review +

+ +8. Click **CREATE ROLE** +9. Click **Assign service accounts** +10. Add the service account email address +11. Click **ADD** then **ASSIGN ROLE** + +

+ Assign role +

+ +

+ Service account privileges +

+ +12. Navigate to [Account Settings](https://admin.google.com/ac/accountsettings/profile) and note the **Customer ID** + +### Step 6: Encode Service Account Key + +```bash +base64 -i +``` + +### Step 7: Configure NetBird + +Set properties in the `setup.env` file: + +```shell NETBIRD_DOMAIN="" NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://accounts.google.com/.well-known/openid-configuration" NETBIRD_USE_AUTH0=false @@ -141,5 +253,42 @@ NETBIRD_IDP_MGMT_EXTRA_SERVICE_ACCOUNT_KEY="" NETBIRD_IDP_MGMT_EXTRA_CUSTOMER_ID="" ``` -## Step 6: Continue with the NetBird Self-hosting Guide -You've configured all required resources in Google Workspace. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). \ No newline at end of file +### Step 8: Continue with NetBird Setup + +You've configured all required resources in Google Workspace. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). + +--- + +## Troubleshooting + +### "Access blocked" error + +- Ensure OAuth consent screen is configured correctly +- For external apps, you may need to submit for verification or add test users +- Check that required scopes are added + +### "Invalid redirect URI" error + +- Verify the redirect URI exactly matches what's in Google Cloud Console +- Check for trailing slashes or HTTP vs HTTPS mismatches +- Google is case-sensitive for redirect URIs + +### Users from wrong domain signing in + +- For Workspace, use **Internal** user type in OAuth consent screen +- Verify domain restrictions in consent screen settings + +### Service account not syncing users + +- Verify Admin SDK API is enabled +- Check that the service account has the User Management ReadOnly role +- Ensure the Customer ID is correct + +--- + +## Related Resources + +- [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) \ 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 9d2b324d..d3b17e88 100644 --- a/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx +++ b/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx @@ -1,105 +1,204 @@ import {Note} from "@/components/mdx"; -# JumpCloud with NetBird Self-Hosted +# JumpCloud -This guide is a part of the [NetBird Self-hosting Guide](/getting-started/self-hosting) and explains how to integrate -**self-hosted** NetBird with [JumpCloud](https://jumpcloud.com/). +[JumpCloud](https://jumpcloud.com/) is a cloud-based directory platform that provides identity, access, and device management. It offers single sign-on (SSO), multi-factor authentication (MFA), and centralized user management. -Before you start creating and configuring an JumpCloud application, ensure that you have the following: -- An JumpCloud account: To create application, you must have an JumpCloud account. If you don't have one, sign up at https://jumpcloud.com/. -- User account with admin permissions: You must have an JumpCloud account with the admin permissions. If you don't have the required permissions, ask your administrator to grant them to you. +## Connector Setup (Recommended) +Add JumpCloud as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments. -## Step 1: Create and configure SSO application +### Prerequisites -- Navigate to to [Admin Portal](https://console.jumpcloud.com/) page -- Click `SSO Applications` on the left menu under `USER AUTHENTICATION` section -- Click `Add New Application` and select `Custom Application` -

- high-level-dia -

-- On the `Which application would you like to integrate` screen, confirm that you've selected `Custom application` and click `Next` -

- high-level-dia -

-- On the `Select the features you would like to enable` screen, select `Manage Single Sign-On (SSO)` and check `Configure SSO with OIDC` and click `Next` -

- high-level-dia -

-- On the `Enter General info` screen, add `NetBird` as `Display Label` and click `Next` -

- high-level-dia -

-- On the confirmation screen, review the information and click on `Configure Application` to proceed -

- high-level-dia -

-- On the `New Application` screen, click on the SSO tab and enter the following values: - - Under `Endpoint Configuration` section: - - Redirect URIs: `https:///silent-auth`, `https:///auth` and `http://localhost:53000` - - Client Authentication Type: `Public (None PKCE)` - - Login URL: `https://` +- NetBird self-hosted with embedded IdP enabled +- JumpCloud account with admin permissions + +### Step 1: Create OIDC Application in JumpCloud + +1. Navigate to [JumpCloud Admin Portal](https://console.jumpcloud.com/) +2. Click **SSO Applications** under **USER AUTHENTICATION** +3. Click **Add New Application** → **Custom Application** +4. Confirm **Custom application** and click **Next** +5. Select **Manage Single Sign-On (SSO)** and check **Configure SSO with OIDC** +6. Click **Next** +7. Enter **Display Label**: `NetBird` +8. Click **Next** +9. Review and click **Configure Application** +10. On the **SSO** tab, configure: + - **Client Authentication Type**: `Confidential` + - Leave redirect URIs empty for now +11. Click **Activate** +12. Note the **Client ID** and **Client Secret** + +### Step 2: Add Connector in NetBird + +1. Log in to your NetBird Dashboard +2. Navigate to **Settings** → **Identity Providers** +3. Click **Add Identity Provider** +4. Fill in the fields: + +| Field | Value | +|-------|-------| +| Type | Generic OIDC | +| Name | JumpCloud (or your preferred display name) | +| Client ID | From JumpCloud | +| Client Secret | From JumpCloud | +| Issuer | `https://oauth.id.jumpcloud.com` | + +5. Click **Save** + +### Step 3: Configure Redirect URI + +After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your JumpCloud application: + +1. Return to JumpCloud Admin → **SSO Applications** → **NetBird** +2. Click the **SSO** tab +3. Under **Redirect URIs**, add the redirect URL from NetBird +4. Click **Save** + +### Step 4: Assign User Groups + +1. Click the **User Groups** tab +2. Select the user groups that can access NetBird +3. Click **Save** + +### Step 5: Test the Connection + +1. Log out of NetBird Dashboard +2. On the login page, you should see a "JumpCloud" button +3. Click it and authenticate with your JumpCloud credentials +4. You should be redirected back to NetBird and logged in + +--- + +## Standalone Setup (Advanced) + +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) 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 + +- JumpCloud account with admin permissions (sign up at https://jumpcloud.com/) +- Docker and Docker Compose for NetBird + +### Step 1: Create and Configure SSO Application + +1. Navigate to [Admin Portal](https://console.jumpcloud.com/) +2. Click **SSO Applications** under **USER AUTHENTICATION** +3. Click **Add New Application** → **Custom Application**

- high-level-dia + New SSO app

- - Under `Attribute Mapping (optional)` section: - - Standard Scopes: `Email`, `Profile` -

- high-level-dia -

-- Click on the `User Groups` tab and select the user groups that can access this application -

- high-level-dia -

-- Click `Activate` -

- high-level-dia -

-- Take note of `Client ID`, will be used later -## Step 2: Create an account administrator for integration -The NetBird management system requires an API token to get user information from JumpCloud. This API is bound to an administrator user configured in JumpCloud's admin portal. +4. Confirm **Custom application** selected and click **Next** + +

+ Confirm selection +

+ +5. Select **Manage Single Sign-On (SSO)** and check **Configure SSO with OIDC** +6. Click **Next** + +

+ SSO features +

+ +7. Enter **Display Label**: `NetBird` +8. Click **Next** + +

+ General info +

+ +9. Review and click **Configure Application** + +

+ Confirmation +

+ +10. On the **SSO** tab, configure: + - **Redirect URIs**: + - `https:///silent-auth` + - `https:///auth` + - `http://localhost:53000` + - **Client Authentication Type**: `Public (None PKCE)` + - **Login URL**: `https://` + +

+ SSO configuration +

+ +11. Under **Attribute Mapping (optional)**: + - **Standard Scopes**: `Email`, `Profile` + +

+ Attribute configuration +

+ +12. Click **User Groups** tab and select groups that can access the application + +

+ User groups +

+ +13. Click **Activate** + +

+ OIDC app +

+ +14. Note the **Client ID** + +### Step 2: Create Administrator for Integration + +The NetBird management system requires an API token to get user information from JumpCloud. -The following steps will assume that you are creating a new account. If you already have a user for this purpose, confirm it has the required role described below and skip to Step 3 in this guide. -- Navigate to to [Admin Portal](https://console.jumpcloud.com/) page -- Go to account `Settings` and click on the add button (+) -- On the `Create New Administrator` window, enter the following values: - - First Name: `NetBird` - - Last Name: `Integration` - - Administrator Email: `netbird-user@` # this email will be used to receive the login instructions - - Role: `Read Only` - - Click `Save` - Optional - - NetBird offers the ability to automatically delete a user from the JumpCloud side when the user is deleted from the associated account. - To enable this functionality, simply include the `--user-delete-from-idp` flag in the management startup command within your Docker Compose configuration. If you choose to enable this feature, - please ensure that you assign the `Help Desk` role to the `NetBird Integration` user following the steps outlined above. +If you already have an integration user, confirm it has the required role and skip to Step 3. + +1. Navigate to [Admin Portal](https://console.jumpcloud.com/) +2. Go to **Settings** and click the add button (+) +3. Fill in: + - **First Name**: `NetBird` + - **Last Name**: `Integration` + - **Administrator Email**: `netbird-user@` + - **Role**: `Read Only` +4. Click **Save** +

- high-level-dia + Add admin user

-After following the steps above, you will receive the login instructions for the newly created user in the email configured. Please follow the instructions to set a password for the user. + +**Optional**: To enable automatic user deletion from JumpCloud when deleted from NetBird, add the `--user-delete-from-idp` flag to the management startup command and assign the `Help Desk` role instead. + -## Step 3: Generate api token -In this step, we will generate netbird api token in jumpcloud for authorizing calls to user api. +5. Check email for login instructions and set a password + +### Step 3: Generate API Token + +1. Log in to [Admin Portal](https://console.jumpcloud.com/) with the integration user +2. Click the account initials (top-right) → **My API Key** -- Navigate to to [Admin Portal](https://console.jumpcloud.com/) page -- Login with the user created in the previous step or with an existing user -- Click on the account initials displayed at the top-right and select `My API Key` from the drop-down

- high-level-dia -

-- If there is no API key generated, click on `Generate New API Key` button -- Take note of your api token displayed -

- high-level-dia + Profile

-- Set properties in the `setup.env` file: -```json +3. If no key exists, click **Generate New API Key** +4. Copy the API token + +

+ API key generation +

+ +### Step 4: Configure NetBird + +Set properties in the `setup.env` file: + +```shell NETBIRD_DOMAIN="" NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://oauth.id.jumpcloud.com/.well-known/openid-configuration" NETBIRD_USE_AUTH0=false @@ -117,5 +216,39 @@ NETBIRD_MGMT_IDP="jumpcloud" NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="" ``` -## Step 4: Continue with the NetBird Self-hosting Guide -You've configured all required resources in JumpCloud. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-5-run-configuration-script). +### Step 5: Continue with NetBird Setup + +You've configured all required resources in JumpCloud. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-5-run-configuration-script). + +--- + +## Troubleshooting + +### "Invalid redirect URI" error + +- Ensure all redirect URIs are configured in JumpCloud +- Check for trailing slashes +- Verify URLs match exactly + +### Users can't access NetBird + +- Verify the user belongs to an assigned user group +- Check that the user group is assigned to the NetBird application + +### API token not working + +- Verify the integration user has appropriate permissions +- Generate a new API token if the current one is invalid + +### Device authorization not available + +- JumpCloud has limited device auth support +- Set `NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"` + +--- + +## Related Resources + +- [JumpCloud Documentation](https://jumpcloud.com/support) +- [JumpCloud Admin Console](https://console.jumpcloud.com/) +- [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 2dcd6153..4803dd16 100644 --- a/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx +++ b/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx @@ -1,133 +1,224 @@ import {Note} from "@/components/mdx"; -# Microsoft Entra ID with NetBird Self-Hosted +# Microsoft Entra ID -This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate **self-hosted** NetBird with [Azure AD](https://azure.microsoft.com/en-us/products/active-directory/). +Use Microsoft accounts for authentication with NetBird. This supports both personal Microsoft accounts and Microsoft Entra ID (formerly Azure AD) for work and school accounts. -Azure AD is a an enterprise identity service that provides single sign-on and multifactor authentication to your applications. -It is a 3rd party managed service and can't be self-hosted. +## Connector Setup (Recommended) + +Add Microsoft as a connector to the embedded IdP. Choose the appropriate connector type based on your needs: + +| Connector Type | Use Case | +|---------------|----------| +| **Microsoft** (`microsoft`) | Personal Microsoft accounts | +| **Microsoft Entra ID** (`entra`) | Work/school accounts via Azure AD | + +### Prerequisites + +- NetBird self-hosted with embedded IdP enabled +- Access to [Azure Portal](https://portal.azure.com/) or [Entra Admin Center](https://entra.microsoft.com/) + +### Step 1: Create App Registration + +1. Navigate to [Azure Portal](https://portal.azure.com/) → **Azure Active Directory** (or [Entra Admin Center](https://entra.microsoft.com/)) +2. Click **App registrations** → **New registration** +3. Fill in: + - **Name**: `NetBird` + - **Supported account types**: Choose based on your needs: + - *Personal accounts only*: `Personal Microsoft accounts only` + - *Work/school only*: `Accounts in this organizational directory only` + - *Both*: `Accounts in any organizational directory and personal Microsoft accounts` + - **Redirect URI**: Leave empty for now +4. Click **Register** +5. Note the **Application (client) ID** and **Directory (tenant) ID** + +### Step 2: Create Client Secret + +1. Go to **Certificates & secrets** +2. Click **New client secret** +3. Add a description and expiration +4. Click **Add** +5. Copy the **Value** immediately (it won't be shown again) + +### Step 3: Add Connector in NetBird + +1. Log in to your NetBird Dashboard +2. Navigate to **Settings** → **Identity Providers** +3. Click **Add Identity Provider** +4. Fill in the fields: + +**For Personal Microsoft Accounts:** + +| Field | Value | +|-------|-------| +| Type | Microsoft | +| Name | Microsoft (or your preferred display name) | +| Client ID | Application (client) ID from Azure | +| Client Secret | Secret value from Azure | + +**For Microsoft Entra ID (Work/School):** + +| Field | Value | +|-------|-------| +| Type | Microsoft Entra ID | +| Name | Microsoft Work (or your preferred display name) | +| Client ID | Application (client) ID from Azure | +| Client Secret | Secret value from Azure | +| Tenant ID | Directory (tenant) ID from Azure | + +5. Click **Save** + +### Step 4: Configure Redirect URI + +After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Azure app: + +1. Return to Azure Portal → Your app registration +2. Go to **Authentication** +3. Click **Add a platform** → **Single-page application** +4. Add the redirect URL from NetBird +5. Click **Configure** + +### Step 5: Test the Connection + +1. Log out of NetBird Dashboard +2. On the login page, you should see the Microsoft button +3. Click it and sign in with your Microsoft account +4. You should be redirected back to NetBird and logged in + +--- + +## Standalone Setup (Advanced) + +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) 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 and authorization of your NetBird network, there are good - self-hosted alternatives to the managed Auth0 service like [Keycloak](/selfhosted/identity-providers#keycloak). +If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak). -Before you start creating and configuring an Azure AD application, ensure that you have the following: -- An Azure account: To create an Azure AD application, you must have an Azure account. If you don't have one, sign up for a free account at https://azure.microsoft.com/free/. +### Prerequisites -- User account with appropriate permissions: You must have an Azure AD user account with the appropriate permissions to create and manage Azure AD applications. If you don't have the required permissions, ask your Azure AD administrator to grant them to you. +- An Azure account with appropriate permissions +- Docker and Docker Compose for NetBird +### Step 1: Create and Configure Azure AD Application -## Step 1. Create and configure Azure AD application -In this step, we will create and configure NetBird application in azure AD. -- Navigate to [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview) -- Click `App Registrations` in the left menu then click on the `+ New registration` button to create a new application. -- Fill in the form with the following values and click Register - - Name: `Netbird` - - Account Types: `Accounts in this organizational directory only (Default Directory only - Single tenant)` - - Redirect URI: select `Single-page application (SPA)` and URI as `https:///silent-auth` +1. Navigate to [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview) +2. Click **App Registrations** → **+ New registration** +3. Fill in: + - **Name**: `Netbird` + - **Supported account types**: `Accounts in this organizational directory only (Single tenant)` + - **Redirect URI**: Select `Single-page application (SPA)` and enter `https:///silent-auth` +4. Click **Register**

- high-level-dia + New application

-#### Step 2. Platform configurations -- Click `Authentication` on the left side menu -- Under the `Single-page application` Section, add another URI `https:///auth` +### Step 2: Configure Platform Settings + +1. Click **Authentication** on the left menu +2. Under **Single-page application**, add another URI: `https:///auth`

- high-level-dia + SPA URI setup

-- Scroll down and setup other options as on the screenshot below and click Save +3. Scroll down and configure options as shown:

- high-level-dia + Flows setup

-- Click `Add a Platform` and select `Mobile and desktop applications` -- Fill in the form with the following values and click Configure - - Custom redirect URIs: `http://localhost:53000` -

- high-level-dia -

+4. Click **Add a Platform** → **Mobile and desktop applications** +5. Add custom redirect URI: `http://localhost:53000` +6. Click **Configure** -## Step 3. Create a NetBird application scope -- Click `Expose an API` on the left menu -- Under `Application ID URI` click `Set` and then `Save` -- Click `+ Add a Scope` -- Fill in the form with the following values and click `Add scope` -- Scope name: `api` +### Step 3: Create Application Scope + +1. Click **Expose an API** on the left menu +2. Under **Application ID URI**, click **Set** then **Save** +3. Click **+ Add a Scope** +4. Fill in: + - **Scope name**: `api` +5. Click **Add scope**

- high-level-dia + Add scope

-- Under `Authorized client Applications`, click on `+ add a client application` and enter the following: -- Fill in the form with the following values and click `Add application` -- Client ID: same as your Application ID URI minus the `api://` +6. Under **Authorized client applications**, click **+ Add a client application** +7. Enter your **Client ID** (same as Application ID URI minus `api://`) +8. Click **Add application**

- high-level-dia + Add application scope

+### Step 4: Add API Permissions -## Step 4. Add API permissions -Add `Netbird` permissions - -- Click `API permissions` on the left menu -- Click `Add a permission` -- Click `My APIs` tab, and select `Netbird`. Next check `api` permission checkbox and click `Add permissions`. +1. Click **API permissions** on the left menu +2. Click **Add a permission** +3. Select **My APIs** tab → **Netbird** → check `api` permission → **Add permissions**

- high-level-dia + NetBird API permissions

-Add `Delegated permissions` to Microsoft Graph - -- Click `Add a permission` -- Click `Microsoft Graph` and then click `Application permissions` tab -- In `Select permissions` search for `User.Read` and under the `User` section select `User.Read.All` and click `Add permissions` +4. Click **Add a permission** again +5. Select **Microsoft Graph** → **Application permissions** +6. Search for `User.Read` and select `User.Read.All` +7. Click **Add permissions**

- high-level-dia + OpenID permissions

- -- Click `Grant admin consent for Default Directory` and click `Yes` +8. Click **Grant admin consent for Default Directory** → **Yes**

- high-level-dia + Grant admin consent

-## Step 5. Update token version -- Click `Manifest` on left menu -- Search for `accessTokenAcceptedVersion` and change the value from `null` to `2` -- Click `Save` +### Step 5: Update Token Version -## Step 6. Generate client secret -- Click `Certificates & secrets` on left menu -- Click `New client secret` -- Fill in the form with the following values and click `Add` -- Description: `Netbird` -- Copy `Value` and save it as it can be viewed only once after creation. +1. Click **Manifest** on the left menu +2. Find `accessTokenAcceptedVersion` and change from `null` to `2` +3. Click **Save** + +### Step 6: Generate Client Secret + +1. Click **Certificates & secrets** on the left menu +2. Click **New client secret** +3. Fill in: + - **Description**: `Netbird` +4. Click **Add** +5. Copy the **Value** immediately

- high-level-dia + Client secret

-- Click `Overview` on left menu and take note of `Application (client) ID`, `Object ID` and `Directory (tenant) ID` -will be required in next step. +6. Click **Overview** and note: + - **Application (client) ID** + - **Object ID** + - **Directory (tenant) ID** + +### Step 7: Configure NetBird + +Your authority OIDC configuration will be available at: -Your authority OIDC configuration will be available under: ```bash https://login.microsoftonline.com//v2.0/.well-known/openid-configuration ``` + - Double-check if the endpoint returns a JSON response by calling it from your browser. +Double-check if the endpoint returns a JSON response by calling it from your browser. -- Set properties in the `setup.env` file: +Set properties in the `setup.env` file: + ```shell NETBIRD_DOMAIN="" NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://login.microsoftonline.com//v2.0/.well-known/openid-configuration" @@ -147,8 +238,43 @@ NETBIRD_IDP_MGMT_CLIENT_ID="" NETBIRD_IDP_MGMT_CLIENT_SECRET="" NETBIRD_IDP_MGMT_EXTRA_OBJECT_ID="" NETBIRD_IDP_MGMT_EXTRA_GRAPH_API_ENDPOINT="https://graph.microsoft.com/v1.0" - ``` -## Step 7: Continue with the NetBird Self-hosting Guide -You've configured all required resources in Azure AD. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). \ No newline at end of file +### Step 8: Continue with NetBird Setup + +You've configured all required resources in Azure AD. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). + +--- + +## Troubleshooting + +### "AADSTS50011: The redirect URI specified in the request does not match" + +- Ensure the redirect URI in Azure exactly matches what NetBird provides +- Check platform type (SPA vs Mobile/Desktop) +- Verify no trailing slashes + +### "AADSTS700016: Application not found" + +- Verify the Application (client) ID is correct +- Check tenant ID for single-tenant apps +- Ensure the app registration is in the correct directory + +### Users from wrong tenant signing in + +- Use single-tenant configuration for organization-only access +- Verify "Supported account types" setting in app registration + +### Token validation errors + +- Ensure `accessTokenAcceptedVersion` is set to `2` in the manifest +- Verify all scopes are properly configured +- Check that admin consent was granted + +--- + +## Related Resources + +- [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) \ 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 9f8e75d7..601f789c 100644 --- a/src/pages/selfhosted/identity-providers/managed/okta.mdx +++ b/src/pages/selfhosted/identity-providers/managed/okta.mdx @@ -1,115 +1,185 @@ import {Note} from "@/components/mdx"; -# Okta with NetBird Self-Hosted +# Okta -This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate -**self-hosted** NetBird with [Okta](https://www.okta.com/). +[Okta](https://www.okta.com/) is a cloud-based identity and access management service for enterprise use, providing single sign-on, multi-factor authentication, and lifecycle management. + +## Connector Setup (Recommended) + +Add Okta as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments. + +### Prerequisites + +- NetBird self-hosted with embedded IdP enabled +- Okta Workforce Identity Cloud account + +### Step 1: Create OIDC Application in Okta + +1. Navigate to Okta Admin Dashboard +2. Click **Applications** → **Applications** +3. Click **Create App Integration** +4. Select: + - **Sign-in method**: `OIDC - OpenID Connect` + - **Application type**: `Web Application` +5. Click **Next** +6. Fill in: + - **App integration name**: `NetBird` + - **Grant type**: `Authorization Code` + - Leave redirect URIs empty for now +7. Click **Save** +8. Note the **Client ID** and **Client Secret** + +### Step 2: Add Connector in NetBird + +1. Log in to your NetBird Dashboard +2. Navigate to **Settings** → **Identity Providers** +3. Click **Add Identity Provider** +4. Fill in the fields: + +| Field | Value | +|-------|-------| +| Type | Okta | +| Name | Okta (or your preferred display name) | +| Client ID | From Okta application | +| Client Secret | From Okta application | +| Issuer | Your Okta URL (e.g., `https://your-org.okta.com`) | + +5. Click **Save** + +### Step 3: Configure Redirect URI + +After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Okta application: + +1. Return to Okta Admin → **Applications** → **NetBird** +2. Click **Edit** in the General Settings +3. Add the redirect URL from NetBird to **Sign-in redirect URIs** +4. Click **Save** + +### Step 4: Test the Connection + +1. Log out of NetBird Dashboard +2. On the login page, you should see an "Okta" button +3. Click it and authenticate with your Okta credentials +4. You should be redirected back to NetBird and logged in + +--- + +## Standalone Setup (Advanced) + +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) 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 and authorization of your NetBird network, there are good self-hosted alternatives to the managed Okta service like [Keycloak](/selfhosted/identity-providers#keycloak). +If you prefer to have full control over authentication, consider self-hosted alternatives like [Keycloak](/selfhosted/identity-providers/keycloak). -Before you start creating and configuring an Okta application, ensure that you have an Okta workforce identity cloud account. If you don't have one, sign up for a free account at https://www.okta.com/free-trial/. +### Prerequisites -## Step 1. Create and configure Okta single-page application -In this step, we will create and configure Netbird single-page application in okta. -- Navigate to Okta Admin Dashboard -- Click `Applications` in the left menu and then click on `Applications` -- Click `Create App Integration` -- Fill in the form with the following values and click `Next` - - Sign-in method: `OIDC - OpenID Connect` - - Application type: `Single-Page Application` +- Okta Workforce Identity Cloud account (sign up at https://www.okta.com/free-trial/) +- Docker and Docker Compose for NetBird + +### Step 1: Create Single-Page Application + +1. Navigate to Okta Admin Dashboard +2. Click **Applications** → **Applications** +3. Click **Create App Integration** +4. Select: + - **Sign-in method**: `OIDC - OpenID Connect` + - **Application type**: `Single-Page Application` +5. Click **Next**

- high-level-dia + New SPA application

-- Fill in the form with the following values and click `Save` - - App integration name: `Netbird` - - Grant type: `Authorization Code` and `Refresh Token` - - Sign-in redirect URIs: `https:///auth`, `https:///silent-auth` and `http://localhost:53000` - - Sign-out redirect URIs: `https:///` -- Click `Save` +6. Fill in: + - **App integration name**: `Netbird` + - **Grant type**: `Authorization Code` and `Refresh Token` + - **Sign-in redirect URIs**: + - `https:///auth` + - `https:///silent-auth` + - `http://localhost:53000` + - **Sign-out redirect URIs**: `https:///` +7. Click **Save**

- high-level-dia + SPA application config

-- Navigate to Okta Admin Dashboard -- Click `Applications` in the left menu and then click on `Applications` -- Select `Netbird` application on the list and take a note of the `Client ID`, we will use it later -- Click on `Sign On` tab on top menu -- Under `OpenID Connect ID Token` section, click `Edit` and update `Issuer` to use the `Okta URL` -- Click `Save` +8. Note the **Client ID** +9. Click **Sign On** tab +10. Under **OpenID Connect ID Token**, click **Edit** and set **Issuer** to use the `Okta URL` +11. Click **Save**

- high-level-dia + Sign-on configuration

-## Step 2. Create and configure Okta native application -In this step, we will create and configure Netbird native application in okta. -- Navigate to Okta Admin Dashboard -- Click `Applications` in the left menu and then click on `Applications` -- Click `Create App Integration` -- Fill in the form with the following values and click `Next` - - Sign-in method: `OIDC - OpenID Connect` - - Application type: `Native Application` +### Step 2: Create Native Application (for Device Auth) + +1. Click **Applications** → **Applications** +2. Click **Create App Integration** +3. Select: + - **Sign-in method**: `OIDC - OpenID Connect` + - **Application type**: `Native Application` +4. Click **Next**

- high-level-dia + New native application

-- Fill in the form with the following values and click `Save` - - App integration name: `Netbird Native App` - - Grant type: `Device Authorization` -- Click `Save` +5. Fill in: + - **App integration name**: `Netbird Native App` + - **Grant type**: `Device Authorization` +6. Click **Save**

- high-level-dia + Native application config

-- Navigate to Okta Admin Dashboard -- Click `Applications` in the left menu and then click on `Applications` -- Select `Netbird Native App` application on the list and take a note of the `Client ID`, we will use it later -- Click on `Sign On` tab on top menu -- Under `OpenID Connect ID Token` section, click `Edit` and update `Issuer` to use the `Okta URL` -- Click `Save` +7. Note the **Client ID** (for device auth) +8. Click **Sign On** tab +9. Under **OpenID Connect ID Token**, set **Issuer** to use the `Okta URL` +10. Click **Save**

- high-level-dia + Native sign-on configuration

+### Step 3: Generate API Token -## Step 3. Generate api token -In this step, we will generate netbird api token in okta for authorizing calls to user api. - -- Navigate to Okta Admin Dashboard -- Click `Security` in the left menu and then click on `API` -- Click on `Tokens` tab on top menu -- Click `Create token` -- Fill in the form with the following values and click `Create token` - - Name: `Netbird` -- Take note of token value and click `OK, got it` +1. Click **Security** → **API** +2. Click **Tokens** tab +3. Click **Create token** +4. Enter: + - **Name**: `Netbird` +5. Click **Create token** +6. Copy the token value and click **OK, got it**

- high-level-dia + Generate token

+### Step 4: Configure NetBird + +Your authority OIDC configuration will be available at: -Your authority OIDC configuration will be available under: ```bash https:///.well-known/openid-configuration ``` + - Double-check if the endpoint returns a JSON response by calling it from your browser. +Double-check if the endpoint returns a JSON response by calling it from your browser. -- Set properties in the `setup.env` file: -```json +Set properties in the `setup.env` file: + +```shell NETBIRD_DOMAIN="" NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///.well-known/openid-configuration" NETBIRD_USE_AUTH0=false -NETBIRD_AUTH_AUDIENCE="<>" +NETBIRD_AUTH_AUDIENCE="" NETBIRD_AUTH_CLIENT_ID="" NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email" NETBIRD_AUTH_REDIRECT_URI="/auth" @@ -117,13 +187,48 @@ NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth" NETBIRD_TOKEN_SOURCE="idToken" NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="hosted" -NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=">" +NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="" NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="" NETBIRD_AUTH_DEVICE_AUTH_SCOPE="openid email" NETBIRD_AUTH_DEVICE_AUTH_USE_ID_TOKEN=true NETBIRD_MGMT_IDP="okta" -NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="" +NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="" ``` -## Step 4: Continue with the NetBird Self-hosting Guide -You've configured all required resources in Okta. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). \ No newline at end of file + +### Step 5: Continue with NetBird Setup + +You've configured all required resources in Okta. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). + +--- + +## Troubleshooting + +### "Invalid redirect URI" error + +- Ensure all redirect URIs are configured in Okta +- Check for trailing slashes +- Verify the application type matches the use case + +### "Invalid issuer" error + +- Ensure the issuer is set to use the Okta URL (not dynamic) +- Verify the OIDC configuration endpoint returns valid JSON + +### Device authorization not working + +- Ensure the native application has "Device Authorization" grant type +- Verify the native client ID is used for device auth settings + +### Users not syncing + +- Verify the API token is valid and not expired +- Check that the token has appropriate permissions + +--- + +## Related Resources + +- [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) \ 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 7a8d1de6..05c3f833 100644 --- a/src/pages/selfhosted/identity-providers/pocketid.mdx +++ b/src/pages/selfhosted/identity-providers/pocketid.mdx @@ -1,72 +1,134 @@ import {Note} from "@/components/mdx"; -# PocketID with NetBird Self-Hosted +# PocketID -This guide is a part of the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide) and explains how to integrate -**self-hosted** NetBird with [PocketID](https://pocket-id.org/). +[PocketID](https://pocket-id.org/) is a simplified identity management solution designed for self-hosted environments, offering a lightweight and easy-to-deploy option for authentication. - PocketID is a simplified identity management solution designed for self hosted environments. - It is secure and effective, but makes some tradeoffs in terms of features and usability. - Notably, it does not allow scoping the access of API Tokens. - This isn't an issue per se, but it does mean that you should keep careful track of the token used by NetBird for management. +PocketID is secure and effective but makes some tradeoffs in terms of features. Notably, it does not allow scoping the access of API Tokens. Keep careful track of the token used by NetBird for management. -## Step 1. Create and configure PocketID application -In this step, we will create and configure NetBird application in pocketid. +## Connector Setup (Recommended) -Create new PocketID OIDC Client -- Navigate to pocketid console -- Click the `Administration` dropdown in the left hand bar, then select `OIDC Clients` -- Fill in the form with the following values and click `Continue` -- Name: `NetBird` -- Client Launch URL: `https://` -- Callback URL's: -- `http://localhost:53000` -- `https:///auth` -- `https:///silent-auth` -- Logout Callback URL: `https:///` -- Public Client: On -- PKCE: On -- Click `Save` +Add PocketID as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments. + +### Prerequisites + +- NetBird self-hosted with embedded IdP enabled +- PocketID instance with admin access + +### Step 1: Create OIDC Client in PocketID + +1. Navigate to PocketID console +2. Click the **Administration** dropdown in the left-hand bar +3. Select **OIDC Clients** +4. Click **Add** to create a new client +5. Fill in the form: + - **Name**: `NetBird` + - **Public Client**: Off (for confidential client) + - **PKCE**: Off +6. Click **Save** +7. Note the **Client ID** and **Client Secret** + +### Step 2: Add Connector in NetBird + +1. Log in to your NetBird Dashboard +2. Navigate to **Settings** → **Identity Providers** +3. Click **Add Identity Provider** +4. Fill in the fields: + +| Field | Value | +|-------|-------| +| Type | PocketID | +| Name | PocketID (or your preferred display name) | +| Client ID | From PocketID | +| Client Secret | From PocketID | +| Issuer | `https://pocketid.example.com` | + +5. Click **Save** + +### Step 3: Configure Redirect URI + +After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your PocketID client: + +1. Return to PocketID console → **OIDC Clients** +2. Edit your NetBird client +3. Add the redirect URL to **Callback URLs** +4. Click **Save** + +### Step 4: Test the Connection + +1. Log out of NetBird Dashboard +2. On the login page, you should see a "PocketID" button +3. Click it and authenticate with your PocketID credentials +4. You should be redirected back to NetBird and logged in + +--- + +## Standalone Setup (Advanced) + +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) 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 + +- PocketID instance running with SSL +- Docker and Docker Compose for NetBird + +### Step 1: Create and Configure PocketID Application + +1. Navigate to PocketID console +2. Click the **Administration** dropdown, then select **OIDC Clients** +3. Fill in the form: + - **Name**: `NetBird` + - **Client Launch URL**: `https://` + - **Callback URLs**: + - `http://localhost:53000` + - `https:///auth` + - `https:///silent-auth` + - **Logout Callback URL**: `https:///` + - **Public Client**: On + - **PKCE**: On +4. Click **Save**

- high-level-dia + Create OIDC client

-- Copy `Client ID` will be used later in the `setup.env` +5. Copy **Client ID** for later use -## Step 2: Application Token Configuration +### Step 2: Create API Token -To configure the application token you need to: - -- Click `Administration` dropdown in the left hand bar, then select `API Keys` -- Click `Add API Key` -- Enter the following values and click `Save` -- Name: 'NetBird Management Token' -- Expires At: Pick a date in the future -- Description: 'NetBird Management Token' -- Click `Save` +1. Click **Administration** dropdown, then select **API Keys** +2. Click **Add API Key** +3. Fill in: + - **Name**: `NetBird Management Token` + - **Expires At**: Pick a date in the future + - **Description**: `NetBird Management Token` +4. Click **Save**

- high-level-dia + Create API token

-- Copy `API Key` will be used later in the `setup.env` +5. Copy **API Key** for later use +### Step 3: Configure NetBird -Your authority OIDC configuration will be available under: +Your authority OIDC configuration will be available at: ```bash https:///.well-known/openid-configuration ``` -:::caution + Double-check if the endpoint returns a JSON response by calling it from your browser. -::: + -- Set properties in the `setup.env` file: -```json +Set properties in the `setup.env` file: + +```shell NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///.well-known/openid-configuration" NETBIRD_USE_AUTH0=false NETBIRD_AUTH_CLIENT_ID="" @@ -86,8 +148,34 @@ NETBIRD_MGMT_IDP="pocketid" NETBIRD_IDP_MGMT_CLIENT_ID="netbird" NETBIRD_IDP_MGMT_EXTRA_MANAGEMENT_ENDPOINT="https://" NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="" - ``` -## Step 3: Continue with the NetBird Self-hosting Guide -You've configured all required resources in PocketID. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). \ No newline at end of file +### Step 4: Continue with NetBird Setup + +You've configured all required resources in PocketID. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). + +--- + +## Troubleshooting + +### "Invalid redirect URI" error + +- Ensure all callback URLs are properly configured in PocketID +- Include both HTTP (localhost) and HTTPS (domain) variants + +### API token not working + +- Verify the token hasn't expired +- Ensure the token was created by an admin user + +### Device authorization not available + +- PocketID has limited device auth support +- Set `NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"` if issues persist + +--- + +## Related Resources + +- [PocketID Documentation](https://pocket-id.org/docs) +- [Embedded IdP Overview](/selfhosted/identity-providers/local) \ 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 4010bcbb..9d331081 100644 --- a/src/pages/selfhosted/identity-providers/zitadel.mdx +++ b/src/pages/selfhosted/identity-providers/zitadel.mdx @@ -1,153 +1,215 @@ import {Note} from "@/components/mdx"; -# Zitadel with NetBird Self-Hosted +# Zitadel -This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate -**self-hosted** NetBird with [Zitadel](https://zitadel.com). +[Zitadel](https://zitadel.com) 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. - If you prefer not to self-host an Identity and Access Management solution, then you could use the managed alternative - [Zitadel Cloud](https://zitadel.com/). +Zitadel was previously used in the NetBird quickstart script. If you have an existing Zitadel deployment, you can continue using it as a standalone IdP or migrate to the embedded IdP with Zitadel as a connector. -## Step 1. Create and configure Zitadel application -In this step, we will create and configure NetBird application in zitadel. +## Connector Setup (Recommended) -Create new zitadel project -- Navigate to zitadel console -- Click `Projects` at the top menu, then click `Create New Project` to create a new project -- Fill in the form with the following values and click `Continue` -- Name: `NETBIRD` +Add Zitadel as a connector to the embedded IdP. This is the simplest approach for new deployments or when migrating from the previous quickstart. -

- high-level-dia -

+### Prerequisites -Create new zitadel application -- Click `Projects` in the top menu and select `NETBIRD` project from the list -- Click `New` in `APPLICATIONS` section to create a new application -- Fill in the form with the following values and click `Continue` -- Name: `netbird` -- TYPE OF APPLICATION: `User Agent` +- NetBird self-hosted with embedded IdP enabled +- Zitadel instance (cloud or self-hosted) -

- high-level-dia -

+### Step 1: Create Application in Zitadel -- Fill in the form with the following values and click `Continue` -- Authentication Method: `PKCE` +1. Log in to your Zitadel Console +2. Navigate to your project (or create one) +3. Click **New** in the **Applications** section +4. Fill in: + - **Name**: `NetBird` + - **Type**: `Web` +5. Click **Continue** +6. Configure authentication: + - **Authentication Method**: `Code` (not PKCE) +7. Leave redirect URIs empty for now +8. Click **Create** +9. Go to **Token Settings** and enable **User Info inside ID Token** +10. Note the **Client ID** and generate a **Client Secret** -

- high-level-dia -

+### Step 2: Add Connector in NetBird -- Fill in the form with the following values and click `Continue` -- Redirect URIs: `https:///auth` and click `+` -- Redirect URIs: `https:///silent-auth` and click `+` -- Redirect URIs: `http://localhost:53000` and click `+` -- Post Logout URIs: `https:///` and click `+` +1. Log in to your NetBird Dashboard +2. Navigate to **Settings** → **Identity Providers** +3. Click **Add Identity Provider** +4. Fill in the fields: -

- high-level-dia -

+| Field | Value | +|-------|-------| +| Type | Zitadel | +| Name | Zitadel (or your preferred display name) | +| Client ID | From Zitadel application | +| Client Secret | From Zitadel application | +| Issuer | Your Zitadel URL (e.g., `https://your-instance.zitadel.cloud`) | -- Verify applications details and Click `Create` and then click `Close` -- Under `Grant Types` select `Authorization Code`, `Device Code` and `Refresh Token` and click `save` +5. Click **Save** -

- high-level-dia -

+### Step 3: Configure Redirect URI -- Copy `Client ID` will be used later in the `setup.env` +After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Zitadel application: -## Step 2: Application Token Configuration +1. Return to Zitadel Console +2. Go to your application → **Redirect Settings** +3. Add the redirect URL from NetBird to **Redirect URIs** +4. Click **Save** -To configure `netbird` application token you need to: +### Step 4: Test the Connection -- Click `Projects` in the top menu and select `NETBIRD` project from the list -- Select `netbird` application from `APPLICATIONS` section -- Click `Token Settings` in the left menu -- Fill in the form with the following values: -- Auth Token Type: `JWT` -- Check `Add user roles to the access token` checkbox -- Click `Save` +1. Log out of NetBird Dashboard +2. On the login page, you should see a "Zitadel" button +3. Click it and authenticate with your Zitadel credentials +4. You should be redirected back to NetBird and logged in -

- high-level-dia -

+--- -## Step 3: Application Redirect Configuration +## Standalone Setup (Advanced) + +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) 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. - This step is intended for setup running in development mode with no SSL +If you prefer not to self-host, Zitadel offers a managed cloud option at [zitadel.com](https://zitadel.com/). -To configure `netbird` application redirect you need to: +### Prerequisites -- Click `Projects` in the top menu and select `NETBIRD` project from the list -- Select `netbird` application from `APPLICATIONS` section -- Click `Redirect Settings` in the left menu -- Fill in the form with the following values: -- Toggle `Development Mode` -- Click `Save` +- Zitadel instance (cloud or self-hosted) with SSL +- Docker and Docker Compose for NetBird + +### Step 1: Create and Configure Zitadel Application + +1. Navigate to Zitadel console +2. Click **Projects** at the top menu, then click **Create New Project** +3. Fill in: + - **Name**: `NETBIRD`

- high-level-dia + New project

-## Step 4: Create a Service User - -In this step we will create a `netbird` service user. - -- Click `Users` in the top menu -- Select `Service Users` tab -- Click `New` -- Fill in the form with the following values: -- User Name: `netbird` -- Name: `netbird` -- Description: `Netbird Service User` -- Access Token Type: `JWT` -- Click `Create` +4. Click **Projects** and select **NETBIRD** project +5. Click **New** in **Applications** section +6. Fill in: + - **Name**: `netbird` + - **Type of Application**: `User Agent`

- high-level-dia + New application

-In this step we will generate `ClientSecret` for the `netbird` service user. - -- Click `Actions` in the top right corner and click `Generate Client Secret` -- Copy `ClientSecret` from the dialog will be used later to set `NETBIRD_IDP_MGMT_CLIENT_SECRET` in the `setup.env` +7. Click **Continue** and set: + - **Authentication Method**: `PKCE`

- high-level-dia + Application auth

-## Step 5: Grant manage-users role to netbird service user - -In this step we will grant `Org User Manager` role to `netbird` service user. - -- Click `Organization` in the top menu -- Click `+` in the top right corner -- Search for `netbird` service user -- Check `Org User Manager` checkbox -- Click `Add` +8. Click **Continue** and configure: + - **Redirect URIs**: + - `https:///auth` + - `https:///silent-auth` + - `http://localhost:53000` + - **Post Logout URIs**: `https:///`

- high-level-dia + Application URIs

-Your authority OIDC configuration will be available under: +9. Click **Create** and then **Close** +10. Under **Grant Types**, select `Authorization Code`, `Device Code`, and `Refresh Token` +11. Click **Save** + +

+ Application overview +

+ +12. Copy **Client ID** for later use + +### Step 2: Configure Token Settings + +1. Select the **netbird** application +2. Click **Token Settings** in the left menu +3. Configure: + - **Auth Token Type**: `JWT` + - Check **Add user roles to the access token** +4. Click **Save** + +

+ Token settings +

+ +### Step 3: Configure Redirect Settings (Development Only) + + +This step is only for development mode without SSL. + + +1. Click **Redirect Settings** in the left menu +2. Toggle **Development Mode** +3. Click **Save** + +

+ Redirect settings +

+ +### Step 4: Create Service User + +1. Click **Users** in the top menu +2. Select **Service Users** tab +3. Click **New** +4. Fill in: + - **User Name**: `netbird` + - **Name**: `netbird` + - **Description**: `Netbird Service User` + - **Access Token Type**: `JWT` +5. Click **Create** + +

+ Create service user +

+ +6. Click **Actions** in the top right corner +7. Click **Generate Client Secret** +8. Copy **ClientSecret** for later use + +

+ Service user secret +

+ +### Step 5: Grant User Manager Role + +1. Click **Organization** in the top menu +2. Click **+** in the top right corner +3. Search for `netbird` service user +4. Check **Org User Manager** checkbox +5. Click **Add** + +

+ Service account role +

+ +### Step 6: Configure NetBird + +Your authority OIDC configuration will be available at: ```bash https:///.well-known/openid-configuration ``` -:::caution + Double-check if the endpoint returns a JSON response by calling it from your browser. -::: + -- Set properties in the `setup.env` file: -```json +Set properties in the `setup.env` file: + +```shell NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https:///.well-known/openid-configuration" NETBIRD_USE_AUTH0=false NETBIRD_AUTH_CLIENT_ID="" @@ -165,9 +227,63 @@ NETBIRD_IDP_MGMT_CLIENT_ID="netbird" NETBIRD_IDP_MGMT_CLIENT_SECRET="" NETBIRD_IDP_MGMT_EXTRA_MANAGEMENT_ENDPOINT="https:///management/v1" NETBIRD_MGMT_IDP_SIGNKEY_REFRESH=true - - ``` -## Step 6: Continue with the NetBird Self-hosting Guide -You've configured all required resources in Zitadel. You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). \ No newline at end of file +### Step 7: Continue with NetBird Setup + +You've configured all required resources in Zitadel. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional). + +--- + +## Migrating from Zitadel Quickstart + +If you deployed NetBird using the previous quickstart script with Zitadel: + +**Option A - Keep using Zitadel standalone**: Continue with your existing setup. No changes needed. + +**Option B - Add Zitadel as connector to embedded IdP**: +1. Deploy new NetBird version with embedded IdP +2. Add your existing Zitadel as a connector (follow connector setup above) +3. Users can continue logging in with Zitadel +4. Optionally create local user accounts as fallback + +**Option C - Migrate fully to embedded IdP**: +1. Export user list from Zitadel +2. Deploy new NetBird version with embedded IdP +3. Recreate users in NetBird Dashboard +4. Decommission Zitadel when ready + +--- + +## Troubleshooting + +### "Invalid redirect URI" error + +- Verify the redirect URI exactly matches what's configured +- Check for trailing slashes +- Ensure the application type is correct (User Agent for Dashboard) + +### "Token validation failed" error + +- Verify the issuer URL is correct +- Ensure **User Info inside ID Token** is enabled +- Check that the audience matches your client ID + +### Service user authentication fails + +- Verify the client secret was copied correctly +- Ensure the service user has **Org User Manager** role + +### Device auth not working + +- Ensure **Device Code** grant type is enabled +- Verify PKCE is configured for the application + +--- + +## Related Resources + +- [Zitadel Documentation](https://zitadel.com/docs) +- [Zitadel GitHub](https://github.com/zitadel/zitadel) +- [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 4b733081..93e80c2b 100644 --- a/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx +++ b/src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx @@ -18,6 +18,19 @@ peer-to-peer connectivity, fallback relayed connections through a network of geo and overall system reliability and availability. It is not an easy task to deploy and maintain such infrastructure in a reliable manner. NetBird is not just one VPN server. You can read more about how NetBird works [here](/about-netbird/how-netbird-works). +## What's New: No External IdP Required + +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) +- **Lower resource requirements** (~1GB RAM vs 2-4GB previously) +- **User management directly in the Dashboard** +- **Optional external IdPs** - Connect Google, Microsoft, Okta, etc. if you want SSO +- **Multiple IdPs supported** - Configure multiple OIDC providers simultaneously + +This makes self-hosting a more viable option for homelabs, small teams, and proof-of-concept deployments. + ## Installation and Maintenance NetBird platform is a combination of [multiple components](/about-netbird/how-netbird-works) that make it possible for @@ -25,7 +38,8 @@ machines to establish direct point-to-point connections and for network administ e.g., control network access. When running the self-hosted version, you are responsible for installing and maintaining all the components as well as backing up -and securing the data. +and securing the data. With local user management built into the Management service, this burden is significantly reduced—you no longer need to maintain separate identity provider infrastructure. + The cloud-hosted NetBird only requires you to install the client software (NetBird agent) on your machines and log them in to the network. The cloud-hosted version is more suitable for organizations that want a hassle-free solution that is easy to set up and maintain. @@ -42,6 +56,10 @@ some additional features that are targeted at business customers and help with n - **[User invites](/manage/team/add-users-to-your-network#direct-user-invites)**. - **[MSP functionality](/manage/for-partners/msp-portal)** for managing multiple tenant networks from a single account. + +SCIM provisioning and some enterprise features require a [Commercial License](https://netbird.io/pricing#on-prem) for self-hosted deployments. + + ## Geo Distributed Relay Servers NetBird uses relay servers to establish connections between machines when a direct point-to-point connections isn't possible. @@ -57,12 +75,27 @@ maintenance effort. When using the cloud-hosted version, you benefit from highly available control plane servers (Management) providing stability for your critical network infrastructure. +## Quick Comparison + +| Aspect | Self-Hosted | Cloud-Hosted | +|--------|-------------|--------------| +| **Setup time** | ~5 minutes with local users | Instant | +| **Infrastructure** | You manage | We manage | +| **Identity provider** | Built-in local users (+ optional external IdPs) | Managed | +| **Multiple IdPs** | Yes, OIDC-compatible | Yes | +| **Relay servers** | Single instance (or DIY geo-distribution) | Geo-distributed globally | +| **High availability** | DIY | Included | +| **SCIM provisioning** | Enterprise license | Included (Business+) | +| **Cost** | Your infrastructure costs | Subscription | +| **Best for** | Homelabs, air-gapped networks, compliance requirements | Teams wanting hassle-free setup | + ## Get started

+- [Self-hosting Quickstart](/selfhosted/selfhosted-quickstart) - Get started with self-hosted NetBird in 5 minutes - Make sure to [star us on GitHub](https://github.com/netbirdio/netbird) - Follow us [on X](https://x.com/netbird) - Join our [Slack Channel](/slack-url) -- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub +- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub \ No newline at end of file diff --git a/src/pages/selfhosted/selfhosted-guide.mdx b/src/pages/selfhosted/selfhosted-guide.mdx index eb68d08a..faa7b2f8 100644 --- a/src/pages/selfhosted/selfhosted-guide.mdx +++ b/src/pages/selfhosted/selfhosted-guide.mdx @@ -8,12 +8,24 @@ a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/cot If you would like to learn more about the architecture please refer to the [architecture section](/about-netbird/how-netbird-works). - It might be a good idea to try NetBird before self-hosting on your servers. - We run NetBird in the cloud, and it will take a few clicks to get started with our managed version. [Check it out!](https://netbird.io/pricing) +**New to self-hosting?** The [Quickstart guide](/selfhosted/selfhosted-quickstart) uses the built-in identity provider and is the fastest way to get started. This advanced guide is for users who need to integrate with an existing IdP or have specific enterprise requirements. -If you are looking for a quick way of trying self-hosted NetBird, please refer to [this guide](/about-netbird/how-netbird-works). Otherwise, continue here to set up -NetBird with custom IdPs. + +It might be a good idea to try NetBird before self-hosting on your servers. +We run NetBird in the cloud, and it will take a few clicks to get started with our managed version. [Check it out!](https://netbird.io/pricing) + + +## When to use this guide + +Use this advanced guide if you: + +- Need to integrate with an **existing identity provider** (Okta, Azure AD, Auth0, etc.) +- Require **SCIM provisioning** for user/group sync (Enterprise) +- Have **compliance requirements** that mandate a specific IdP +- Want **full control** over the authentication infrastructure + +For simpler deployments, the [Quickstart with embedded IdP](/selfhosted/selfhosted-quickstart) is recommended. ## Advanced self-hosting guide with a custom identity provider @@ -123,18 +135,24 @@ NetBird supports generic OpenID (OIDC) protocol allowing integration with any ID NetBird's management service integrates with some of the most popular IDP APIs, allowing the service to cache and display user names and email addresses without storing sensitive data. -Pick the one that suits your needs, follow the steps, and continue with this guide: +Pick the one that suits your needs, follow the **Standalone Setup (Advanced)** section in each guide, and continue with this guide: **Self-hosted options** -- Continue with [Zitadel](/selfhosted/identity-providers#zitadel). -- Continue with [Keycloak](/selfhosted/identity-providers#keycloak). -- Continue with [Authentik](/selfhosted/identity-providers#authentik). +- [Zitadel](/selfhosted/identity-providers/zitadel) - Previously used in the quickstart script +- [Keycloak](/selfhosted/identity-providers/keycloak) - Popular open-source IAM +- [Authentik](/selfhosted/identity-providers/authentik) - Flexible open-source IdP +- [PocketID](/selfhosted/identity-providers/pocketid) - Lightweight self-hosted option **Managed options** -- Continue with [Azure AD](/selfhosted/identity-providers#azure-ad-microsoft-entra-id). -- Continue with [Google Workspace](/selfhosted/identity-providers#google-workspace). -- Continue with [Okta](/selfhosted/identity-providers#okta). -- Continue with [Auth0](/selfhosted/identity-providers#auth0). +- [Microsoft Entra ID](/selfhosted/identity-providers/managed/microsoft-entra-id) - Azure AD / Microsoft 365 +- [Google Workspace](/selfhosted/identity-providers/managed/google-workspace) - Google accounts +- [Okta](/selfhosted/identity-providers/managed/okta) - Enterprise SSO +- [Auth0](/selfhosted/identity-providers/managed/auth0) - Flexible auth platform +- [JumpCloud](/selfhosted/identity-providers/managed/jumpcloud) - Cloud directory + + +Each provider page includes both "Connector Setup" (for use with embedded IdP) and "Standalone Setup (Advanced)" sections. For this guide, follow the **Standalone Setup** section. + ### Step 4: Disable single account mode (optional) @@ -283,10 +301,20 @@ To upgrade NetBird to the latest version, you need to review the [release notes] docker compose up -d --force-recreate ``` +## Migrating to Embedded IdP + +If you've deployed NetBird using this advanced guide and want to simplify your setup by migrating to the embedded IdP: + +1. Your existing IdP can be added as a **connector** to the embedded IdP +2. Users can continue logging in with their existing credentials +3. You can gradually transition to local user management + +See the [Migration Guide](/selfhosted/identity-providers#migration-guide) for detailed instructions. + ## Get in touch Feel free to ping us on [Slack](/slack-url) if you have any questions - NetBird managed version: [https://app.netbird.io](https://app.netbird.io) - Make sure to [star us on GitHub](https://github.com/netbirdio/netbird) -- Follow us [on X](https://x.com/netbird) +- Follow us [on X](https://x.com/netbird) \ No newline at end of file diff --git a/src/pages/selfhosted/selfhosted-quickstart.mdx b/src/pages/selfhosted/selfhosted-quickstart.mdx index be55b194..b92478b3 100644 --- a/src/pages/selfhosted/selfhosted-quickstart.mdx +++ b/src/pages/selfhosted/selfhosted-quickstart.mdx @@ -1,24 +1,17 @@ # Self-hosting quickstart guide (5 min) -NetBird is open-source and can be self-hosted on your servers. +NetBird is open source and can be self-hosted on your servers. It relies on components developed by NetBird Authors [Management Service](https://github.com/netbirdio/netbird/tree/main/management), [Management UI Dashboard](https://github.com/netbirdio/dashboard), [Signal Service](https://github.com/netbirdio/netbird/tree/main/signal), -a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn), and an identity provider (available options will be listed later in this guide). +and a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn). If you would like to learn more about the architecture please refer to the [Architecture section](/about-netbird/how-netbird-works). - - It might be a good idea to try NetBird before self-hosting on your servers. - We run NetBird in the cloud, and it will take a few clicks to get started with our managed version. [Check it out!](https://netbird.io/pricing) - - -## Quick self-hosting with Zitadel IdP -In this guide, we will guide you through deploying NetBird with [Zitadel](https://zitadel.com/) -as the identity provider for user management using a single-line setup script and docker containers. +## Quick self-hosting - This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM. - Follow the [Advanced guide with a custom identity provider](/selfhosted/selfhosted-guide#advanced-self-hosting-guide-with-a-custom-identity-provider) for installations with different IDPs. +This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM. +For advanced setups, see the [Advanced guide](/selfhosted/selfhosted-guide). ### Requirements @@ -30,19 +23,186 @@ as the identity provider for user management using a single-line setup script an **Software requirements:** - Docker installed on the VM with the docker compose plugin ([Docker installation guide](https://docs.docker.com/engine/install/)) or docker with docker-compose in version 2 or higher. -- [jq](https://jqlang.github.io/jq/) installed. In most distributions -Usually available in the official repositories and can be installed with `sudo apt install jq` or `sudo yum install jq` -- [curl](https://curl.se/) installed. -Usually available in the official repositories and can be installed with `sudo apt install curl` or `sudo yum install curl` +- [jq](https://jqlang.github.io/jq/) installed. In most distributions usually available in the official repositories and can be installed with `sudo apt install jq` or `sudo yum install jq` +- [curl](https://curl.se/) installed. Usually available in the official repositories and can be installed with `sudo apt install curl` or `sudo yum install curl` ### Download and run the script Download and run the installation script in a single line: ```bash -export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh | bash +export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash ``` If you want to check the script before running it, you can download it and run it locally: ```bash +curl -sSLO https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh +# check the script +cat getting-started.sh +# run the script +export NETBIRD_DOMAIN=netbird.example.com +bash getting-started.sh +``` + +Replace `netbird.example.com` with your domain name. + + +An example output of the script: + +```bash +root@selfhosted-1:~/netbird# bash getting-started.sh +Rendering initial files... + +Starting NetBird services + +WARN[0000] No services to build +[+] up 9/9 + ✔ Network netbird-selfhosted-3_netbird Created 0.1s + ✔ Volume netbird-selfhosted-3_netbird_caddy_data Created 0.0s + ✔ Volume netbird-selfhosted-3_netbird_management Created 0.0s + ✔ Container netbird-caddy Created 0.2s + ✔ Container netbird-dashboard Created 0.2s + ✔ Container netbird-management Created 0.2s + ✔ Container netbird-relay Created 0.2s + ✔ Container netbird-coturn Created 0.2s + ✔ Container netbird-signal Created 0.2s +Waiting for Management server to become ready . . done + +Done! + +You can access the NetBird dashboard at https://netbird.example.com +Follow the onboarding steps to set up your NetBird instance. +``` + +### Initial setup (Onboarding) + +The script deploys NetBird **without any users**. Once complete, you'll need to create your first user: + +

+ NetBird setup page +

+ +1. Open your browser and navigate to `https://netbird.example.com` +2. You'll be redirected to the setup page (`/setup`) +3. Create your admin account: + - Enter your email address + - Enter your name + - Enter a password + - Click **Create Account** + +You can then log in with your email and password. + + +The `/setup` page is only accessible when no users exist. After creating the first user, it redirects to the regular login page. + + +### Add more users + +#### Local users + +You can add users directly from the NetBird Dashboard: + +

+ Add user +

+ +1. Navigate to **Team** → **Users** +2. Click **Create User** +3. Enter the user's email and name +4. Click **Create** + +A password will be generated and displayed once. Share this securely with the user—it cannot be retrieved later. + +#### Via Identity Provider (Optional) + +If you want users to sign in with their existing accounts from Google, Microsoft, Okta, or other providers, you can connect external identity providers: + +1. Navigate to **Settings** → **Identity Providers** +2. Click **Add Identity Provider** +3. Select your provider type (Google, Microsoft, Okta, or generic OIDC) +4. Enter the OAuth client credentials from your provider +5. Click **Save** + +You can add multiple identity providers. Users will see all configured providers as login options. + +For detailed setup guides, see [Identity Providers](/selfhosted/identity-providers). + +### Backup + +To backup your NetBird installation, you need to copy the configuration files and the Management service databases. + +The configuration files are located in the folder where you ran the installation script. To backup, copy the files to a backup location: +```bash +mkdir backup +cp docker-compose.yml Caddyfile dashboard.env turnserver.conf management.json relay.env backup/ +``` +To save the Management service databases, you need to stop the Management service and copy the files from the store directory using a docker compose command as follows: +```bash +docker compose stop management +docker compose cp -a management:/var/lib/netbird/ backup/ +docker compose start management +``` + +### Upgrade + +To upgrade NetBird to the latest version: + +1. Run the backup steps described in the [backup](#backup) section. +2. Review the [release notes](https://github.com/netbirdio/netbird/releases) for any breaking changes. +3. Pull the latest NetBird docker images: + ```bash + docker compose pull management dashboard signal relay + ``` +4. Restart the NetBird containers with the new images: + ```bash + docker compose up -d --force-recreate management dashboard signal relay + ``` + + +For upgrades from older versions (pre-v0.26.0), see the [Legacy upgrade notes](#legacy-self-hosting-with-zitadel-idp). + + +### Remove +To remove the NetBird installation and all related data from your server, run these commands from the folder where you installed NetBird: +```bash +# remove all NetBird-related containers and volumes (data) +docker compose down --volumes +# remove downloaded and generated config files +rm -f docker-compose.yml Caddyfile dashboard.env turnserver.conf management.json relay.env +``` + +### Troubleshoot + +- **I can't access the `/setup` page** + + The setup page is only available when no users exist. If you've already created a user, go to the main login page instead. + +- **I forgot my admin password** + + You can create a new user via the API using a PAT (Personal Access Token) from an existing admin, or reset the database to start fresh. + +- **SSO provider not appearing on login page** + + Check that the connector is properly configured in **Settings** → **Identity Providers**. Ensure the redirect URL is correctly configured in your IdP. + +For more troubleshooting help, see the [Troubleshooting guide](/selfhosted/troubleshooting). + +--- + +## 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 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. + +### Download and run the script + +```bash +export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh | bash +``` + +If you want to check the script before running it: +```bash curl -sSLO https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh # check the script cat getting-started-with-zitadel.sh @@ -50,62 +210,30 @@ cat getting-started-with-zitadel.sh export NETBIRD_DOMAIN=netbird.example.com bash getting-started-with-zitadel.sh ``` - - Replace `netbird.example.com` with your domain name. - -Once the script execution is complete, you can access your netbird instance via the URL `https://netbird.example.com` using the credentials displayed in your terminal. -### Add users -If you want to add additional users, you can access Zitadel's management console via the URL `https://netbird.example.com/ui/console` with the same credentials. Follow the [Users guide](https://zitadel.com/docs/guides/manage/console/users) -from Zitadel to add additional local users or integrate Zitadel with your existing identity provider by following the guide [Configure identity providers](https://zitadel.com/docs/guides/integrate/identity-providers). +Once the script execution is complete, you can access your NetBird instance via `https://netbird.example.com` using the credentials displayed in your terminal. -### Backup -To backup your NetBird installation, you need to copy the configuration files, the Management service databases, and Zitadel's database. +### Add users (Zitadel) +To add additional users, access Zitadel's management console via `https://netbird.example.com/ui/console` with the same credentials. Follow the [Users guide](https://zitadel.com/docs/guides/manage/console/users) from Zitadel to add additional local users or integrate Zitadel with your existing identity provider by following the guide [Configure identity providers](https://zitadel.com/docs/guides/integrate/identity-providers). + +### Backup (Zitadel) +To backup your NetBird installation with Zitadel, you need to copy the configuration files, the Management service databases, and Zitadel's database. -The configuration files are located in the folder where you ran the installation script. To backup, copy the files to a backup location: ```bash mkdir backup cp docker-compose.yml Caddyfile zitadel.env dashboard.env turnserver.conf management.json relay.env zdb.env backup/ ``` -To save the Management service databases, you need to stop the Management service and copy the files from the store directory using a docker compose command as follows: + +To save the Management service databases: ```bash docker compose stop management docker compose cp -a management:/var/lib/netbird/ backup/ docker compose start management ``` + You can follow the [Cockroach backup guide](https://www.cockroachlabs.com/docs/stable/backup) to backup Zitadel's database, which holds user information. -### Upgrade - -The users with management on version < [v0.15.3](https://github.com/netbirdio/netbird/releases/tag/v0.15.3) -should first upgrade their systems to [v0.25.9](https://github.com/netbirdio/netbird/releases/tag/v0.25.9), -run management to properly migrate rules to policies, and then upgrade to **0.26.0+**. - - -To upgrade NetBird to the latest version, you need to review the [release notes](https://github.com/netbirdio/netbird/releases) for any breaking changes and follow the upgrade steps below: -1. Run the backup steps described in the [backup](#backup) section. -2. Pull the latest NetBird docker images: - ```bash - docker compose pull management dashboard signal relay - ``` -3. Restart the NetBird containers with the new images: - ```bash - docker compose up -d --force-recreate management dashboard signal relay - ``` - -### Support browser clients -If you deployed NetBird before version **0.59.0** and want to use browser clients, you need to update your Signal, Management, Dashboard and Relay services, see [Upgrade](#upgrade), then you need to edit the `Caddyfile` file to enable support for browser clients by adding the following lines to the `Caddyfile`: -``` - reverse_proxy /ws-proxy/management* management:80 - reverse_proxy /ws-proxy/signal* signal:80 -``` -Then restart the Caddy service to apply the changes: -```bash -docker compose restart caddy -``` - -### Remove -To remove the NetBird installation and all related data from your server, run these commands from the folder where you installed NetBird: +### Remove (Zitadel) ```bash # remove all NetBird-related containers and volumes (data) docker compose down --volumes @@ -113,12 +241,24 @@ docker compose down --volumes rm -f docker-compose.yml Caddyfile zitadel.env dashboard.env machinekey/zitadel-admin-sa.token turnserver.conf management.json ``` -### Troubleshoot +### Migrating from Zitadel to Local Users -- I'm trying to register a user but I didn't receive a verification code. What's the problem? +If you have an existing Zitadel deployment and want to migrate: - The NetBird quickstart script generates a user name and a password for the administrator. This should be enough to login and manage your network. - If you want to register a new user and invite them via email, you need to configure a SMTP server in Zitadel. See [this guide](https://zitadel.com/docs/guides/manage/console/instance-settings#smtp) or details. +1. **Option A**: Keep Zitadel as an external provider—add it as an identity provider in Settings +2. **Option B**: Recreate users as local users and decommission Zitadel + +See the [Migration Guide](/selfhosted/identity-providers#migration-guide) for detailed steps. + +### Upgrade (Legacy) + + +If upgrading from management version < [v0.15.3](https://github.com/netbirdio/netbird/releases/tag/v0.15.3), +first upgrade to [v0.25.9](https://github.com/netbirdio/netbird/releases/tag/v0.25.9), +run management to migrate rules to policies, then upgrade to **0.26.0+**. + + +--- ## Get in touch @@ -126,4 +266,4 @@ Feel free to ping us on [Slack](/slack-url) if you have any questions - NetBird managed version: [https://app.netbird.io](https://app.netbird.io) - Make sure to [star us on GitHub](https://github.com/netbirdio/netbird) -- Follow us [on X](https://x.com/netbird) +- Follow us [on X](https://x.com/netbird) \ No newline at end of file diff --git a/src/pages/selfhosted/troubleshooting.mdx b/src/pages/selfhosted/troubleshooting.mdx index 1cf5669e..26463ab0 100644 --- a/src/pages/selfhosted/troubleshooting.mdx +++ b/src/pages/selfhosted/troubleshooting.mdx @@ -1,5 +1,70 @@ # Troubleshooting + This page will help with various issues when self-hosting NetBird. + +## Embedded IdP Issues + +### Setup page not accessible + +**Problem**: You can't access the `/setup` page to create the first user. + +**Solutions**: +- The `/setup` page is only available when no users exist. If you've already created a user, use the regular login page. +- Check that the embedded IdP is enabled in your configuration. +- Verify the Management service is running: `docker compose logs management` + +### "Setup already completed" error (HTTP 412) + +**Problem**: The setup endpoint returns a 412 error. + +**Solution**: Setup has already been completed. The first user was already created. Use the regular login page to sign in. + +### Password not working after user creation + +**Problem**: You created a user but the password doesn't work. + +**Solutions**: +- Passwords are shown only once during user creation. If you didn't save it, you'll need to delete and recreate the user. +- Via API, you can create a new user with a new password. +- For the owner account, you may need to reset the database if no other admins exist. + +### SSO connector not appearing on login page + +**Problem**: You configured an identity provider but it doesn't show on the login page. + +**Solutions**: +1. Verify the connector was saved: Go to **Settings** → **Identity Providers** +2. Check that the redirect URL is correctly configured in your IdP +3. Review Management service logs for configuration errors: `docker compose logs management` +4. Ensure the IdP application has the correct redirect URI from NetBird + +### "Invalid redirect URI" error from IdP + +**Problem**: When clicking an SSO button, the IdP returns an invalid redirect URI error. + +**Solutions**: +1. Copy the exact redirect URL from NetBird (shown after saving the connector) +2. Add it to your IdP's allowed redirect URIs +3. Check for trailing slashes or typos +4. Some IdPs are case-sensitive + +### Identity Providers tab not visible + +**Problem**: You don't see the Identity Providers tab in Settings. + +**Solution**: This tab is only visible when the embedded IdP is enabled. Check your deployment configuration: +- For quickstart deployments, the embedded IdP should be enabled by default +- For advanced deployments, ensure `EmbeddedIdP.Enabled` is set to `true` in management.json + +### Users not syncing from SSO provider + +**Problem**: Users who authenticate via SSO don't appear in the user list. + +**Solutions**: +- Users appear after their first successful login, not immediately after connector configuration +- Check that the SSO flow completes successfully (user should land on Dashboard) +- Review Management logs for any token validation errors + ## Debugging TURN connections In the case that the peer-to-peer connection is not an option then the peer will use the TURN server for the secure connection establishment. If the connection is not possible even with TURN (Relay), @@ -21,3 +86,100 @@ You should see an output similar to the following:

Where you have the following types: `host` (local address), `srflx` (STUN reflexive address), `relay` (TURN relay address). If `srflx` and `relay` are not present then the TURN server is not working or not accessible and you should review the required ports in the [requirements section](/selfhosted/selfhosted-guide#requirements). + +## Dashboard Issues + +### Dashboard shows blank page + +**Problem**: The Dashboard loads but shows a blank page or errors. + +**Solutions**: +1. Check browser console for JavaScript errors (F12 → Console) +2. Verify the Dashboard can reach the Management API +3. Check CORS configuration if running behind a custom reverse proxy +4. Clear browser cache and try again + +### "Unauthorized" or "403" errors + +**Problem**: API calls return unauthorized or forbidden errors. + +**Solutions**: +1. Verify your authentication token is valid +2. Check that the user has appropriate permissions +3. For API access, ensure you're using a valid Personal Access Token (PAT) +4. Review Management service logs for detailed error information + +## Certificate Issues + +### Let's Encrypt certificate not renewing + +**Problem**: SSL certificate expires and doesn't auto-renew. + +**Solutions**: +1. Ensure port 80 is accessible for ACME challenge +2. Check Caddy logs: `docker compose logs caddy` +3. Verify the domain points to the correct IP +4. Manually trigger renewal: `docker compose exec caddy caddy reload` + +### Certificate errors with custom reverse proxy + +**Problem**: SSL errors when using your own reverse proxy. + +**Solutions**: +1. Ensure your reverse proxy terminates SSL correctly +2. Set `NETBIRD_DISABLE_LETSENCRYPT=true` in your configuration +3. Configure proper headers (X-Forwarded-For, X-Forwarded-Proto) +4. Verify HTTP/2 support is enabled for gRPC endpoints + +## Connection Issues + +### Peers can't connect to each other + +**Problem**: Peers are registered but can't establish connections. + +**Solutions**: +1. Check that UDP port 3478 is accessible (STUN/TURN) +2. Verify the TURN server is working (see [TURN debugging](#debugging-turn-connections)) +3. Check firewall rules on both peers +4. Review peer logs: `netbird status -d` + +### Management service unreachable + +**Problem**: Clients can't connect to the Management service. + +**Solutions**: +1. Verify port 443 is accessible +2. Check DNS resolution for your domain +3. Review Management logs: `docker compose logs management` +4. Test with curl: `curl -v https://your-domain.com/api/health` + +## Database Issues + +### Management service won't start after upgrade + +**Problem**: After upgrading, the Management service fails to start. + +**Solutions**: +1. Check logs for migration errors: `docker compose logs management` +2. Ensure you followed the [upgrade path](/selfhosted/selfhosted-quickstart#upgrade) for your version +3. Restore from backup if needed +4. For major version jumps, you may need intermediate upgrades + +### Data corruption after power loss + +**Problem**: Services don't start properly after unexpected shutdown. + +**Solutions**: +1. Check for database lock files +2. Review all service logs +3. Consider restoring from backup +4. For SQLite databases, you may need to run integrity checks + +## Getting Help + +If you're still experiencing issues: + +1. **Check logs**: `docker compose logs` for all services +2. **Search existing issues**: [GitHub Issues](https://github.com/netbirdio/netbird/issues) +3. **Join our community**: [Slack Channel](/slack-url) +4. **Open an issue**: Include logs, configuration (without secrets), and steps to reproduce \ No newline at end of file