Updating Self-Hosted Managed Idp Guides (#538)

2026-04-16 15:36:36 +00:00 · 2026-01-08 20:05:28 -08:00
parent b0d218484a
commit 027d9f077a
84 changed files with 390 additions and 139 deletions
--- a/src/components/NavigationDocs.jsx
+++ b/src/components/NavigationDocs.jsx
@@ -303,11 +303,11 @@ export const docsNavigation = [
                        title: 'Managed IdPs',
                        isOpen: true,
                        links: [
-                            { title: 'Entra ID', href: '/selfhosted/identity-providers/managed/microsoft-entra-id' },
-                            { title: 'Okta', href: '/selfhosted/identity-providers/managed/okta' },
                            { title: 'Google Workspace', href: '/selfhosted/identity-providers/managed/google-workspace' },
+                            { title: 'Microsoft Entra ID', href: '/selfhosted/identity-providers/managed/microsoft-entra-id' },
                            { title: 'JumpCloud', href: '/selfhosted/identity-providers/managed/jumpcloud' },
-                            { title: 'Keycloak', href: '/selfhosted/identity-providers/managed/keycloak' },
+                            { title: 'Auth0', href: '/selfhosted/identity-providers/managed/auth0' },
+                            { title: 'Okta', href: '/selfhosted/identity-providers/managed/okta' },
                        ]
                    },
                ]
--- a/src/pages/selfhosted/identity-providers/index.mdx
+++ b/src/pages/selfhosted/identity-providers/index.mdx
@@ -37,7 +37,7 @@ NetBird supports any OIDC-compliant identity providers. Here are some popular pr

 | Provider | Type | Best For |
 |----------|------|----------|
-| [**Generic OIDC**](#adding-external-identity-providers) | `oidc` | Any OIDC-compliant provider |
+| [**Generic OIDC**](#adding-an-identity-provider) | `oidc` | Any OIDC-compliant provider |
 | [**Google**](/selfhosted/identity-providers/managed/google-workspace) | `google` | Google Workspace, personal Google accounts |
 | [**Microsoft**](/selfhosted/identity-providers/managed/microsoft-entra-id) | `microsoft` / `entra` | Personal accounts, Azure AD / Entra ID |
 | [**Okta**](/selfhosted/identity-providers/managed/okta) | `okta` | Enterprise SSO |
@@ -51,7 +51,7 @@ NetBird supports any OIDC-compliant identity providers. Here are some popular pr
    use the generic OIDC configuration.
 </Note>

-    ### Adding an Identity Provider
+### Adding an Identity Provider

 #### Via Dashboard

--- a/src/pages/selfhosted/identity-providers/managed/auth0.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/auth0.mdx
@@ -1,6 +1,6 @@
 import {Note} from "@/components/mdx";

-# Auth0
+# Auth0 SSO with NetBird Self-Hosted

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

@@ -13,22 +13,29 @@ Add Auth0 as an external IdP directly in the NetBird Management Dashboard. This
 - NetBird self-hosted with embedded IdP enabled
 - Auth0 account (sign up at https://auth0.com/)

-### Step 1: Create Application in Auth0
+### Step 1: Start Creating Application in Auth0

 1. Log in to your Auth0 dashboard at https://manage.auth0.com/
 2. Go to **Applications** → **Applications**
 3. Click **Create Application**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/1_create-app-auth0.png" alt="Create application" className="imagewrapper-big"/>
+</p>
+
 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 Identity Provider in NetBird
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/2_create-web-app-auth0.png" alt="Create web application" className="imagewrapper-big"/>
+</p>

-1. Log in to your NetBird Dashboard
+5. Click Create
+
+### Step 2: Get Redirect URL from NetBird
+
+1. Open a new tab or window and log in to your NetBird Dashboard
 2. Navigate to **Settings** → **Identity Providers**
 3. Click **Add Identity Provider**
 4. Fill in the fields:
@@ -37,23 +44,42 @@ Add Auth0 as an external IdP directly in the NetBird Management Dashboard. This
 |-------|-------|
 | 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` |
+| Client ID | From Auth0 application (will fill after Step 3) |
+| Client Secret | From Auth0 application (will fill after Step 3) |
+| Issuer | `https://your-tenant.auth0.com/` **(must include trailing slash)** (will fill after Step 3) |

-5. Don't click **Add Provider** yet, copy your Redirect URL for the next step.
+5. **Copy the Redirect URL** that NetBird displays (but don't click **Add Provider** yet)

-### Step 3: Configure Redirect URI
+### Step 3: Complete Auth0 Application Setup

-NetBird displays the **Redirect URL**. Copy this URL and add it to your Auth0 application:
-
-1. Return to Auth0 Dashboard → **Applications** → **NetBird**
+1. Return to the Auth0 tab
 2. Go to **Settings** tab
-3. Under **Allowed Callback URLs**, add the redirect URL from NetBird
+3. Under **Allowed Callback URLs**, add the redirect URL you copied from NetBird
 4. Click **Save Changes**
-5. Click **Add Provider** in NetBird

-### Step 4: Test the Connection
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/3_add-save-callback-url-auth0.png" alt="Add and save callback URL" className="imagewrapper-big"/>
+</p>
+
+5. Note the **Client ID**, **Client Secret**, and **Domain** (e.g., `your-tenant.auth0.com`) at the top of the setting tab — you'll need these for Step 4
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/4_copy-client-secret-ids-auth0.png" alt="Copy client secret and IDs" className="imagewrapper-big"/>
+</p>
+
+### Step 4: Complete NetBird Setup
+
+1. Return to the NetBird tab
+2. Fill in the **Client ID** and **Client Secret** from Step 3
+3. Update the **Issuer** field with your Auth0 domain if needed (e.g., `https://your-tenant.auth0.com/`)
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/5_netbird-idp-config-auth0.png" alt="NetBird IdP configuration" className="imagewrapper-big"/>
+</p>
+
+4. Click **Add Provider**
+
+### Step 5: Test the Connection

 1. Log out of NetBird Dashboard
 2. On the login page, you should see an "Auth0" button
@@ -134,14 +160,14 @@ This enables machine authorization via your Identity Provider as an alternative
 4. Click **Create**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-create-interactive-login-app.png" alt="Create interactive login app" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/advanced/auth0-create-interactive-login-app.png" alt="Create interactive login app" className="imagewrapper-big"/>
 </p>

 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="Interactive login settings" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/advanced/auth0-interactive-login-settings.png" alt="Interactive login settings" className="imagewrapper-big"/>
 </p>

 7. Scroll to **Advanced Settings**
@@ -149,7 +175,7 @@ This enables machine authorization via your Identity Provider as an alternative
 9. Click **Save Changes**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-grant-types.png" alt="Grant types" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/advanced/auth0-grant-types.png" alt="Grant types" className="imagewrapper-big"/>
 </p>

 ### Step 4: Create Machine to Machine Application
@@ -164,7 +190,7 @@ This application authorizes access to Auth0 Management API.
 4. Click **Create**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-create-machine-app.png" alt="Create machine app" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/advanced/auth0-create-machine-app.png" alt="Create machine app" className="imagewrapper-big"/>
 </p>

 5. Configure:
@@ -173,7 +199,7 @@ This application authorizes access to Auth0 Management API.
 6. Click **Authorize**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/auth0-machine-authorization.png" alt="Machine authorization" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/advanced/auth0-machine-authorization.png" alt="Machine authorization" className="imagewrapper-big"/>
 </p>

 <Note>
@@ -187,7 +213,7 @@ This application authorizes access to Auth0 Management API.
   - **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="Machine settings" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/auth0/advanced/auth0-machine-settings.png" alt="Machine settings" className="imagewrapper-big"/>
 </p>

 ### Step 5: Configure NetBird
--- a/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/google-workspace.mdx
@@ -1,6 +1,6 @@
 import {Note} from "@/components/mdx";

-# Google Workspace
+# Google Workspace SSO with NetBird Self-Hosted

 Use Google accounts for authentication with NetBird. This supports both personal Google accounts and Google Workspace (formerly G Suite) organizations.

@@ -13,12 +13,17 @@ Add Google as an external IdP directly in the NetBird Management Dashboard. This
 - NetBird self-hosted with embedded IdP enabled
 - Access to [Google Cloud Console](https://console.cloud.google.com/)

-### Step 1: Create OAuth Credentials
+### Step 1: Start Creating 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**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/1_0auth-client-id-google.png" alt="OAuth client ID" className="imagewrapper-big"/>
+</p>
+
 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)
@@ -27,13 +32,13 @@ Add Google as an external IdP directly in the NetBird Management Dashboard. This
 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**
+   - Leave redirect URIs empty for now (you'll add this in Step 3)

-### Step 2: Add Identity Provider in NetBird
+7. **Don't click Create yet** — keep this tab open and proceed to Step 2

-1. Log in to your NetBird Dashboard
+### Step 2: Get Redirect URL from NetBird
+
+1. Open a new tab or window and log in to your NetBird Dashboard
 2. Navigate to **Settings** → **Identity Providers**
 3. Click **Add Identity Provider**
 4. Fill in the fields:
@@ -42,22 +47,44 @@ Add Google as an external IdP directly in the NetBird Management Dashboard. This
 |-------|-------|
 | Type | Google |
 | Name | Google (or your preferred display name) |
-| Client ID | From Google Cloud Console |
-| Client Secret | From Google Cloud Console |
+| Client ID | From Google Cloud Console (will fill after Step 3) |
+| Client Secret | From Google Cloud Console (will fill after Step 3) |

-5. Don't click **Add Provider** yet, copy your Redirect URL for the next step.
+5. **Copy the Redirect URL** that NetBird displays (but don't click **Add Provider** yet)

-### Step 3: Configure Redirect URI
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/2_copy-redirect-google.png" alt="Copy redirect URL" className="imagewrapper-big"/>
+</p>

-NetBird displays the **Redirect URL**. Copy this URL and add it to your Google OAuth client:
+### Step 3: Complete Google OAuth Client Setup

-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 **Add Provider**
+1. Return to the Google Cloud Console tab
+2. Under **Authorized redirect URIs**, click **Add URI**
+3. Paste the redirect URL you copied from NetBird

-### Step 4: Test the Connection
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/3_paste-uri-google.png" alt="Paste URI" className="imagewrapper-big"/>
+</p>
+
+4. Click **Create**
+5. Note the **Client ID** and **Client Secret** — you'll need these for Step 4
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/4_0auth-client-created-google.png" alt="OAuth client created" className="imagewrapper-big"/>
+</p>
+
+### Step 4: Complete NetBird Setup
+
+1. Return to the NetBird tab
+2. Fill in the **Client ID** and **Client Secret** from Step 3
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/5_netbird-complete-google.png" alt="NetBird complete configuration" className="imagewrapper-big"/>
+</p>
+
+3. Click **Add Provider**
+
+### Step 5: Test the Connection

 1. Log out of NetBird Dashboard
 2. On the login page, you should see a "Google" button
@@ -101,7 +128,7 @@ Beginning with NetBird version v0.23.6 and onwards, the Google Workspace IdP man
 2. 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="Consent screen type" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/advanced/google-consent-screen-type.png" alt="Consent screen type" className="imagewrapper-big"/>
 </p>

 3. Fill in the form:
@@ -115,14 +142,14 @@ Beginning with NetBird version v0.23.6 and onwards, the Google Workspace IdP man
 7. Click **UPDATE**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-scopes.png" alt="Consent screen scopes" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/advanced/google-consent-screen-scopes.png" alt="Consent screen scopes" className="imagewrapper-big"/>
 </p>

 8. Click **SAVE AND CONTINUE**
 9. Review the summary and click **BACK TO DASHBOARD**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/google-consent-screen-summary.png" alt="Consent screen summary" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/advanced/google-consent-screen-summary.png" alt="Consent screen summary" className="imagewrapper-big"/>
 </p>

 ### Step 2: Create OAuth 2.0 Credentials
@@ -140,13 +167,13 @@ Beginning with NetBird version v0.23.6 and onwards, the Google Workspace IdP man
 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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/advanced/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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/advanced/google-oauth-client-created.png" alt="OAuth client created" className="imagewrapper-big"/>
 </p>

 ### Step 3: Create Service Account
@@ -160,7 +187,7 @@ Beginning with NetBird version v0.23.6 and onwards, the Google Workspace IdP man
 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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/advanced/google-service-account-create.png" alt="Create service account" className="imagewrapper-big"/>
 </p>

 ### Step 4: Create Service Account Keys
@@ -169,7 +196,7 @@ Beginning with NetBird version v0.23.6 and onwards, the Google Workspace IdP man
 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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/advanced/google-edit-service-account.png" alt="Edit service account" className="imagewrapper-big"/>
 </p>

 3. Click the **Keys** tab
@@ -193,7 +220,7 @@ The key file downloads automatically. Store it securely. Read about [managing se
 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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/advanced/google-new-role-info.png" alt="New role info" className="imagewrapper-big"/>
 </p>

 6. Scroll to **Admin API privileges** and add:
@@ -201,7 +228,7 @@ The key file downloads automatically. Store it securely. Read about [managing se
 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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/advanced/google-privileges-review.png" alt="Privileges review" className="imagewrapper-big"/>
 </p>

 8. Click **CREATE ROLE**
@@ -210,11 +237,11 @@ The key file downloads automatically. Store it securely. Read about [managing se
 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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/advanced/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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/google-workspace/advanced/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**
--- a/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/jumpcloud.mdx
@@ -1,6 +1,6 @@
 import {Note} from "@/components/mdx";

-# JumpCloud
+# JumpCloud SSO with NetBird Self-Hosted

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

@@ -13,26 +13,49 @@ Add JumpCloud as an external IdP directly in the NetBird Management Dashboard. T
 - NetBird self-hosted with embedded IdP enabled
 - JumpCloud account with admin permissions

-### Step 1: Create OIDC Application in JumpCloud
+### Step 1: Start Creating OIDC Application in JumpCloud

 1. Navigate to [JumpCloud Admin Portal](https://console.jumpcloud.com/)
 2. Click **SSO Applications** under **USER AUTHENTICATION**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/1_sso-applications.png" alt="SSO Applications" className="imagewrapper-big"/>
+</p>
+
 3. Click **Add New Application** → **Custom Application**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/2_custom-applications.png" alt="Custom Applications" className="imagewrapper-big"/>
+</p>
 4. Confirm **Custom application** and click **Next**
 5. Select **Manage Single Sign-On (SSO)** and check **Configure SSO with OIDC**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/3_SSO-with-OIDC.png" alt="SSO with OIDC" className="imagewrapper-big"/>
+</p>
+
 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**
+    - **Redirect URIs**: `https://<your-netbird-domain>/oauth2/callback` (you'll verify this matches exactly in Step 3)
+    - **Client Authentication Type**: `Client Secret POST`
+    - **Login URL**: `https://<your-netbird-domain>/` 
+11. Under **Attribute Mapping**, enable:
+    - **Email** scope
+    - **Profile** scope
+12. Click **Save** to save the SSO configuration
+13. Click the **User Groups** tab and select at least one user group that can access NetBird
+14. **Don't click Activate yet** — keep this tab open and proceed to Step 2

-### Step 2: Add Identity Provider in NetBird
+<Note>
+Sometimes, the JumpCloud application configuration will add duplicate attributes, like `email` and `email_verified`. Remove any duplicates if they appear.
+</Note>

-1. Log in to your NetBird Dashboard
+### Step 2: Get Redirect URL from NetBird
+
+1. Open a new tab or window and log in to your NetBird Dashboard
 2. Navigate to **Settings** → **Identity Providers**
 3. Click **Add Identity Provider**
 4. Fill in the fields:
@@ -41,27 +64,48 @@ Add JumpCloud as an external IdP directly in the NetBird Management Dashboard. T
 |-------|-------|
 | Type | Generic OIDC |
 | Name | JumpCloud (or your preferred display name) |
-| Client ID | From JumpCloud |
-| Client Secret | From JumpCloud |
-| Issuer | `https://oauth.id.jumpcloud.com` |
+| Client ID | From JumpCloud application (will fill after Step 3) |
+| Client Secret | From JumpCloud application (will fill after Step 3) |
+| Issuer | `https://oauth.id.jumpcloud.com/` **(must include trailing slash)** |

-5. Don't click **Add Provider** yet, copy your Redirect URL for the next step.
+<Note>
+**Important:** The Issuer must be exactly `https://oauth.id.jumpcloud.com/` (with trailing slash) to match what JumpCloud returns. If you enter it without the trailing slash, the connector will fail to initialize. See the ["Issuer did not match" troubleshooting section](#issuer-did-not-match-or-unauthenticated-error) for how to fix this if you encounter this error.
+</Note>

-### Step 3: Configure Redirect URI
+5. **Copy the Redirect URL** that NetBird displays (but don't click **Add Provider** yet)

-NetBird displays the **Redirect URL**. Copy this URL and add it to your JumpCloud application:
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/4_copy-redirect.png" alt="Copy redirect URL" className="imagewrapper-big"/>
+</p>

-1. Return to JumpCloud Admin → **SSO Applications** → **NetBird**
+### Step 3: Complete JumpCloud Application Setup
+
+1. Return to the JumpCloud tab
 2. Click the **SSO** tab
-3. Under **Redirect URIs**, add the redirect URL from NetBird
-4. Click **Save**
-5. Click **Add Provider** in NetBird
+3. Under **Redirect URIs**, verify the redirect URL matches the exact URL you copied from NetBird (e.g., `https://netbird.hopkins.sh/oauth2/callback`). If it doesn't match exactly, update it to match.
+4. Click **Save** (if you made any changes)

-### Step 4: Assign User Groups
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/5_config-jumpcloud-sso.png" alt="Configure JumpCloud SSO" className="imagewrapper-big"/>
+</p>

-1. Click the **User Groups** tab
-2. Select the user groups that can access NetBird
-3. Click **Save**
+5. Click **Activate**
+6. Note the **Client ID** and **Client Secret** — you'll need these for Step 4
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/6_client-ids.png" alt="Client IDs" className="imagewrapper-big"/>
+</p>
+
+### Step 4: Complete NetBird Setup
+
+1. Return to the NetBird tab
+2. Fill in the **Client ID** and **Client Secret** from Step 3
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/7_jumpcloud-config.png" alt="JumpCloud configuration" className="imagewrapper-big"/>
+</p>
+
+3. Click **Add Provider**

 ### Step 5: Test the Connection

@@ -90,33 +134,33 @@ For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) i
 3. Click **Add New Application** → **Custom Application**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-new-sso-app.png" alt="New SSO app" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/advanced/jumpcloud-new-sso-app.png" alt="New SSO app" className="imagewrapper-big"/>
 </p>

 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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/advanced/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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/advanced/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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/advanced/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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/advanced/jumpcloud-new-sso-app-confirmation.png" alt="Confirmation" className="imagewrapper-big"/>
 </p>

 10. On the **SSO** tab, configure:
@@ -128,26 +172,26 @@ For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) i
    - **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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/advanced/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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/advanced/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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/advanced/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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/advanced/jumpcloud-oidc-app.png" alt="OIDC app" className="imagewrapper-big"/>
 </p>

 14. Note the **Client ID**
@@ -170,7 +214,7 @@ If you already have an integration user, confirm it has the required role and sk
 4. Click **Save**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-add-admin-user.png" alt="Add admin user" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/advanced/jumpcloud-add-admin-user.png" alt="Add admin user" className="imagewrapper-big"/>
 </p>

 <Note>
@@ -185,14 +229,14 @@ If you already have an integration user, confirm it has the required role and sk
 2. Click the account initials (top-right) → **My API Key**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jumpcloud-profile.png" alt="Profile" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/advanced/jumpcloud-profile.png" alt="Profile" className="imagewrapper-big"/>
 </p>

 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"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/advanced/jumpcloud-api-key-generation.png" alt="API key generation" className="imagewrapper-big"/>
 </p>

 ### Step 4: Configure NetBird
@@ -225,6 +269,86 @@ You've configured all required resources in JumpCloud. Continue with the [NetBir

 ## Troubleshooting

+### "Issuer did not match" or "Unauthenticated" error
+
+If you see an error like:
+
+```
+FATL ... oidc: issuer did not match the issuer returned by provider, expected "https://oauth.id.jumpcloud.com" got "https://oauth.id.jumpcloud.com/"
+```
+
+This means there's a trailing slash mismatch in the Issuer URL. OIDC validation is strictly character-for-character.
+
+**The Cause:**
+- **Configured in NetBird:** `https://oauth.id.jumpcloud.com` (missing trailing slash)
+- **Returned by JumpCloud:** `https://oauth.id.jumpcloud.com/` (has trailing slash)
+
+Because the service fails to initialize the IDP manager, the Management container will often crash or restart loop, making it impossible to fix this via the Web UI.
+
+**Resolution:**
+
+If you can still access NetBird Dashboard:
+1. Navigate to **Settings** → **Identity Providers**
+2. Edit the JumpCloud identity provider
+3. Change the **Issuer** field to exactly `https://oauth.id.jumpcloud.com/` (with trailing slash)
+4. Click **Save**
+5. Restart the management container: `docker restart netbird-management`
+
+If you cannot access the dashboard (locked out), you must fix it directly in the SQLite database:
+
+1. **Locate the Volume:**
+   ```bash
+   docker volume inspect root_netbird_management
+   # Look for "Mountpoint", e.g., /var/lib/docker/volumes/root_netbird_management/_data
+   ```
+
+2. **Access the Database:**
+   ```bash
+   cd /var/lib/docker/volumes/root_netbird_management/_data
+   
+   # Backup the database first!
+   cp idp.db idp.db.bak
+   
+   # Open the database
+   sqlite3 idp.db
+   ```
+
+3. **Update the Issuer URL:**
+   Inside the SQLite prompt, run the following:
+   ```sql
+   -- Check current config to confirm missing slash
+   SELECT config FROM connector;
+   
+   -- Update the config to add trailing slash to match JumpCloud
+   UPDATE connector 
+   SET config = replace(config, 'jumpcloud.com"', 'jumpcloud.com/"') 
+   WHERE config LIKE '%jumpcloud.com"%';
+   
+   -- Verify the change
+   SELECT config FROM connector;
+   
+   -- Exit
+   .quit
+   ```
+
+4. **Restart Service:**
+   ```bash
+   docker restart netbird-management
+   ```
+
+The service should now start successfully, and the error should be resolved.
+
+
+### "Connector failed to initialize" error
+
+- Ensure **Attribute Mapping** has both **Email** and **Profile** scopes enabled
+- Verify at least one **User Group** is assigned to the application before activation
+- Check that **Redirect URIs** exactly matches the URL from NetBird (no trailing slashes)
+- Ensure **Client Authentication Type** is set to `Client Secret POST`
+- Verify **Login URL** matches your NetBird domain exactly
+- Make sure the application is **Activated** and you have the correct **Client ID** and **Client Secret**
+- Remove any duplicate attributes in **Attribute Mapping** (e.g., `email` and `email_verified`)
+
 ### "Invalid redirect URI" error

 - Ensure all redirect URIs are configured in JumpCloud
--- a/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/microsoft-entra-id.mdx
@@ -1,6 +1,6 @@
 import {Note} from "@/components/mdx";

-# Microsoft Entra ID
+# Microsoft and Entra ID SSO with NetBird Self-Hosted

 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.

@@ -18,10 +18,15 @@ Add Microsoft as an external IdP directly in the NetBird Management Dashboard. C
 - NetBird self-hosted with embedded IdP enabled
 - Access the [Entra Admin Center](https://entra.microsoft.com/)

-### Step 1: Create App Registration
+### Step 1: Start Creating App Registration

 1. Navigate to [Entra Admin Center](https://entra.microsoft.com/))
 2. Click **App registrations** → **New registration**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/1_new-registration-microsoft-entra.png" alt="New registration" className="imagewrapper-big"/>
+</p>
+
 3. Fill in:
   - **Name**: `NetBird`
   - **Supported account types**: Choose based on your needs:
@@ -29,21 +34,13 @@ Add Microsoft as an external IdP directly in the NetBird Management Dashboard. C
     - *Multi-tenant (any Entra ID organization)*: `Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)`
     - *Multi-tenant with personal accounts*: `Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)`
     - *Personal accounts only*: `Personal Microsoft accounts only`
-   - **Redirect URI**: Leave empty for now
-4. Click **Register**
-5. Note the **Application (client) ID** and **Directory (tenant) ID**
+   - **Redirect URI**: Leave empty for now (you'll add this in Step 4)

-### Step 2: Create Client Secret
+4. **Don't click Register yet** — keep this tab open and proceed to Step 2

-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 2: Get Redirect URL from NetBird

-### Step 3: Add Identity Provider in NetBird
-
-1. Log in to your NetBird Dashboard
+1. Open a new tab or window and log in to your NetBird Dashboard
 2. Navigate to **Settings** → **Identity Providers**
 3. Click **Add Identity Provider**
 4. Fill in the fields:
@@ -54,8 +51,8 @@ Add Microsoft as an external IdP directly in the NetBird Management Dashboard. C
 |-------|-------|
 | Type | Microsoft |
 | Name | Microsoft (or your preferred display name) |
-| Client ID | Application (client) ID from Azure |
-| Client Secret | Secret value from Azure |
+| Client ID | From Azure app registration (will fill after Step 3) |
+| Client Secret | From Azure app registration (will fill after Step 5) |

 **For Microsoft Entra ID (Work/School):**

@@ -63,28 +60,72 @@ Add Microsoft as an external IdP directly in the NetBird Management Dashboard. C
 |-------|-------|
 | 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 |
+| Issuer URL | From Azure app registration (will fill after Step 3) |
+| Client ID | From Azure app registration (will fill after Step 3) |
+| Client Secret | From Azure app registration (will fill after Step 5) |

 <Note>
-Microsoft doesn't require an Issuer URL—it's determined automatically.
+**Issuer URL format:** `https://login.microsoftonline.com/{tenant-id}/v2.0` where `{tenant-id}` is your Directory (tenant) ID from Azure.
 </Note>

-5. Don't click **Add Provider** yet, copy your Redirect URL for the next step.
+5. **Copy the Redirect URL** that NetBird displays (but don't click **Add Provider** yet)
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/2_copy-url-redirect-microsoft-entra.png" alt="Copy URL redirect" className="imagewrapper-big"/>
+</p>
+
+### Step 3: Complete App Registration
+
+1. Return to the Entra Admin Center tab
+2. Click **Register**
+3. Note the **Application (client) ID** and **Directory (tenant) ID** — you'll need these for Step 6
+4. Construct the **Issuer URL** using the format: `https://login.microsoftonline.com/{tenant-id}/v2.0` (replace `{tenant-id}` with your Directory (tenant) ID)

 ### Step 4: Configure Redirect URI

-NetBird displays the **Redirect URL**. Copy this URL and add it to your Azure app:
+1. Still in the Entra Admin Center tab, go to **Authentication**
+2. Click **Add a platform** → **Web**
+3. In the dropdown next to the redirect URI field, select **Web**
+4. Paste the redirect URL you copied from NetBird in the **Redirect URI** field
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/3_select-web-paste-uri-microsoft-entra.png" alt="Select web and paste URI" className="imagewrapper-big"/>
+</p>

-1. Return to Azure Portal → Your app registration
-2. Go to **Authentication**
-3. Click **Add a platform** → **Web application**
-4. Add the redirect URL from NetBird
 5. Click **Configure**
-6. Click **Add Provider** in NetBird

-### Step 5: Test the Connection
+### Step 5: Create Client Secret
+
+1. Go to **Certificates & secrets**
+2. Click **New client secret**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/4_new-client-secret-microsoft-entra.png" alt="New client secret" className="imagewrapper-big"/>
+</p>
+
+3. Add a description and expiration
+4. Click **Add**
+5. Copy the **Value** immediately (it won't be shown again) — you'll need this for Step 6
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/5_copy-secret-microsoft-entra.png" alt="Copy secret" className="imagewrapper-big"/>
+</p>
+
+### Step 6: Complete NetBird Setup
+
+1. Return to the NetBird tab
+2. Fill in the fields:
+   - **Client ID**: Paste the **Application (client) ID** from Step 3
+   - **Client Secret**: Paste the **Value** from Step 5
+   - **Issuer URL**: Paste the **Issuer URL** you constructed in Step 3 (for Entra ID only)
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/6_netbird-config-filled-microsoft-entra.png" alt="NetBird config filled" className="imagewrapper-big"/>
+</p>
+
+3. Click **Add Provider**
+
+### Step 7: Test the Connection

 1. Log out of NetBird Dashboard
 2. On the login page, you should see the Microsoft button
@@ -120,7 +161,7 @@ If you prefer to have full control over authentication, consider self-hosted alt
 5. After registration, note the **Application (client) ID** from the Overview page (you'll need this in Step 3)

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-new-application.png" alt="New application" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure/azure-new-application.png" alt="New application" className="imagewrapper-big"/>
 </p>

 ### Step 2: Configure Platform Settings
@@ -129,13 +170,13 @@ If you prefer to have full control over authentication, consider self-hosted alt
 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="SPA URI setup" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure/azure-spa-uri-setup.png" alt="SPA URI setup" className="imagewrapper-big"/>
 </p>

 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="Flows setup" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure/azure-flows-setup.png" alt="Flows setup" className="imagewrapper-big"/>
 </p>

 4. Click **Add a Platform** → **Mobile and desktop applications**
@@ -152,7 +193,7 @@ If you prefer to have full control over authentication, consider self-hosted alt
 5. Click **Add scope**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-add-scope.png" alt="Add scope" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure/azure-add-scope.png" alt="Add scope" className="imagewrapper-big"/>
 </p>

 6. Under **Authorized client applications**, click **+ Add a client application**
@@ -160,7 +201,7 @@ If you prefer to have full control over authentication, consider self-hosted alt
 8. Click **Add application**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-add-application-scope.png" alt="Add application scope" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure/azure-add-application-scope.png" alt="Add application scope" className="imagewrapper-big"/>
 </p>

 ### Step 4: Add API Permissions
@@ -170,7 +211,7 @@ If you prefer to have full control over authentication, consider self-hosted alt
 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="NetBird API permissions" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure/azure-netbird-api-permisssions.png" alt="NetBird API permissions" className="imagewrapper-big"/>
 </p>

 4. Click **Add a permission** again
@@ -179,13 +220,13 @@ If you prefer to have full control over authentication, consider self-hosted alt
 7. Click **Add permissions**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-openid-permissions.png" alt="OpenID permissions" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure/azure-openid-permissions.png" alt="OpenID permissions" className="imagewrapper-big"/>
 </p>

 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="Grant admin consent" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure/azure-grant-admin-conset.png" alt="Grant admin consent" className="imagewrapper-big"/>
 </p>

 ### Step 5: Update Token Version
@@ -204,7 +245,7 @@ If you prefer to have full control over authentication, consider self-hosted alt
 5. Copy the **Value** immediately

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure-client-secret.png" alt="Client secret" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/azure/azure-client-secret.png" alt="Client secret" className="imagewrapper-big"/>
 </p>

 6. Click **Overview** and note:
--- a/src/pages/selfhosted/identity-providers/managed/okta.mdx
+++ b/src/pages/selfhosted/identity-providers/managed/okta.mdx
@@ -1,6 +1,6 @@
 import {Note} from "@/components/mdx";

-# Okta
+# Okta SSO with NetBird Self-Hosted

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

@@ -18,9 +18,19 @@ Add Okta as an external IdP directly in the NetBird Management Dashboard. This i
 1. Navigate to Okta Admin Dashboard
 2. Click **Applications** → **Applications**
 3. Click **Create App Integration**
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/1_create-app-integration-okta.png" alt="Create app integration" className="imagewrapper-big"/>
+</p>
+
 4. Select:
   - **Sign-in method**: `OIDC - OpenID Connect`
   - **Application type**: `Web Application`
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/2_oidc-web-app-okta.png" alt="OIDC Web Application" className="imagewrapper-big"/>
+</p>
+
 5. Click **Next**
 6. Fill in:
   - **App integration name**: `NetBird`
@@ -30,6 +40,11 @@ Add Okta as an external IdP directly in the NetBird Management Dashboard. This i
   - **Allow everyone in your organization to access** (recommended for testing)
   - **Limit access to selected groups** (for production)
   - **Skip group assignment for now** (assign later)
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/3_assignments-okta.png" alt="Assignments" className="imagewrapper-big"/>
+</p>
+
 8. **Don't click Save yet** — keep this tab open and proceed to Step 2

 ### Step 2: Get Redirect URL from NetBird
@@ -49,20 +64,38 @@ Add Okta as an external IdP directly in the NetBird Management Dashboard. This i

 5. **Copy the Redirect URL** that NetBird displays (but don't click **Add Provider** yet)

+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/4_redirect-url-okta.png" alt="Copy redirect URL" className="imagewrapper-big"/>
+</p>
+
 ### Step 3: Complete Okta Application Setup

 1. Return to the Okta tab
 2. In the **Sign-in redirect URIs** field, paste the redirect URL you copied from NetBird
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/5_sign-in-uri-okta.png" alt="Sign-in redirect URIs" className="imagewrapper-big"/>
+</p>
+
 3. Click **Save**
 4. Note the **Client ID** and **Client Secret** — you'll need these for Step 4

+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/6_client-id-okta.png" alt="Client ID" className="imagewrapper-big"/>
+</p>
+
 ### Step 4: Complete NetBird Setup

 1. Return to the NetBird tab
 2. Fill in the **Client ID** and **Client Secret** from Step 3
+
+<p>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/7_complte-config-okta.png" alt="Complete configuration" className="imagewrapper-big"/>
+</p>
+
 3. Click **Add Provider**

-### Step 4: Test the Connection
+### Step 5: Test the Connection

 1. Log out of NetBird Dashboard
 2. On the login page, you should see an "Okta" button
@@ -97,7 +130,7 @@ If you prefer to have full control over authentication, consider self-hosted alt
 5. Click **Next**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-new-single-page-application.png" alt="New SPA application" className="imagewrapper"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/advanced/okta-new-single-page-application.png" alt="New SPA application" className="imagewrapper"/>
 </p>

 6. Fill in:
@@ -111,7 +144,7 @@ If you prefer to have full control over authentication, consider self-hosted alt
 7. Click **Save**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-single-page-application.png" alt="SPA application config" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/advanced/okta-single-page-application.png" alt="SPA application config" className="imagewrapper-big"/>
 </p>

 8. Note the **Client ID**
@@ -120,7 +153,7 @@ If you prefer to have full control over authentication, consider self-hosted alt
 11. Click **Save**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-single-sign-on-configuration.png" alt="Sign-on configuration" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/advanced/okta-single-sign-on-configuration.png" alt="Sign-on configuration" className="imagewrapper-big"/>
 </p>

 ### Step 2: Create Native Application (for Device Auth)
@@ -133,7 +166,7 @@ If you prefer to have full control over authentication, consider self-hosted alt
 4. Click **Next**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-new-native-application.png" alt="New native application" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/advanced/okta-new-native-application.png" alt="New native application" className="imagewrapper-big"/>
 </p>

 5. Fill in:
@@ -142,7 +175,7 @@ If you prefer to have full control over authentication, consider self-hosted alt
 6. Click **Save**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-native-application.png" alt="Native application config" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/advanced/okta-native-application.png" alt="Native application config" className="imagewrapper-big"/>
 </p>

 7. Note the **Client ID** (for device auth)
@@ -151,7 +184,7 @@ If you prefer to have full control over authentication, consider self-hosted alt
 10. Click **Save**

 <p>
-    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/okta-native-sign-on-configuration.png" alt="Native sign-on configuration" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/advanced/okta-native-sign-on-configuration.png" alt="Native sign-on configuration" className="imagewrapper-big"/>
 </p>

 ### Step 3: Generate API Token
@@ -165,7 +198,7 @@ If you prefer to have full control over authentication, consider self-hosted alt
 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="Generate token" className="imagewrapper-big"/>
+    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/advanced/okta-generate-token.png" alt="Generate token" className="imagewrapper-big"/>
 </p>

 ### Step 4: Configure NetBird