From a9a542e3e2b495db807f9dc38e5ef1bf9ef99553 Mon Sep 17 00:00:00 2001 From: braginini Date: Sat, 31 Jan 2026 15:15:07 +0100 Subject: [PATCH] Disable local authentication --- src/components/NavigationDocs.jsx | 1 + .../disable-local-authentication.mdx | 60 +++++++++++++++++++ .../selfhosted/identity-providers/local.mdx | 29 --------- 3 files changed, 61 insertions(+), 29 deletions(-) create mode 100644 src/pages/selfhosted/identity-providers/disable-local-authentication.mdx diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index fe6730688..a901cb206 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -305,6 +305,7 @@ export const docsNavigation = [ links: [ { title: 'Authentication and IdPs', href: '/selfhosted/identity-providers' }, { title: 'Local User Management', href: '/selfhosted/identity-providers/local' }, + { title: 'Disable Local Auth', href: '/selfhosted/identity-providers/disable-local-authentication' }, { title: 'Self-hosted IdPs', isOpen: true, diff --git a/src/pages/selfhosted/identity-providers/disable-local-authentication.mdx b/src/pages/selfhosted/identity-providers/disable-local-authentication.mdx new file mode 100644 index 000000000..7751a0a20 --- /dev/null +++ b/src/pages/selfhosted/identity-providers/disable-local-authentication.mdx @@ -0,0 +1,60 @@ +# Disable Local Authentication + +If you prefer to delegate all credential storage and authentication to your IdP while still utilizing NetBird's new, +simplified IdP connection flow, you can completely disable local (email/password) authentication. + +This is useful when you want to: + +- Enforce that all users authenticate via external identity providers only +- Simplify end user login by directing users to your external IdP when logging in to NetBird +- Prevent local password-based logins while still using NetBird's simplified IdP connection flow +- Maintain a single source of truth for user credentials in your external IdP + + +Disabling local authentication preserves existing local user accounts in the database. +If you re-enable local authentication later, those users will be able to log in again with their existing credentials. + + +## Prerequisites + +Before disabling local authentication: + +1. Configure an external IdP connector following the [Authentication Guide](/selfhosted/identity-providers). +2. Log out and log in with your new admin account via the external IdP. NetBird will notify you that the user requires approval. +3. Log back in as your original NetBird-local admin and navigate to **Team > Users**. You should see the new IdP user pending approval: + +Approve User + +4. Approve the request, click on the user, select **Owner** as the role, confirm the ownership transfer, and save. + +Change Owner + +5. Verify you can log in via the external IdP with full owner access. + + +NetBird will refuse to disable local authentication if no external identity provider connectors are configured. + This prevents you from being locked out of your instance. + + +## Configuration + +Update your `management.json` to disable local authentication: + +```json +{ + "EmbeddedIdP": { + "Enabled": true, + "LocalAuthDisabled": true + } +} +``` + +After updating the configuration, restart the Management service. +The local login option will no longer appear on the login page—users will only see the configured external identity providers. + +## Re-enabling Local Authentication + +To restore local authentication, set `LocalAuthDisabled` to `false` (or remove the option) and restart the Management service. +All previously created local users will be able to log in again with their existing passwords. + + diff --git a/src/pages/selfhosted/identity-providers/local.mdx b/src/pages/selfhosted/identity-providers/local.mdx index 10c146d86..0b7cfc7b0 100644 --- a/src/pages/selfhosted/identity-providers/local.mdx +++ b/src/pages/selfhosted/identity-providers/local.mdx @@ -372,35 +372,6 @@ Ensure `EmbeddedIdP.Enabled` is `true` in `management.json` and the Management s 2. Verify the encryption key hasn't changed 3. Confirm the user exists: Check **Team** → **Users** in Dashboard -## Comparison with External IdP - -| Feature | Embedded IdP | External IdP | -|---------|--------------|--------------| -| Setup complexity | Minimal | Moderate to High | -| Resource requirements | Low (~1GB RAM) | Higher (2-4GB+ RAM) | -| Additional containers | None | IdP + Database | -| User management | Dashboard/API | External IdP console | -| External SSO | Via connectors | Native | -| SCIM provisioning | Not available | Available (Enterprise) | -| MFA | Via external connectors | Native IdP feature | -| Backup complexity | Single database | Multiple databases | - -## Deleting the Default Local Admin User - -If you prefer to delegate all credential storage and authentication to your IdP while still utilizing NetBird's new, simplified IdP connection flow, you can remove the default local user. To do so: - -1. Configure an external IdP connector following the [Authentication Guide](/selfhosted/identity-providers). -2. Log out and log in with your new admin account via the external IdP. NetBird will notify you that the user requires approval. -3. Log back in as your original NetBird-local admin and navigate to **Team > Users**. You should see the new IdP user pending approval: - -Approve User - -4. Approve the request, click on the user, select **Owner** as the role, confirm the ownership transfer, and save. - -Change Owner - -5. Log out and log back in as the new IdP user. You should now have admin access. Navigate to **Team > Users** and delete the original NetBird-local user. - ## Disabling Embedded IdP To switch from embedded IdP to a (standalone) external IdP: