DEX Docs Overall Updates

src/components/NavigationAPI.jsx

@@ -23,6 +23,7 @@ export const apiNavigation = [
     links: [
       { title: 'Accounts', href: '/api/resources/accounts' },
       { title: 'Users', href: '/api/resources/users' },
+      { title: 'Identity Providers', href: '/api/resources/identity-providers' },
       { title: 'Tokens', href: '/api/resources/tokens' },
       { title: 'Peers', href: '/api/resources/peers' },
       { title: 'Ingress Ports', href: '/api/resources/ingress-ports' },

src/components/NavigationDocs.jsx

@@ -279,31 +279,18 @@ 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: 'Supported IdPs',
                 isOpen: false,
                 links: [
                     { title: 'Using IdPs on Self-Hosted', href: '/selfhosted/identity-providers' },
+                    { title: 'Embedded IdP', href: '/selfhosted/identity-providers/embedded-idp' },
+                    { title: 'Connectors', href: '/selfhosted/identity-providers/connectors' },
+                    { title: 'API Reference', href: '/selfhosted/identity-providers/api-reference' },
                     {
                         title: 'Self-hosted IdPs',
                         isOpen: true,
@@ -327,10 +314,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: [

src/pages/ipa/resources/accounts.mdx

@@ -2,6 +2,411 @@ export const title = 'Accounts'
 
 
 
+## Get Instance Status  {{ tag: 'GET' , label: '/api/instance' }}
+
+<Row>
+  <Col>
+    Check if the instance requires initial setup. This endpoint is only available when embedded IdP is enabled and no accounts exist. It is **unauthenticated** and only works before setup is complete.
+              </Col>
+
+  <Col sticky>
+    <CodeGroup title="Request" tag="GET" label="/api/instance">
+```bash {{ title: 'cURL' }}
+curl -X GET https://api.netbird.io/api/instance \
+-H 'Accept: application/json'
+```
+
+```js
+const axios = require('axios');
+
+let config = {
+  method: 'get',
+  maxBodyLength: Infinity,
+  url: '/api/instance',
+  headers: {     
+    'Accept': 'application/json'
+  }  
+};
+
+axios(config)
+.then((response) => {
+  console.log(JSON.stringify(response.data));
+})
+.catch((error) => {
+  console.log(error);
+});
+```
+
+```python
+import requests
+import json
+
+url = "https://api.netbird.io/api/instance"
+
+headers = {     
+  'Accept': 'application/json'
+}
+
+response = requests.request("GET", url, headers=headers)
+
+print(response.text)
+```
+
+```go
+package main
+
+import (
+  "fmt"
+  "strings"
+  "net/http"
+  "io/ioutil"
+)
+
+func main() {
+
+  url := "https://api.netbird.io/api/instance"
+  method := "GET"
+  
+  client := &http.Client {
+  }
+  req, err := http.NewRequest(method, url, nil)
+
+  if err != nil {
+    fmt.Println(err)
+    return
+  {  
+  
+  req.Header.Add("Accept", "application/json")
+
+  res, err := client.Do(req)
+  if err != nil {
+    fmt.Println(err)
+    return
+  }
+  defer res.Body.Close()
+
+  body, err := ioutil.ReadAll(res.Body)
+  if err != nil {
+    fmt.Println(err)
+    return
+  }
+  fmt.Println(string(body))
+}
+```
+
+```ruby
+require "uri"
+require "json"
+require "net/http"
+
+url = URI("https://api.netbird.io/api/instance")
+
+https = Net::HTTP.new(url.host, url.port)
+https.use_ssl = true
+
+request = Net::HTTP::Get.new(url)
+request["Accept"] = "application/json"
+
+response = https.request(request)
+puts response.read_body
+```
+
+```java
+OkHttpClient client = new OkHttpClient().newBuilder()
+  .build();
+
+Request request = new Request.Builder()
+  .url("https://api.netbird.io/api/instance")
+  .method("GET")    
+  .addHeader("Accept", "application/json")
+  .build();
+Response response = client.newCall(request).execute();
+```
+
+```php
+<?php
+
+$curl = curl_init();
+
+curl_setopt_array($curl, array(
+  CURLOPT_URL => 'https://api.netbird.io/api/instance',
+  CURLOPT_RETURNTRANSFER => true,
+  CURLOPT_ENCODING => '',
+  CURLOPT_MAXREDIRS => 10,
+  CURLOPT_TIMEOUT => 0,
+  CURLOPT_FOLLOWLOCATION => true,
+  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
+  CURLOPT_CUSTOMREQUEST => 'GET',  
+  CURLOPT_HTTPHEADER => array(        
+    'Accept: application/json'
+  ),
+));
+
+$response = curl_exec($curl);
+
+curl_close($curl);
+echo $response;
+```
+
+    </CodeGroup>
+    
+    
+    <CodeGroup title="Response">
+```json {{ title: 'Example' }}
+{
+  "setup_required": true
+}
+```
+```json {{ title: 'Schema' }}
+{
+  "setup_required": "boolean"
+}
+```
+    </CodeGroup>
+    
+ 
+  </Col>
+</Row>
+
+---
+
+
+## Complete Instance Setup  {{ tag: 'POST' , label: '/api/instance/setup' }}
+
+<Row>
+  <Col>
+    Create the initial owner account. This endpoint is only available when embedded IdP is enabled and no accounts exist. It is **unauthenticated** and only works before setup is complete.
+            
+    ### Request-Body Parameters
+    
+    <Properties><Property name="email" type="string" required={true}>
+        
+            Email address for the owner account
+        
+        </Property>
+    <Property name="password" type="string" required={true}>
+        
+            Password for the owner account (minimum 8 characters)
+        
+        </Property>
+    <Property name="name" type="string" required={false}>
+        
+            Display name for the owner account
+        
+        </Property>
+    </Properties>
+
+    <Note>
+    After setup is complete, accessing this endpoint returns a 412 error and redirects to login.
+    </Note>
+    
+       </Col>
+
+  <Col sticky>
+    <CodeGroup title="Request" tag="POST" label="/api/instance/setup">
+```bash {{ title: 'cURL' }}
+curl -X POST https://api.netbird.io/api/instance/setup \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "email": "admin@example.com",
+  "password": "securepassword123",
+  "name": "Admin User"
+}'
+```
+
+```js
+const axios = require('axios');
+let data = JSON.stringify({
+  "email": "admin@example.com",
+  "password": "securepassword123",
+  "name": "Admin User"
+});
+let config = {
+  method: 'post',
+  maxBodyLength: Infinity,
+  url: '/api/instance/setup',
+  headers: {     
+    'Accept': 'application/json',    
+    'Content-Type': 'application/json'
+  },  
+  data : data
+};
+
+axios(config)
+.then((response) => {
+  console.log(JSON.stringify(response.data));
+})
+.catch((error) => {
+  console.log(error);
+});
+```
+
+```python
+import requests
+import json
+
+url = "https://api.netbird.io/api/instance/setup"
+payload = json.dumps({
+  "email": "admin@example.com",
+  "password": "securepassword123",
+  "name": "Admin User"
+})
+headers = {   
+  'Content-Type': 'application/json',  
+  'Accept': 'application/json'
+}
+
+response = requests.request("POST", url, headers=headers, data=payload)
+
+print(response.text)
+```
+
+```go
+package main
+
+import (
+  "fmt"
+  "strings"
+  "net/http"
+  "io/ioutil"
+)
+
+func main() {
+
+  url := "https://api.netbird.io/api/instance/setup"
+  method := "POST"
+  
+  payload := strings.NewReader(`{
+  "email": "admin@example.com",
+  "password": "securepassword123",
+  "name": "Admin User"
+}`)
+  client := &http.Client {
+  }
+  req, err := http.NewRequest(method, url, payload)
+
+  if err != nil {
+    fmt.Println(err)
+    return
+  {  
+  
+  req.Header.Add("Content-Type", "application/json")  
+  req.Header.Add("Accept", "application/json")
+
+  res, err := client.Do(req)
+  if err != nil {
+    fmt.Println(err)
+    return
+  }
+  defer res.Body.Close()
+
+  body, err := ioutil.ReadAll(res.Body)
+  if err != nil {
+    fmt.Println(err)
+    return
+  }
+  fmt.Println(string(body))
+}
+```
+
+```ruby
+require "uri"
+require "json"
+require "net/http"
+
+url = URI("https://api.netbird.io/api/instance/setup")
+
+https = Net::HTTP.new(url.host, url.port)
+https.use_ssl = true
+
+request = Net::HTTP::Post.new(url)
+request["Content-Type"] = "application/json"
+request["Accept"] = "application/json"
+
+request.body = JSON.dump({
+  "email": "admin@example.com",
+  "password": "securepassword123",
+  "name": "Admin User"
+})
+response = https.request(request)
+puts response.read_body
+```
+
+```java
+OkHttpClient client = new OkHttpClient().newBuilder()
+  .build();
+MediaType mediaType = MediaType.parse("application/json");
+RequestBody body = RequestBody.create(mediaType, '{
+  "email": "admin@example.com",
+  "password": "securepassword123",
+  "name": "Admin User"
+}');
+Request request = new Request.Builder()
+  .url("https://api.netbird.io/api/instance/setup")
+  .method("POST", body)  
+  .addHeader("Content-Type", "application/json")  
+  .addHeader("Accept", "application/json")
+  .build();
+Response response = client.newCall(request).execute();
+```
+
+```php
+<?php
+
+$curl = curl_init();
+
+curl_setopt_array($curl, array(
+  CURLOPT_URL => 'https://api.netbird.io/api/instance/setup',
+  CURLOPT_RETURNTRANSFER => true,
+  CURLOPT_ENCODING => '',
+  CURLOPT_MAXREDIRS => 10,
+  CURLOPT_TIMEOUT => 0,
+  CURLOPT_FOLLOWLOCATION => true,
+  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
+  CURLOPT_CUSTOMREQUEST => 'POST',  
+  CURLOPT_POSTFIELDS => '{
+  "email": "admin@example.com",
+  "password": "securepassword123",
+  "name": "Admin User"
+}',
+  CURLOPT_HTTPHEADER => array(    
+    'Content-Type: application/json',    
+    'Accept: application/json'
+  ),
+));
+
+$response = curl_exec($curl);
+
+curl_close($curl);
+echo $response;
+```
+
+    </CodeGroup>
+    
+    
+    <CodeGroup title="Response">
+```json {{ title: 'Example' }}
+{
+  "user_id": "user-abc123",
+  "account_id": "account-xyz789"
+}
+```
+```json {{ title: 'Schema' }}
+{
+  "user_id": "string",
+  "account_id": "string"
+}
+```
+    </CodeGroup>
+    
+ 
+  </Col>
+</Row>
+
+---
+
+
 ## List all Accounts  {{ tag: 'GET' , label: '/api/accounts' }}
 
 <Row>

src/pages/ipa/resources/users.mdx

@@ -264,7 +264,7 @@ echo $response;
 
 <Row>
   <Col>
-    Creates a new service user or sends an invite to a regular user
+    Creates a new service user or sends an invite to a regular user. When embedded IdP is enabled (`account.settings.extra.embedded_idp_enabled: true`), this endpoint creates a local user with a generated password that is returned in the response.
             
     ### Request-Body Parameters
     
@@ -295,6 +295,9 @@ echo $response;
         </Property>
     </Properties>
 
+    <Note>
+    **Embedded IdP Behavior:** When embedded IdP is enabled, the response includes a `password` field containing the generated password. This password is only returned once at creation time and cannot be retrieved later. Store it securely or share it with the user immediately. Users authenticated through external identity provider connectors will have an `idp_id` field linking them to the provider.
+    </Note>
     
        </Col>
 
@@ -532,6 +535,8 @@ echo $response;
   "is_service_user": false,
   "is_blocked": false,
   "issued": "api",
+  "password": "generated-password-here",
+  "idp_id": "idp-def456",
   "permissions": {
     "is_restricted": {
       "type": "boolean",
@@ -569,6 +574,8 @@ echo $response;
   "is_service_user": "boolean",
   "is_blocked": "boolean",
   "issued": "string",
+  "password": "string",
+  "idp_id": "string",
   "permissions": {
     "is_restricted": "boolean",
     "modules": {

src/pages/selfhosted/identity-providers/api-reference.mdx

@@ -0,0 +1,490 @@
+# Identity Provider API Reference
+
+This page documents the API endpoints for managing identity providers when using the [embedded IdP](/selfhosted/identity-providers/embedded-idp).
+
+## Base URL
+
+All endpoints are relative to your NetBird Management API:
+
+```
+https://netbird.example.com/api
+```
+
+## Authentication
+
+Most endpoints require authentication via Bearer token:
+
+```
+Authorization: Bearer <access_token>
+```
+
+## Permissions
+
+Identity provider management requires administrator privileges. The following permission is required:
+
+- `identity_providers` permission - For managing identity provider configurations
+- `settings:read` - For viewing the Identity Providers tab
+
+---
+
+## Instance Setup
+
+These endpoints handle the initial setup when embedded IdP is enabled and no accounts exist. Both endpoints are **unauthenticated** and only work before setup is complete.
+
+### Get Instance Status
+
+Check if the instance requires initial setup.
+
+```http
+GET /instance
+```
+
+**Authentication:** None required (public endpoint)
+
+**Response:**
+
+```json
+{
+  "setup_required": true
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `setup_required` | boolean | `true` if no accounts exist and setup is needed |
+
+### Complete Setup
+
+Create the initial owner account.
+
+```http
+POST /instance/setup
+```
+
+**Authentication:** None required (only available during setup)
+
+**Request Body:**
+
+```json
+{
+  "email": "admin@example.com",
+  "password": "securepassword123",
+  "name": "Admin User"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `email` | string | Yes | Email address for the owner account |
+| `password` | string | Yes | Password (minimum 8 characters) |
+| `name` | string | No | Display name |
+
+**Response:**
+
+```json
+{
+  "user_id": "user-abc123",
+  "account_id": "account-xyz789"
+}
+```
+
+**Errors:**
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | `invalid_request` | Missing required fields or invalid format |
+| 412 | `precondition_failed` | Setup already completed (redirects to login) |
+| 503 | `idp_unavailable` | Embedded IdP is not enabled |
+
+---
+
+## Identity Providers (Connectors)
+
+Manage external identity provider connectors. The Identity Providers tab is visible in Settings when `embedded_idp_enabled` is `true` in account settings.
+
+### List Identity Providers
+
+Get all configured identity providers.
+
+```http
+GET /identity-providers
+```
+
+**Response:**
+
+```json
+[
+  {
+    "id": "idp-abc123",
+    "type": "google",
+    "name": "Google Workspace",
+    "client_id": "123456789.apps.googleusercontent.com",
+    "issuer": "",
+    "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
+  },
+  {
+    "id": "idp-def456",
+    "type": "oidc",
+    "name": "Corporate SSO",
+    "client_id": "netbird-client",
+    "issuer": "https://sso.example.com",
+    "redirect_url": "https://netbird.example.com/api/idp/callback/idp-def456"
+  }
+]
+```
+
+<Note>
+Client secrets are never returned in API responses for security.
+</Note>
+
+### Get Identity Provider
+
+Get details for a specific identity provider.
+
+```http
+GET /identity-providers/{id}
+```
+
+**Path Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | string | Identity provider ID |
+
+**Response:**
+
+```json
+{
+  "id": "idp-abc123",
+  "type": "google",
+  "name": "Google Workspace",
+  "client_id": "123456789.apps.googleusercontent.com",
+  "issuer": "",
+  "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
+}
+```
+
+### Create Identity Provider
+
+Add a new identity provider connector.
+
+```http
+POST /identity-providers
+```
+
+**Request Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | Yes | Provider type (see below) |
+| `name` | string | Yes | Display name on login page |
+| `client_id` | string | Yes | OAuth client ID |
+| `client_secret` | string | Yes | OAuth client secret |
+| `issuer` | string | Conditional | Issuer URL (required for oidc, okta, zitadel, pocketid) |
+
+**Provider Types:**
+
+| Type | Description | Requires Issuer |
+|------|-------------|-----------------|
+| `google` | Google accounts / Google Workspace | No |
+| `microsoft` | Microsoft personal accounts | No |
+| `entra` | Microsoft Entra ID (Azure AD) | No |
+| `okta` | Okta SSO | Yes |
+| `zitadel` | Zitadel IdP | Yes |
+| `pocketid` | PocketID | Yes |
+| `oidc` | Generic OIDC provider | Yes |
+
+#### Google Configuration
+
+```json
+{
+  "type": "google",
+  "name": "Google Workspace",
+  "client_id": "123456789.apps.googleusercontent.com",
+  "client_secret": "GOCSPX-xxxxx"
+}
+```
+
+<Note>
+Google and Microsoft types do not require an `issuer` field - the issuer is determined automatically.
+</Note>
+
+#### Microsoft / Entra ID Configuration
+
+```json
+{
+  "type": "entra",
+  "name": "Microsoft Entra ID",
+  "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "client_secret": "xxxxx"
+}
+```
+
+Use `microsoft` for personal Microsoft accounts, or `entra` for Azure AD / work accounts.
+
+#### Okta Configuration
+
+```json
+{
+  "type": "okta",
+  "name": "Okta SSO",
+  "client_id": "0oaxxxxxxxxxx",
+  "client_secret": "xxxxx",
+  "issuer": "https://yourcompany.okta.com/oauth2/default"
+}
+```
+
+#### Zitadel Configuration
+
+```json
+{
+  "type": "zitadel",
+  "name": "Zitadel",
+  "client_id": "123456789",
+  "client_secret": "xxxxx",
+  "issuer": "https://zitadel.example.com"
+}
+```
+
+#### PocketID Configuration
+
+```json
+{
+  "type": "pocketid",
+  "name": "PocketID",
+  "client_id": "netbird",
+  "client_secret": "xxxxx",
+  "issuer": "https://pocketid.example.com"
+}
+```
+
+#### Generic OIDC Configuration
+
+```json
+{
+  "type": "oidc",
+  "name": "Custom SSO",
+  "client_id": "netbird-client",
+  "client_secret": "xxxxx",
+  "issuer": "https://sso.example.com"
+}
+```
+
+The issuer URL must have a valid `/.well-known/openid-configuration` endpoint.
+
+**Response:**
+
+On successful creation, the response includes a `redirect_url` that must be configured in your identity provider:
+
+```json
+{
+  "id": "idp-abc123",
+  "type": "google",
+  "name": "Google Workspace",
+  "client_id": "123456789.apps.googleusercontent.com",
+  "issuer": "",
+  "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
+}
+```
+
+<Note>
+**Important:** After creating an identity provider, you must configure the `redirect_url` in your IdP's OAuth application settings. The Dashboard shows a modal with copy functionality after successful creation.
+</Note>
+
+**Errors:**
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | `invalid_request` | Missing required fields |
+| 400 | `invalid_type` | Unknown provider type |
+| 403 | `permission_denied` | Insufficient permissions |
+
+### Update Identity Provider
+
+Update an existing identity provider.
+
+```http
+PUT /identity-providers/{id}
+```
+
+**Path Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | string | Identity provider ID |
+
+**Request Body:**
+
+Include only fields you want to update. The `type` cannot be changed.
+
+```json
+{
+  "name": "Updated Name",
+  "client_id": "new-client-id",
+  "client_secret": "new-secret"
+}
+```
+
+<Note>
+If `client_secret` is empty or omitted, the existing secret is preserved. The help text in the Dashboard says: "Leave empty to keep the existing secret."
+</Note>
+
+**Response:**
+
+```json
+{
+  "id": "idp-abc123",
+  "type": "google",
+  "name": "Updated Name",
+  "client_id": "new-client-id",
+  "issuer": "",
+  "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
+}
+```
+
+### Delete Identity Provider
+
+Remove an identity provider connector.
+
+```http
+DELETE /identity-providers/{id}
+```
+
+**Path Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | string | Identity provider ID |
+
+**Response:**
+
+```
+204 No Content
+```
+
+**Errors:**
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 404 | `not_found` | Identity provider not found |
+| 403 | `permission_denied` | Insufficient permissions |
+
+<Warning>
+Deleting an identity provider will prevent users who authenticate exclusively through that provider from logging in.
+</Warning>
+
+---
+
+## Users (Embedded IdP)
+
+When embedded IdP is enabled, the Dashboard shows a **"Create User"** button instead of "Invite User". Created users receive a generated password that is shown only once.
+
+### Create User
+
+Create a new local user. In the Dashboard, after creation, a modal displays the generated password with a copy button and the warning: *"This password will only be shown once. Please copy it now."*
+
+```http
+POST /users
+```
+
+**Request Body:**
+
+```json
+{
+  "email": "user@example.com",
+  "name": "New User",
+  "role": "user",
+  "auto_groups": ["group-id-1", "group-id-2"]
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `email` | string | Yes | User's email address |
+| `name` | string | Yes | Display name |
+| `role` | string | No | Role: `admin`, `user` (default: `user`) |
+| `auto_groups` | string[] | No | Groups to automatically assign |
+
+**Response:**
+
+```json
+{
+  "id": "user-abc123",
+  "email": "user@example.com",
+  "name": "New User",
+  "role": "user",
+  "status": "active",
+  "password": "generated-password-here"
+}
+```
+
+<Warning>
+The `password` field is only included in the response when creating a user with embedded IdP enabled. It is never returned in subsequent API calls. Store it securely or share it with the user immediately.
+</Warning>
+
+### User IdP Association
+
+When users authenticate through an external identity provider connector, their user record includes an `idp_id` field linking them to the provider. The Dashboard displays an IdP badge (with the provider's icon) next to the user's name in the Users table.
+
+```json
+{
+  "id": "user-abc123",
+  "email": "user@example.com",
+  "name": "User Name",
+  "role": "user",
+  "status": "active",
+  "idp_id": "idp-def456"
+}
+```
+
+<Note>
+This endpoint is only available when embedded IdP is enabled (`account.settings.extra.embedded_idp_enabled: true`). With external IdPs, users are provisioned through the IdP.
+</Note>
+
+---
+
+## Error Responses
+
+All error responses follow this format:
+
+```json
+{
+  "error": {
+    "code": "error_code",
+    "message": "Human-readable error message",
+    "details": {}
+  }
+}
+```
+
+### Common Error Codes
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| `invalid_request` | 400 | Request body is malformed or missing required fields |
+| `invalid_config` | 400 | Provider configuration is invalid |
+| `unauthorized` | 401 | Missing or invalid authentication token |
+| `permission_denied` | 403 | Insufficient permissions for this operation |
+| `not_found` | 404 | Requested resource not found |
+| `duplicate` | 409 | Resource already exists |
+| `idp_unavailable` | 503 | Embedded IdP is not enabled or unavailable |
+
+---
+
+## Rate Limits
+
+API requests are subject to rate limiting:
+
+| Endpoint Category | Rate Limit |
+|-------------------|------------|
+| Read operations | 100 requests/minute |
+| Write operations | 20 requests/minute |
+| Onboarding | 5 requests/minute |
+
+Rate limit headers are included in responses:
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1642089600
+```

src/pages/selfhosted/identity-providers/authentik.mdx

@@ -1,135 +1,192 @@
 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**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-provider-type.png" alt="Select provider type" className="imagewrapper-big"/>
+</p>
+
+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**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-application.png" alt="Create application" className="imagewrapper-big"/>
+</p>
+
+### 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 the embedded IdP. This approach gives you full control over identity management but requires more configuration.
 
 <Note>
-    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/auth0).
 </Note>
 
-## 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://<domain>/.*`
+  - Strict: `http://localhost:53000`
+- **Advanced protocol settings**:
+  - Access code validity: `minutes=10`
+  - Subject mode: `Based on the User's ID`
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-provider-type.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-provider-config.png" alt="Provider configuration" className="imagewrapper-big"/>
 </p>
 
-- 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://<domain>/.*`
-            - 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
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-provider-config.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
+### 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-application.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-service-account.png" alt="Create service account" className="imagewrapper-big"/>
 </p>
 
-## 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`
- 
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-service-account.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
+### 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
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-service-account-details.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-add-user-group.png" alt="Add user to group" className="imagewrapper-big"/>
 </p>
 
-## 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-add-user-group.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-device-flow.png" alt="Create device flow" className="imagewrapper-big"/>
 </p>
 
-#### 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-device-flow.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-brand-device-flow.png" alt="Configure brand device flow" className="imagewrapper-big"/>
 </p>
 
-- 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
 
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-brand-device-flow.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-
-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://<YOUR_AUTHENTIK_HOST_AND_PORT>/application/o/netbird/.well-known/openid-configuration
 ```
 
 <Note>
 Double-check if the endpoint returns a JSON response by calling it from your browser.
 </Note>
 
-- Set properties in the `setup.env` file:
+Set properties in the `setup.env` file:
+
 ```shell
 NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_AUTHENTIK_HOST_AND_PORT>/application/o/netbird/.well-known/openid-configuration"
 NETBIRD_USE_AUTH0=false
@@ -146,10 +203,38 @@ NETBIRD_IDP_MGMT_CLIENT_ID="<PROVIDER_CLIENT_ID>"
 NETBIRD_IDP_MGMT_EXTRA_USERNAME="Netbird"
 NETBIRD_IDP_MGMT_EXTRA_PASSWORD="<SERVICE_ACCOUNT_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).
+### 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://<domain>/.*`
+
+### 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/embedded-idp)
+- [API Reference](/selfhosted/identity-providers/api-reference)

src/pages/selfhosted/identity-providers/connectors.mdx

@@ -0,0 +1,121 @@
+# Identity Provider Connectors
+
+When using the [embedded IdP](/selfhosted/identity-providers/embedded-idp), you can add identity provider **connectors** to enable Single Sign-On (SSO). This allows users to sign in with their existing accounts from services like Google, Microsoft, or your corporate identity provider—while still maintaining the simplicity of the embedded IdP.
+
+## Why Use Connectors?
+
+Connectors provide:
+
+- **Single Sign-On (SSO)** - Users authenticate with familiar credentials
+- **Federation** - Multiple identity sources, single NetBird account
+- **Flexibility** - Mix local users with SSO authentication
+- **Gradual adoption** - Start with local users, add SSO later
+
+## Supported Providers
+
+| Provider | Type | Best For |
+|----------|------|----------|
+| [**Google**](/selfhosted/identity-providers/google) | `google` | Google Workspace, personal Google accounts |
+| [**Microsoft**](/selfhosted/identity-providers/microsoft) | `microsoft` / `entra` | Personal accounts, Azure AD / Entra ID |
+| [**Okta**](/selfhosted/identity-providers/okta) | `okta` | Enterprise SSO |
+| [**Zitadel**](/selfhosted/identity-providers/zitadel) | `zitadel` | Self-hosted Zitadel |
+| [**Keycloak**](/selfhosted/identity-providers/keycloak) | `oidc` | Self-hosted Keycloak |
+| [**Authentik**](/selfhosted/identity-providers/authentik) | `oidc` | Self-hosted Authentik |
+| [**PocketID**](/selfhosted/identity-providers/pocketid) | `pocketid` | Lightweight self-hosted IdP |
+| [**Generic OIDC**](/selfhosted/identity-providers/generic-oidc) | `oidc` | Any OIDC-compliant provider |
+
+## Adding a Connector
+
+### Via Dashboard
+
+1. Log in to your NetBird Dashboard
+2. Navigate to **Settings** → **Identity Providers**
+3. Click **Add Identity Provider**
+4. Select your provider type and fill in the required fields
+5. Click **Save**
+6. Copy the **Redirect URL** and configure it in your identity provider
+
+<Note>
+The Identity Providers tab is only visible when the embedded IdP is enabled.
+</Note>
+
+### Via API
+
+```bash
+curl -X POST "https://netbird.example.com/api/identity-providers" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "oidc",
+    "name": "My SSO Provider",
+    "client_id": "your-client-id",
+    "client_secret": "your-client-secret",
+    "issuer": "https://sso.example.com"
+  }'
+```
+
+See the [API Reference](/selfhosted/identity-providers/api-reference) for complete documentation.
+
+## Common Configuration Fields
+
+All connectors require:
+
+| Field | Description |
+|-------|-------------|
+| **Name** | Display name shown on the login button |
+| **Client ID** | OAuth client identifier from your provider |
+| **Client Secret** | OAuth client secret from your provider |
+
+Some providers also require:
+
+| Field | Required For | Description |
+|-------|--------------|-------------|
+| **Issuer** | Okta, Zitadel, PocketID, OIDC | The OIDC issuer URL |
+
+## How It Works
+
+1. User clicks the provider button on the login page
+2. User is redirected to the identity provider to authenticate
+3. After successful authentication, user is redirected back to NetBird
+4. NetBird validates the token and creates/updates the user account
+5. User is logged in and can access the Dashboard
+
+Users who authenticate via a connector appear in your Users list with a badge showing their identity provider.
+
+## Multiple Connectors
+
+You can configure multiple connectors simultaneously:
+
+- All enabled providers appear as buttons on the login page
+- "Continue with Email" (local authentication) is always available
+- Users can authenticate with any configured provider
+- Each user's provider is tracked and displayed in the Dashboard
+
+## Best Practices
+
+1. **Start simple** - Begin with local users, add connectors as needed
+2. **Test thoroughly** - Verify the connector works before announcing to users
+3. **Communicate changes** - Let users know about new login options
+4. **Keep a fallback** - Local authentication remains available if a connector has issues
+
+## Troubleshooting
+
+### Provider not appearing on login page
+
+- Verify the connector was saved successfully in Settings → Identity Providers
+- Check that the connector is enabled
+- Clear browser cache and reload the login page
+
+### "Invalid redirect URI" error
+
+- Copy the exact Redirect URL from NetBird after creating the connector
+- Ensure no trailing slashes or typos
+- Some providers are case-sensitive
+
+### Authentication succeeds but user not created
+
+- Check Management service logs for errors
+- Verify the token contains required claims (email, name)
+- Ensure the user's email domain is not blocked by any policies
+
+For provider-specific troubleshooting, see the individual provider pages.

src/pages/selfhosted/identity-providers/embedded-idp.mdx

@@ -0,0 +1,408 @@
+# Embedded Identity Provider
+
+The embedded identity provider is NetBird's built-in authentication system, powered by [Dex](https://dexidp.io/). It runs directly within the Management service, eliminating the need for external IdP containers or complex configuration.
+
+## Overview
+
+The embedded IdP provides:
+
+- **Local user management** - Create users with email/password authentication directly in NetBird
+- **External connector support** - Optionally integrate Google, GitHub, OIDC, or SAML providers
+- **Device authentication** - CLI authentication via device authorization flow
+- **Secure storage** - AES-256-GCM encryption for sensitive user data at rest
+
+## When to Use Embedded IdP
+
+The embedded IdP is ideal for:
+
+| Use Case | Why Embedded IdP Works |
+|----------|----------------------|
+| **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 an [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 in connectors
+
+## Architecture
+
+With the embedded IdP enabled, the architecture is simplified:
+
+```
+                     NetBird Management                      
+  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  
+  │   Management    │  │   Embedded Dex  │  │  Dashboard  │  
+  │     Service     │◄─┤   IdP Server    │◄─┤     API     │  
+  └─────────────────┘  └─────────────────┘  └─────────────┘  
+           │                    │                            
+           ▼                    ▼                            
+  ┌─────────────────────────────────────────────────────────┐
+  │              SQLite/Postgres Database                   │
+  │         (Users, Accounts, IdP Connectors)               │
+  └─────────────────────────────────────────────────────────┘
+```
+
+Compare this to the external IdP architecture which requires separate containers for the IdP and its database.
+
+## Configuration
+
+### Enabling Embedded IdP
+
+The embedded IdP is enabled by default when using the new `getting-started.sh` quickstart script. For manual configuration, update your `management.json`:
+
+```json
+{
+  "EmbeddedIdP": {
+    "Enabled": true,
+    "DataDir": "/var/lib/netbird/idp"
+  },
+  "EncryptionKey": "<auto-generated-base64-key>"
+}
+```
+
+### Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `EmbeddedIdP.Enabled` | Enable/disable the embedded IdP | `true` (quickstart) |
+| `EmbeddedIdP.DataDir` | Directory for IdP data storage | `/var/lib/netbird/idp` |
+| `EncryptionKey` | Base64-encoded AES-256 key for encrypting user data | Auto-generated |
+
+### Environment Variables
+
+When using docker-compose, you can configure these via environment variables:
+
+```yaml
+environment:
+  - NETBIRD_EMBEDDED_IDP_ENABLED=true
+  - NETBIRD_EMBEDDED_IDP_DATA_DIR=/var/lib/netbird/idp
+  - NETBIRD_ENCRYPTION_KEY=${ENCRYPTION_KEY}
+```
+
+### Generating an Encryption Key
+
+If you need to generate an encryption key manually:
+
+```bash
+openssl rand -base64 32
+```
+
+<Note>
+**Warning:** Store your encryption key securely. If lost, encrypted user data (emails, names) cannot be recovered. Include it in your backup procedures.
+</Note>
+
+## User Management
+
+### Creating Users via Dashboard
+
+When embedded IdP is enabled, the Dashboard shows a **"Create User"** button (instead of "Invite User" shown for cloud-hosted NetBird):
+
+1. Navigate to **Team** → **Users**
+2. Click **Create User**
+3. Fill in the user details:
+   - **Email** (required) - User's email address for login
+   - **Name** (required) - Display name
+   - **Groups** (optional) - Auto-assign to groups
+4. Click **Create**
+
+After creation, a modal displays with:
+- The **generated password** with a copy button
+- Warning: *"This password will only be shown once. Please copy it now."*
+- **Copy & Close** button to copy password and dismiss
+
+<Note>
+**Warning:** The generated password is only shown once at creation time. It cannot be retrieved later. Make sure to copy it and share it securely with the user.
+</Note>
+
+### User IdP Badges
+
+In the Users table, each user shows a badge indicating their identity provider:
+- Users created locally show no badge (or "Local" badge)
+- Users who authenticated via an external connector show that provider's icon (Google, Microsoft, etc.)
+- The badge links to the `idp_id` field in the user record
+
+### Creating Users via API
+
+```bash
+curl -X POST "https://netbird.example.com/api/users" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "name": "New User",
+    "auto_groups": ["group-id-1"]
+  }'
+```
+
+Response includes the generated password:
+
+```json
+{
+  "id": "user-abc123",
+  "email": "user@example.com",
+  "name": "New User",
+  "role": "user",
+  "status": "active",
+  "password": "generated-password-here"
+}
+```
+
+<Note>
+The `password` field is only included when creating users with embedded IdP. Store it immediately—it won't be returned in subsequent API calls.
+</Note>
+
+### User Roles
+
+Users created through the embedded IdP can be assigned roles:
+
+| Role | Permissions |
+|------|-------------|
+| **Owner** | Full administrative access, cannot be demoted |
+| **Admin** | Manage users, peers, policies, and settings |
+| **User** | Connect devices, view assigned resources |
+
+## Instance Setup (First Run)
+
+When NetBird starts with the embedded IdP and no existing accounts, the Dashboard redirects to the `/setup` route and displays the **Instance Setup Wizard**:
+
+1. The Dashboard checks `GET /instance` for `setup_required: true`
+2. If setup is required, users are redirected to `/setup`
+3. The wizard collects:
+   - **Email address** (required)
+   - **Password** (required, minimum 8 characters)
+   - **Name** (optional)
+4. On submit, the owner account is created via `POST /instance/setup`
+5. User is redirected to login with the credentials they just created
+
+<Note>
+The `/setup` route is unauthenticated and only accessible when `setup_required` is true. Once setup is complete, accessing `/setup` returns a 412 error and redirects to login.
+</Note>
+
+### Setup API
+
+For automated deployments, you can complete setup via API:
+
+```bash
+# Check if setup is required
+curl "https://netbird.example.com/api/instance"
+
+# Response when setup is needed:
+{
+  "setup_required": true
+}
+
+# Complete setup
+curl -X POST "https://netbird.example.com/api/instance/setup" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "admin@example.com",
+    "password": "securepassword123",
+    "name": "Admin User"
+  }'
+
+# Response:
+{
+  "user_id": "user-abc123",
+  "account_id": "account-xyz789"
+}
+```
+
+## Adding Identity Provider Connectors
+
+The embedded IdP supports adding identity provider [**connectors**](/selfhosted/identity-providers/connectors) to enable SSO. This allows users to sign in with existing accounts from:
+
+- Google
+- Microsoft (personal accounts)
+- Microsoft Entra ID (Azure AD / work accounts)
+- Okta
+- Zitadel
+- PocketID
+- Any OIDC-compliant provider
+
+### Managing Connectors via Dashboard
+
+1. Navigate to **Settings** → **Identity Providers**
+2. Click **Add Identity Provider**
+3. Select your provider type from the dropdown
+4. Configure the required fields:
+   - **Name** - Display name for the login button
+   - **Client ID** - From your identity provider
+   - **Client Secret** - From your identity provider
+   - **Issuer** - Required for Okta, Zitadel, PocketID, and generic OIDC
+5. Click **Save**
+
+After saving, a modal displays the **Redirect URL** that you must configure in your identity provider's OAuth settings. Copy this URL before closing.
+
+<Note>
+The Identity Providers tab is only visible when `embedded_idp_enabled` is `true` in your account settings.
+</Note>
+
+For detailed setup instructions for each provider, see the individual provider pages:
+- [Google](/selfhosted/identity-providers/google)
+- [Microsoft](/selfhosted/identity-providers/microsoft)
+- [Keycloak](/selfhosted/identity-providers/keycloak)
+- [Zitadel](/selfhosted/identity-providers/zitadel)
+- [All Providers →](/selfhosted/identity-providers)
+
+### Managing Connectors via API
+
+```bash
+# List configured connectors
+curl "https://netbird.example.com/api/identity-providers" \
+  -H "Authorization: Bearer ${TOKEN}"
+
+# Add a Google connector
+curl -X POST "https://netbird.example.com/api/identity-providers" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "google",
+    "name": "Google Workspace",
+    "client_id": "your-client-id.apps.googleusercontent.com",
+    "client_secret": "your-client-secret"
+  }'
+
+# Response includes redirect_url to configure in Google:
+{
+  "id": "idp-abc123",
+  "type": "google",
+  "name": "Google Workspace",
+  "client_id": "your-client-id.apps.googleusercontent.com",
+  "issuer": "",
+  "redirect_url": "https://netbird.example.com/api/idp/callback/idp-abc123"
+}
+
+# Update a connector
+curl -X PUT "https://netbird.example.com/api/identity-providers/{id}" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Updated Name"
+  }'
+
+# Delete a connector
+curl -X DELETE "https://netbird.example.com/api/identity-providers/{id}" \
+  -H "Authorization: Bearer ${TOKEN}"
+```
+
+## Login Flow
+
+When embedded IdP is enabled with external connectors, the login page displays:
+
+1. **"Continue with Email"** - Local username/password authentication (always shown first)
+2. **External provider buttons** - One for each configured connector
+
+Users can choose their preferred authentication method.
+
+## 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
+
+## 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
+
+### External connector not working
+
+1. Verify Client ID and Secret are correct
+2. Check redirect URIs are properly configured in the external IdP
+3. Review Management logs for OIDC/SAML errors
+
+### Password reset
+
+Use the management CLI:
+
+```bash
+docker compose exec management /go/bin/netbird-mgmt users reset-password \
+  --email user@example.com \
+  --new-password "newpassword123"
+```
+
+## Security Considerations
+
+### Password Requirements
+
+Default password requirements for local users:
+
+- Minimum 8 characters
+- No specific complexity requirements (consider your security policy)
+
+### Session Management
+
+- JWT tokens are issued upon successful authentication
+- Token expiration follows OIDC best practices
+- Device authorization flow available for CLI clients
+
+### Audit Logging
+
+User authentication events are logged in the activity log:
+
+- Login attempts (successful and failed)
+- User creation/deletion
+- Connector configuration changes
+- Password resets
+
+## Comparison with External IdP
+
+| Feature | Embedded IdP | External IdP |
+|---------|--------------|--------------|
+| Setup complexity | Minimal | Moderate to High |
+| Resource requirements | Low (~1GB RAM) | Higher (2-4GB+ RAM) |
+| Additional containers | None | IdP + Database |
+| User management | Dashboard/API | External IdP console |
+| External SSO | Via connectors | Native |
+| SCIM provisioning | Not available | Available (Enterprise) |
+| MFA | Via external connectors | Native IdP feature |
+| Backup complexity | Single database | Multiple databases |
+
+## Disabling Embedded IdP
+
+To switch from embedded IdP to an external IdP:
+
+1. Configure your external IdP following the [Advanced guide](/selfhosted/selfhosted-guide)
+2. Update `management.json`:
+
+   ```json
+   {
+     "EmbeddedIdP": {
+       "Enabled": false
+     },
+     "HttpConfig": {
+       "OIDCConfigEndpoint": "https://your-idp.example.com/.well-known/openid-configuration"
+     }
+   }
+   ```
+
+3. Restart the Management service
+4. Users will need to re-authenticate with the new IdP
+
+<Note>
+**Warning:** Disabling the embedded IdP will invalidate all local user accounts. Ensure users have accounts in the external IdP before switching.
+</Note>

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

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

src/pages/selfhosted/identity-providers/keycloak.mdx

@@ -1,265 +1,322 @@
 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
 
 <Note>
-    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.
 </Note>
 
-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 the embedded IdP. This approach gives you full control but requires more configuration.
+
+<Note>
+If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like [Auth0](/selfhosted/identity-providers/auth0).
+</Note>
+
+### 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.
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-auth-grant.gif" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-auth-grant.gif" alt="Keycloak auth flow" className="imagewrapper-big"/>
 </p>
 
-## 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-realm.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-realm.png" alt="Create realm" className="imagewrapper-big"/>
 </p>
 
+### 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-user.png" alt="high-level-dia" className="imagewrapper"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-user.png" alt="Create user" className="imagewrapper"/>
 </p>
 
-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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-set-password.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-set-password.png" alt="Set password" className="imagewrapper-big"/>
 </p>
 
-## 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-client.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-client.png" alt="Create client" className="imagewrapper-big"/>
 </p>
 
-
-- Check the checkboxes as on the screenshot below and click Save
+4. Enable the authentication options as shown:
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-enable-auth.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-enable-auth.png" alt="Enable auth" className="imagewrapper-big"/>
 </p>
 
-## 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-access-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-access-settings.png" alt="Access settings" className="imagewrapper-big"/>
 </p>
 
-## 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-client-scope.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-client-scope.png" alt="Create client scope" className="imagewrapper-big"/>
 </p>
 
-- 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
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-configure-audience-mapper.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-configure-audience-mapper.png" alt="Configure audience mapper" className="imagewrapper-big"/>
 </p>
 
-- 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-configure-audience-mapper-2.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-configure-audience-mapper-2.png" alt="Audience mapper config" className="imagewrapper-big"/>
 </p>
 
-## 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`
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-add-client-scope.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-add-client-scope.png" alt="Add client scope" className="imagewrapper-big"/>
 </p>
 
-## 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-backend-client.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-create-backend-client.png" alt="Create backend client" className="imagewrapper-big"/>
 </p>
 
-- Check the checkboxes as on the screenshot below and click Save
+4. Enable authentication as shown:
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-backend-client-auth.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-backend-client-auth.png" alt="Backend client auth" className="imagewrapper-big"/>
 </p>
 
-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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-backend-client-credentials.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-backend-client-credentials.png" alt="Backend client credentials" className="imagewrapper-big"/>
 </p>
 
-## 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`
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-service-account-role.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-service-account-role.png" alt="Service account role" className="imagewrapper-big"/>
 </p>
 
-- Check the role checkbox and click assign
+5. Check the role checkbox and click **Assign**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-add-role.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/keycloak-add-role.png" alt="Add role" className="imagewrapper-big"/>
 </p>
 
 <Note>
-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.
 </Note>
 
-Your authority OIDC configuration will be available under:
+### Step 10: Configure NetBird
+
+Your authority OIDC configuration will be available at:
+
 ```bash
 https://<YOUR_KEYCLOAK_HOST_AND_PORT>/realms/netbird/.well-known/openid-configuration
 ```
+
 <Note>
-    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.
 </Note>
 
-- Set properties in the `setup.env` file:
-```shell
-NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=`https://<YOUR_KEYCLOAK_HOST_AND_PORT>/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://<YOUR_KEYCLOAK_HOST_AND_PORT>/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_BACKEND_CLIENT_SECRET>"
 NETBIRD_IDP_MGMT_EXTRA_ADMIN_ENDPOINT="https://<YOUR_KEYCLOAK_HOST_AND_PORT>/admin/realms/netbird"
-
 ```
+
 <Note>
-    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.
 </Note>
 
-#### 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).
+### 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/embedded-idp)
+- [API Reference](/selfhosted/identity-providers/api-reference)

src/pages/selfhosted/identity-providers/managed/auth0.mdx

@@ -1,22 +1,83 @@
 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 the embedded IdP.
 
 <Note>
-    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).
 </Note>
 
-## 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 +88,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)`
 <Note>
-    Make sure that **`Token Endpoint Authentication Method`** is set to **`None`**.
+Ensure **Token Endpoint Authentication Method** is set to **None**.
 </Note>
 
-- 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://<DOMAIN>/.well-known/openid-configuration
+https://<DOMAIN>/.well-known/openid-configuration
 ```
+
 <Note>
-    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.
 </Note>
 
-#### 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-create-interactive-login-app.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-create-interactive-login-app.png" alt="Create interactive login app" className="imagewrapper-big"/>
 </p>
 
-- 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`
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-interactive-login-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-interactive-login-settings.png" alt="Interactive login settings" className="imagewrapper-big"/>
 </p>
 
-- 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-grant-types.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-grant-types.png" alt="Grant types" className="imagewrapper-big"/>
 </p>
 
-## 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-create-machine-app.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-create-machine-app.png" alt="Create machine app" className="imagewrapper-big"/>
 </p>
 
-- 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-machine-authorization.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-machine-authorization.png" alt="Machine authorization" className="imagewrapper-big"/>
 </p>
 
 <Note>
-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.
 </Note>
 
-- 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://<DOMAIN>/api/v2/`)
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-machine-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-machine-settings.png" alt="Machine settings" className="imagewrapper-big"/>
 </p>
 
-- 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://<DOMAIN>/.well-known/openid-configuration"
 NETBIRD_USE_AUTH0=true
-NETBIRD_AUTH_CLIENT_ID="<Client_ID>"
+NETBIRD_AUTH_CLIENT_ID="<CLIENT_ID>"
 NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api email_verified"
 NETBIRD_AUTH_AUDIENCE="<IDENTIFIER>"
 NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<INTERACTIVE_CLIENT_ID>"
@@ -146,6 +205,39 @@ NETBIRD_IDP_MGMT_CLIENT_SECRET="<NETBIRD_API_CLIENT_SECRET>"
 NETBIRD_IDP_MGMT_EXTRA_AUDIENCE="https://<DOMAIN>/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).
+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/embedded-idp)

src/pages/selfhosted/identity-providers/managed/google-workspace.mdx

@@ -1,127 +1,237 @@
 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 |
 
 <Note>
-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.
 </Note>
 
-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
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-type.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
+### Step 3: Configure Redirect URI
 
-- Fill in the form with the following values and click `SAVE AND CONTINUE`
-    - App name: `Netbird`
-    - User support email: `<administrator email address>`
-    - Authorized domain: `<your netbird domain>`
-    - Developer contact information: `<developer email address>`
-- Click `ADD OR REMOVE SCOPES`
-- Select `/auth/userinfo.email`, `/auth/userinfo.profile` and `openid` scopes and then click `UPDATE`
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-scopes.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- 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`
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-summary.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
+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://<your netbird domain>` and `http://localhost`
-    - Authorized redirect URIs: `https://<your netbird domain>/auth`, `https://<your netbird domain>/silent-auth` and `http://localhost:53000`
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-oauth-client.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- Take note of `Client ID` and `Client Secret` and click `OK`
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-oauth-client-created.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
+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`
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-service-account-create.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
+### 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
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-edit-service-account.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- 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
 
 <Note>
-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.
 </Note>
 
-- 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 the embedded IdP. This enables full user management integration with Google Workspace.
+
+<Note>
+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.
+</Note>
+
+### 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`
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-new-role-info.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-type.png" alt="Consent screen type" className="imagewrapper-big"/>
 </p>
 
-- 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**: `<administrator email>`
+   - **Authorized domain**: `<your netbird domain>`
+   - **Developer contact information**: `<developer email>`
+4. Click **SAVE AND CONTINUE**
+5. Click **ADD OR REMOVE SCOPES**
+6. Select `/auth/userinfo.email`, `/auth/userinfo.profile`, and `openid`
+7. Click **UPDATE**
+
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-privileges-review.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- 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`
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-assign-role.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- Click `ASSIGN ROLE` to assign service account to `User Management ReadOnly` role
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-service-account-privileges.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-scopes.png" alt="Consent screen scopes" className="imagewrapper-big"/>
 </p>
 
-- 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 <SERVICE_ACCOUNT_KEY_PATH>
-    ```
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-summary.png" alt="Consent screen summary" className="imagewrapper-big"/>
+</p>
 
-- 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://<your domain>` and `http://localhost`
+   - **Authorized redirect URIs**: 
+     - `https://<your domain>/auth`
+     - `https://<your domain>/silent-auth`
+     - `http://localhost:53000`
+4. Click **CREATE**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-oauth-client.png" alt="OAuth client" className="imagewrapper-big"/>
+</p>
+
+5. Note **Client ID** and **Client Secret**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-oauth-client-created.png" alt="OAuth client created" className="imagewrapper-big"/>
+</p>
+
+### 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**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-service-account-create.png" alt="Create service account" className="imagewrapper-big"/>
+</p>
+
+### 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
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-edit-service-account.png" alt="Edit service account" className="imagewrapper-big"/>
+</p>
+
+3. Click the **Keys** tab
+4. Click **Add key** → **Create new key**
+5. Select **JSON** and click **Create**
+
+<Note>
+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).
+</Note>
+
+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**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-new-role-info.png" alt="New role info" className="imagewrapper-big"/>
+</p>
+
+6. Scroll to **Admin API privileges** and add:
+   - **Users**: `Read`
+7. Click **CONTINUE**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-privileges-review.png" alt="Privileges review" className="imagewrapper-big"/>
+</p>
+
+8. Click **CREATE ROLE**
+9. Click **Assign service accounts**
+10. Add the service account email address
+11. Click **ADD** then **ASSIGN ROLE**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-assign-role.png" alt="Assign role" className="imagewrapper-big"/>
+</p>
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-service-account-privileges.png" alt="Service account privileges" className="imagewrapper-big"/>
+</p>
+
+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 <SERVICE_ACCOUNT_KEY_PATH>
+```
+
+### Step 7: Configure NetBird
+
+Set properties in the `setup.env` file:
+
+```shell
 NETBIRD_DOMAIN="<YOUR_DOMAIN>"
 NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://accounts.google.com/.well-known/openid-configuration"
 NETBIRD_USE_AUTH0=false
@@ -141,5 +251,42 @@ NETBIRD_IDP_MGMT_EXTRA_SERVICE_ACCOUNT_KEY="<BASE64_SERVICE_ACCOUNT_KEY>"
 NETBIRD_IDP_MGMT_EXTRA_CUSTOMER_ID="<GOOGLE_WORKSPACE_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).
+### 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/embedded-idp)

src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx

@@ -1,105 +1,202 @@
 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`
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- On the `Which application would you like to integrate` screen, confirm that you've selected `Custom application` and click `Next`
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-confirm-selection.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- 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`
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-features.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- On the `Enter General info` screen, add `NetBird` as `Display Label` and click `Next`
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-general-info.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- On the confirmation screen, review the information and click on `Configure Application` to proceed
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-confirmation.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- On the `New Application` screen, click on the SSO tab and enter the following values:
-    - Under `Endpoint Configuration` section:
-      - Redirect URIs: `https://<domain>/silent-auth`, `https://<domain>/auth` and `http://localhost:53000`
-      - Client Authentication Type: `Public (None PKCE)`
-      - Login URL: `https://<domain>`
+- 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 the embedded IdP.
+
+### 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-sso-configuration.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app.png" alt="New SSO app" className="imagewrapper-big"/>
 </p>
-    - Under `Attribute Mapping (optional)` section:
-        - Standard Scopes: `Email`, `Profile`
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-sso-atributes-configuration.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- Click on the `User Groups` tab and select the user groups that can access this application
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-user-groups.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- Click `Activate`
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-oidc-app.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- 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**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-confirm-selection.png" alt="Confirm selection" className="imagewrapper-big"/>
+</p>
+
+5. Select **Manage Single Sign-On (SSO)** and check **Configure SSO with OIDC**
+6. Click **Next**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-features.png" alt="SSO features" className="imagewrapper-big"/>
+</p>
+
+7. Enter **Display Label**: `NetBird`
+8. Click **Next**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-general-info.png" alt="General info" className="imagewrapper-big"/>
+</p>
+
+9. Review and click **Configure Application**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app-confirmation.png" alt="Confirmation" className="imagewrapper-big"/>
+</p>
+
+10. On the **SSO** tab, configure:
+    - **Redirect URIs**: 
+      - `https://<domain>/silent-auth`
+      - `https://<domain>/auth`
+      - `http://localhost:53000`
+    - **Client Authentication Type**: `Public (None PKCE)`
+    - **Login URL**: `https://<domain>`
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-sso-configuration.png" alt="SSO configuration" className="imagewrapper-big"/>
+</p>
+
+11. Under **Attribute Mapping (optional)**:
+    - **Standard Scopes**: `Email`, `Profile`
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-sso-atributes-configuration.png" alt="Attribute configuration" className="imagewrapper-big"/>
+</p>
+
+12. Click **User Groups** tab and select groups that can access the application
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-user-groups.png" alt="User groups" className="imagewrapper-big"/>
+</p>
+
+13. Click **Activate**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-oidc-app.png" alt="OIDC app" className="imagewrapper-big"/>
+</p>
+
+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@<yourdomain>` # this email will be used to receive the login instructions
-    - Role: `Read Only`
-    - Click `Save`
 <Note>
-    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.
 </Note>
+
+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@<yourdomain>`
+   - **Role**: `Read Only`
+4. Click **Save**
+
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-add-admin-user.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-add-admin-user.png" alt="Add admin user" className="imagewrapper-big"/>
 </p>
 
-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.
+<Note>
+**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.
+</Note>
 
-## 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
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-profile.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
-- If there is no API key generated, click on `Generate New API Key` button
-- Take note of your api token displayed 
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-api-key-generation.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-profile.png" alt="Profile" className="imagewrapper-big"/>
 </p>
 
-- Set properties in the `setup.env` file:
-```json
+3. If no key exists, click **Generate New API Key**
+4. Copy the API token
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-api-key-generation.png" alt="API key generation" className="imagewrapper-big"/>
+</p>
+
+### Step 4: Configure NetBird
+
+Set properties in the `setup.env` file:
+
+```shell
 NETBIRD_DOMAIN="<YOUR_DOMAIN>"
 NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://oauth.id.jumpcloud.com/.well-known/openid-configuration"
 NETBIRD_USE_AUTH0=false
@@ -117,5 +214,39 @@ NETBIRD_MGMT_IDP="jumpcloud"
 NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="<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/embedded-idp)

src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx

@@ -1,133 +1,222 @@
 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 the embedded IdP.
 
 <Note>
-    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).
 </Note>
 
-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://<yournetbirddomain.com>/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://<yournetbirddomain.com>/silent-auth`
+4. Click **Register**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-new-application.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-new-application.png" alt="New application" className="imagewrapper-big"/>
 </p>
 
-#### Step 2. Platform configurations
-- Click `Authentication` on the left side menu
-- Under the `Single-page application` Section, add another URI `https://<yournetbirddomain.com>/auth`
+### Step 2: Configure Platform Settings
+
+1. Click **Authentication** on the left menu
+2. Under **Single-page application**, add another URI: `https://<yournetbirddomain.com>/auth`
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-spa-uri-setup.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-spa-uri-setup.png" alt="SPA URI setup" className="imagewrapper-big"/>
 </p>
 
-- Scroll down and setup other options as on the screenshot below and click Save
+3. Scroll down and configure options as shown:
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-flows-setup.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-flows-setup.png" alt="Flows setup" className="imagewrapper-big"/>
 </p>
 
-- 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`
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-spa-uri-setup.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
+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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-add-scope.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-add-scope.png" alt="Add scope" className="imagewrapper-big"/>
 </p>
 
-- 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-add-application-scope.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-add-application-scope.png" alt="Add application scope" className="imagewrapper-big"/>
 </p>
 
+### 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-netbird-api-permisssions.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-netbird-api-permisssions.png" alt="NetBird API permissions" className="imagewrapper-big"/>
 </p>
 
-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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-openid-permissions.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-openid-permissions.png" alt="OpenID permissions" className="imagewrapper-big"/>
 </p>
 
-
-- Click `Grant admin consent for Default Directory` and click `Yes`
+8. Click **Grant admin consent for Default Directory** → **Yes**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-grant-admin-conset.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-grant-admin-conset.png" alt="Grant admin consent" className="imagewrapper-big"/>
 </p>
 
-## 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
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-client-secret.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-client-secret.png" alt="Client secret" className="imagewrapper-big"/>
 </p>
 
-- 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/<Directory (tenant) ID>/v2.0/.well-known/openid-configuration
 ```
+
 <Note>
-    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.
 </Note>
 
-- Set properties in the `setup.env` file:
+Set properties in the `setup.env` file:
+
 ```shell
 NETBIRD_DOMAIN="<YOUR_DOMAIN>"
 NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0/.well-known/openid-configuration"
@@ -147,8 +236,43 @@ NETBIRD_IDP_MGMT_CLIENT_ID="<Application (client) ID>"
 NETBIRD_IDP_MGMT_CLIENT_SECRET="<CLIENT_SECRET>"
 NETBIRD_IDP_MGMT_EXTRA_OBJECT_ID="<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).
+### 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/embedded-idp)

src/pages/selfhosted/identity-providers/managed/okta.mdx

@@ -1,115 +1,183 @@
 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 the embedded IdP.
 
 <Note>
-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).
 </Note>
 
-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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-new-single-page-application.png" alt="high-level-dia" className="imagewrapper"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-new-single-page-application.png" alt="New SPA application" className="imagewrapper"/>
 </p>
 
-- 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://<yournetbirddomain.com>/auth`, `https://<yournetbirddomain.com>/silent-auth` and `http://localhost:53000`
-    - Sign-out redirect URIs: `https://<yournetbirddomain.com>/`
-- Click `Save`
+6. Fill in:
+   - **App integration name**: `Netbird`
+   - **Grant type**: `Authorization Code` and `Refresh Token`
+   - **Sign-in redirect URIs**: 
+     - `https://<yournetbirddomain.com>/auth`
+     - `https://<yournetbirddomain.com>/silent-auth`
+     - `http://localhost:53000`
+   - **Sign-out redirect URIs**: `https://<yournetbirddomain.com>/`
+7. Click **Save**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-single-page-application.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-single-page-application.png" alt="SPA application config" className="imagewrapper-big"/>
 </p>
 
-- 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-single-sign-on-configuration.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-single-sign-on-configuration.png" alt="Sign-on configuration" className="imagewrapper-big"/>
 </p>
 
-## 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-new-native-application.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-new-native-application.png" alt="New native application" className="imagewrapper-big"/>
 </p>
 
-- 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-native-application.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-native-application.png" alt="Native application config" className="imagewrapper-big"/>
 </p>
 
-- 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-native-sign-on-configuration.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-native-sign-on-configuration.png" alt="Native sign-on configuration" className="imagewrapper-big"/>
 </p>
 
+### 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-generate-token.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-generate-token.png" alt="Generate token" className="imagewrapper-big"/>
 </p>
 
+### Step 4: Configure NetBird
+
+Your authority OIDC configuration will be available at:
 
-Your authority OIDC configuration will be available under:
 ```bash
 https://<YOUR_OKTA_ORGANIZATION_URL>/.well-known/openid-configuration
 ```
+
 <Note>
-    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.
 </Note>
 
-- Set properties in the `setup.env` file:
-```json
+Set properties in the `setup.env` file:
+
+```shell
 NETBIRD_DOMAIN="<YOUR_DOMAIN>"
 NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_OKTA_ORGANIZATION_URL>/.well-known/openid-configuration"
 NETBIRD_USE_AUTH0=false
-NETBIRD_AUTH_AUDIENCE="<<NETBIRD_CLIENT_ID>>"
+NETBIRD_AUTH_AUDIENCE="<NETBIRD_CLIENT_ID>"
 NETBIRD_AUTH_CLIENT_ID="<NETBIRD_CLIENT_ID>"
 NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email"
 NETBIRD_AUTH_REDIRECT_URI="/auth"
@@ -117,13 +185,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_NATIVE_CLIENT_ID>>"
+NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<NETBIRD_NATIVE_CLIENT_ID>"
 NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="<NETBIRD_NATIVE_CLIENT_ID>"
 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="<api_token>"
+NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="<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).
+
+### 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/embedded-idp)

src/pages/selfhosted/identity-providers/pocketid.mdx

@@ -1,72 +1,132 @@
 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.
 
 <Note>
-    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.
 </Note>
 
-## 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://<domain>`
-- Callback URL's:
-- `http://localhost:53000`
-- `https://<domain>/auth`
-- `https://<domain>/silent-auth`
-- Logout Callback URL: `https://<domain>/`
-- 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 the embedded IdP.
+
+### 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://<domain>`
+   - **Callback URLs**:
+     - `http://localhost:53000`
+     - `https://<domain>/auth`
+     - `https://<domain>/silent-auth`
+   - **Logout Callback URL**: `https://<domain>/`
+   - **Public Client**: On
+   - **PKCE**: On
+4. Click **Save**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/pocketid-create-oidc-client.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/pocketid-create-oidc-client.png" alt="Create OIDC client" className="imagewrapper-big"/>
 </p>
 
-- 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**
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/pocketid-create-api-token.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/pocketid/pocketid-create-api-token.png" alt="Create API token" className="imagewrapper-big"/>
 </p>
 
-- 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://<YOUR_POCKETID_HOST_AND_PORT>/.well-known/openid-configuration
 ```
 
-:::caution
+<Note>
 Double-check if the endpoint returns a JSON response by calling it from your browser.
-:::
+</Note>
 
-- Set properties in the `setup.env` file:
-```json
+Set properties in the `setup.env` file:
+
+```shell
 NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_POCKETID_HOST_AND_PORT>/.well-known/openid-configuration"
 NETBIRD_USE_AUTH0=false
 NETBIRD_AUTH_CLIENT_ID="<CLIENT_ID>"
@@ -86,8 +146,35 @@ NETBIRD_MGMT_IDP="pocketid"
 NETBIRD_IDP_MGMT_CLIENT_ID="netbird"
 NETBIRD_IDP_MGMT_EXTRA_MANAGEMENT_ENDPOINT="https://<YOUR_POCKETID_HOST_AND_PORT>"
 NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="<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).
+### 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/embedded-idp)
+- [API Reference](/selfhosted/identity-providers/api-reference)

src/pages/selfhosted/identity-providers/zitadel.mdx

@@ -1,153 +1,213 @@
 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.
 
 <Note>
-    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.
 </Note>
 
-## 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.
 
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-project.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
+### 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)
 
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
+### 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**
 
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application-auth.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
+### Step 2: Add Connector in NetBird
 
-- Fill in the form with the following values and click `Continue`
-- Redirect URIs: `https://<domain>/auth` and click `+`
-- Redirect URIs: `https://<domain>/silent-auth` and click `+`
-- Redirect URIs: `http://localhost:53000` and click `+`
-- Post Logout URIs: `https://<domain>/` 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:
 
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application-uri.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
+| 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**
 
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application-overview.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
+### 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
 
-<p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-token-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
-</p>
+---
 
-## Step 3: Application Redirect Configuration
+## Standalone Setup (Advanced)
+
+Use Zitadel as your primary identity provider instead of the embedded IdP. This was the default approach in previous NetBird versions.
 
 <Note>
-    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/).
 </Note>
 
-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`
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-redirect-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-project.png" alt="New project" className="imagewrapper-big"/>
 </p>
 
-## 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`
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-create-user.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application.png" alt="New application" className="imagewrapper-big"/>
 </p>
 
-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`
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-service-user-secret.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application-auth.png" alt="Application auth" className="imagewrapper-big"/>
 </p>
 
-## 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://<domain>/auth`
+     - `https://<domain>/silent-auth`
+     - `http://localhost:53000`
+   - **Post Logout URIs**: `https://<domain>/`
 
 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-service-account-role.png" alt="high-level-dia" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application-uri.png" alt="Application URIs" className="imagewrapper-big"/>
 </p>
 
-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**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-new-application-overview.png" alt="Application overview" className="imagewrapper-big"/>
+</p>
+
+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**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-token-settings.png" alt="Token settings" className="imagewrapper-big"/>
+</p>
+
+### Step 3: Configure Redirect Settings (Development Only)
+
+<Note>
+This step is only for development mode without SSL.
+</Note>
+
+1. Click **Redirect Settings** in the left menu
+2. Toggle **Development Mode**
+3. Click **Save**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-redirect-settings.png" alt="Redirect settings" className="imagewrapper-big"/>
+</p>
+
+### 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**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-create-user.png" alt="Create service user" className="imagewrapper-big"/>
+</p>
+
+6. Click **Actions** in the top right corner
+7. Click **Generate Client Secret**
+8. Copy **ClientSecret** for later use
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-service-user-secret.png" alt="Service user secret" className="imagewrapper-big"/>
+</p>
+
+### 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**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/zitadel-service-account-role.png" alt="Service account role" className="imagewrapper-big"/>
+</p>
+
+### Step 6: Configure NetBird
+
+Your authority OIDC configuration will be available at:
 
 ```bash
 https://<YOUR_ZITADEL_HOST_AND_PORT>/.well-known/openid-configuration
 ```
 
-:::caution
+<Note>
 Double-check if the endpoint returns a JSON response by calling it from your browser.
-:::
+</Note>
 
-- Set properties in the `setup.env` file:
-```json
+Set properties in the `setup.env` file:
+
+```shell
 NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_ZITADEL_HOST_AND_PORT>/.well-known/openid-configuration"
 NETBIRD_USE_AUTH0=false
 NETBIRD_AUTH_CLIENT_ID="<CLIENT_ID>"
@@ -165,9 +225,63 @@ NETBIRD_IDP_MGMT_CLIENT_ID="netbird"
 NETBIRD_IDP_MGMT_CLIENT_SECRET="<CLIENT_SECRET>"
 NETBIRD_IDP_MGMT_EXTRA_MANAGEMENT_ENDPOINT="https://<YOUR_ZITADEL_HOST_AND_PORT>/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).
+### 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/embedded-idp)
+- [Migration Guide](/selfhosted/identity-providers/migration)

src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx

@@ -18,6 +18,18 @@ 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: Simplified Self-Hosting
+
+Starting with version X.XX, self-hosting NetBird has become significantly easier with the introduction of the **embedded identity provider**. Previously, self-hosting required setting up and maintaining a separate identity provider (like Zitadel, Keycloak, or Auth0). Now, NetBird includes a built-in IdP powered by [Dex](https://dexidp.io/), which means:
+
+- **Fewer containers** to deploy and maintain (4-5 vs 7+ previously)
+- **Lower resource requirements** (~1GB RAM vs 2-4GB previously)
+- **No external IdP configuration** required
+- **User management directly in the Dashboard**
+- **Optional SSO connectors** if you want to integrate with Google, Microsoft, Okta, etc.
+
+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 +37,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 the new embedded IdP, this burden is reduced—you no longer need to maintain a 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 +55,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.
 
+<Note>
+SCIM provisioning and some enterprise features require a [Commercial License](https://netbird.io/pricing#on-prem) for self-hosted deployments.
+</Note>
+
 ## 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 +74,26 @@ 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 embedded IdP | Instant |
+| **Infrastructure** | You manage | We manage |
+| **Identity provider** | Built-in (or bring your own) | Managed |
+| **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
 <p float="center" >
     <Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
 </p>
 
+- [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

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).
 
 <Note>
-    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.
 </Note>
 
-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.
+<Note>
+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)
+</Note>
+
+## 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/microsoft) - Azure AD / Microsoft 365
+- [Google Workspace](/selfhosted/identity-providers/google) - Google accounts
+- [Okta](/selfhosted/identity-providers/okta) - Enterprise SSO
+- [Auth0](/selfhosted/identity-providers/auth0) - Flexible auth platform
+- [JumpCloud](/selfhosted/identity-providers/jumpcloud) - Cloud directory
+
+<Note>
+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.
+</Note>
 
 ### 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) 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)

src/pages/selfhosted/selfhosted-quickstart.mdx

@@ -3,22 +3,22 @@
 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).
+a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn), and a built-in identity provider.
 
 If you would like to learn more about the architecture please refer to the [Architecture section](/about-netbird/how-netbird-works).
 
 <Note>
-    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)
+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)
 </Note>
 
-## 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 with embedded IdP
+
+Starting with version X.XX, NetBird includes a **built-in identity provider** powered by [Dex](https://dexidp.io/). This eliminates the need for external IdP setup and is the recommended approach for new deployments.
 
 <Note>
-    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 with custom IdPs, see the [Advanced guide](/selfhosted/selfhosted-guide).
 </Note>
 
 ### Requirements
@@ -30,42 +30,72 @@ 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-with-zitadel.sh
+curl -sSLO https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh
 # check the script
-cat getting-started-with-zitadel.sh
+cat getting-started.sh
 # run the script
 export NETBIRD_DOMAIN=netbird.example.com
-bash getting-started-with-zitadel.sh
+bash getting-started.sh
 ```
 <Note>
-    Replace `netbird.example.com` with your domain name.
+Replace `netbird.example.com` with your domain name.
+</Note>
+
+### Initial setup
+
+Once the script completes, open your browser and navigate to `https://netbird.example.com/setup`. You'll be prompted to create your first admin user:
+
+1. Enter your email address
+2. Set a secure password
+3. Click **Create Account**
+
+This creates the owner account for your NetBird instance. You can now log in to the Dashboard.
+
+<Note>
+The `/setup` page is only accessible once. After creating the first user, it will redirect to the login page.
 </Note>
-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).
+
+You can add users directly from the NetBird Dashboard:
+
+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.
+
+### Add SSO (Optional)
+
+Want users to sign in with Google, Microsoft, or your corporate IdP? You can add SSO connectors directly from the Dashboard:
+
+1. Navigate to **Settings** → **Identity Providers**
+2. Click **Add Identity Provider**
+3. Select your provider (Google, Microsoft, Okta, etc.)
+4. Follow the provider-specific setup instructions
+
+For detailed setup guides, see [Identity Provider Connectors](/selfhosted/identity-providers/connectors).
 
 ### Backup
-To backup your NetBird installation, you need to copy the configuration files, the Management service databases, and Zitadel's database.
+
+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 zitadel.env dashboard.env turnserver.conf management.json relay.env zdb.env 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
@@ -73,7 +103,6 @@ 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
 <Note>
@@ -110,15 +139,91 @@ To remove the NetBird installation and all related data from your server, run th
 # remove all NetBird-related containers and volumes (data)
 docker compose down --volumes
 # remove downloaded and generated config files
-rm -f docker-compose.yml Caddyfile zitadel.env dashboard.env machinekey/zitadel-admin-sa.token turnserver.conf management.json
+rm -f docker-compose.yml Caddyfile dashboard.env turnserver.conf management.json relay.env
 ```
 
 ### Troubleshoot
 
-- I'm trying to register a user but I didn't receive a verification code. What's the problem?
+- **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.
 
-    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.
+- **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: Quick self-hosting with Zitadel IdP
+
+<Note>
+This section is for users who prefer to use Zitadel as a standalone IdP instead of the embedded IdP. For new installations, we recommend the [embedded IdP approach](#quick-self-hosting-with-embedded-idp) above.
+</Note>
+
+If you want to deploy NetBird with [Zitadel](https://zitadel.com/) as the identity provider, you can use the legacy quickstart script:
+
+### 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
+# run the script
+export NETBIRD_DOMAIN=netbird.example.com
+bash getting-started-with-zitadel.sh
+```
+
+Once the script execution is complete, you can access your NetBird instance via `https://netbird.example.com` using the credentials displayed in your terminal.
+
+### 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.
+
+```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:
+```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.
+
+### Remove (Zitadel)
+```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 zitadel.env dashboard.env machinekey/zitadel-admin-sa.token turnserver.conf management.json
+```
+
+### Migrating from Zitadel to Embedded IdP
+
+If you have an existing Zitadel deployment and want to migrate to the embedded IdP:
+
+1. **Option A**: Keep Zitadel as a connector—add it as an SSO provider in the embedded IdP
+2. **Option B**: Recreate users in the embedded IdP and decommission Zitadel
+
+See the [Migration Guide](/selfhosted/identity-providers/migration) for detailed steps.
+
+---
 
 ## Get in touch
 
@@ -126,4 +231,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)

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:
 </p>
 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