diff --git a/public/docs-static/img/selfhosted/identity-providers/local-mfa/totp-setup.png b/public/docs-static/img/selfhosted/identity-providers/local-mfa/totp-setup.png new file mode 100644 index 000000000..c57694c72 Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/local-mfa/totp-setup.png differ diff --git a/public/docs-static/img/selfhosted/identity-providers/local-mfa/totp-verify.png b/public/docs-static/img/selfhosted/identity-providers/local-mfa/totp-verify.png new file mode 100644 index 000000000..96b8a8e00 Binary files /dev/null and b/public/docs-static/img/selfhosted/identity-providers/local-mfa/totp-verify.png differ diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 3a88d3577..d0500e1b7 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -576,6 +576,10 @@ export const docsNavigation = [ title: 'Disable Local Auth', href: '/selfhosted/identity-providers/disable-local-authentication', }, + { + title: 'Enable MFA for local users', + href: '/selfhosted/identity-providers/enable-local-mfa' + }, { title: 'Self-hosted IdPs', isOpen: true, diff --git a/src/pages/selfhosted/configuration-files.mdx b/src/pages/selfhosted/configuration-files.mdx index e3e59346b..6da0bdb77 100644 --- a/src/pages/selfhosted/configuration-files.mdx +++ b/src/pages/selfhosted/configuration-files.mdx @@ -283,6 +283,13 @@ Configures the built-in identity provider (embedded IdP) that handles user authe Password for the initial admin user. Optional. Used together with `owner.email` to bootstrap the first admin account on initial deployment. + + Maximum MFA session duration from creation. After this time, local users must re-authenticate with TOTP regardless of activity. Default: `"24h"`. Only applicable when [local MFA](/selfhosted/identity-providers/enable-local-mfa) is enabled. + + + MFA session idle timeout. If the user is inactive for this duration, the MFA session expires and they must re-authenticate with TOTP. Default: `"1h"`. Only applicable when [local MFA](/selfhosted/identity-providers/enable-local-mfa) is enabled. + + When the embedded IdP is active, the server automatically hosts these OIDC endpoints: diff --git a/src/pages/selfhosted/identity-providers/enable-local-mfa.mdx b/src/pages/selfhosted/identity-providers/enable-local-mfa.mdx new file mode 100644 index 000000000..30161a04a --- /dev/null +++ b/src/pages/selfhosted/identity-providers/enable-local-mfa.mdx @@ -0,0 +1,116 @@ +import {Note, Warning} from "@/components/mdx" + +export const description = "Enable MFA for local users in your self-hosted NetBird deployment so that all users have to complete a TOTP challenge to login"; + +# Enable MFA for local users + +NetBird supports multi-factor authentication (MFA) for local users managed by the embedded identity provider. When enabled, all local users are required to set up and verify a time-based one-time password (TOTP) using an authenticator app before they can log in. + +This is useful when you want to add an extra layer of security to local users, as it will require **all** local users to authenticate using the TOTP code on every login. + + +MFA enforcement applies only to local users authenticated through the embedded IdP. Users who sign in via external identity providers (Google, Microsoft, Okta, etc.) are not affected, as MFA for those users should be configured in the respective IdP. + + +## Prerequisites + +- A self-hosted NetBird deployment using the [embedded identity provider](/selfhosted/identity-providers/local) +- Local authentication must be enabled (not [disabled](/selfhosted/identity-providers/disable-local-authentication)) +- Admin or Owner access to the NetBird Dashboard + +## Enabling MFA + +1. Log in to the NetBird Dashboard as an Admin or Owner +2. Navigate to **Settings** → **Authentication** +3. Toggle **Local MFA** to on +4. Click **Save** + +Once enabled, all local users will be prompted to set up TOTP on their next login. + +## User experience + +### First login after MFA is enabled + +When a local user logs in for the first time after MFA is enabled, they are presented with a TOTP setup screen: + +1. The user sees a QR code and is prompted to scan it with an authenticator app (e.g., Google Authenticator, Authy, 1Password) +2. After scanning, the user enters the one-time code generated by their authenticator app +3. The user clicks **Verify** to complete the setup + +

+ TOTP Setup - Scan QR code with authenticator app +

+ +### Subsequent logins + +After the initial setup, every login requires a TOTP verification step: + +1. The user enters their email and password as usual +2. A second screen prompts for the one-time code from their authenticator app +3. The user enters the code and clicks **Verify** to complete the login + +

+ TOTP Verification - Enter code from authenticator app +

+ +## MFA session configuration + +NetBird will hold an MFA session after a user went through the whole authentication process, this session will let users skip the MFA authentication process +as long as the session is active. + +By default, MFA sessions last up to 24 hours and expire after 1 hour of inactivity. You can customize these values depending on your deployment type. + +| Setting | Description | Default | +|---------|-------------|---------| +| `mfaSessionMaxLifetime` | Maximum session duration from creation. After this time, the user must re-authenticate with MFA regardless of activity. | `24h` | +| `mfaSessionIdleTimeout` | Idle timeout. If the user is inactive for this duration, the MFA session expires and they must re-authenticate. | `1h` | + +### Combined setup (config.yaml) + +```yaml +server: + auth: + mfaSessionMaxLifetime: "24h" + mfaSessionIdleTimeout: "1h" +``` + +Restart the server after changing these values: + +```bash +docker compose restart netbird-server +``` + +### Older multi-container setup (management.json) + + +This section applies to deployments using the older multi-container architecture. If you deployed using `getting-started.sh`, you are on the combined setup and should use the `config.yaml` instructions above. See the [migration guide](/selfhosted/migration/combined-container) to upgrade. + + +```json +{ + "EmbeddedIdP": { + "Enabled": true, + "MfaSessionMaxLifetime": "24h", + "MfaSessionIdleTimeout": "1h" + } +} +``` + +Restart the Management service after changing these values: + +```bash +docker compose restart management +``` + +## Disabling MFA + +To disable MFA for local users: + +1. Navigate to **Settings** → **Authentication** +2. Toggle **Local MFA** to off +3. Click **Save** + + +Disable MFA removes the TOTP requirement but **does not** remove the stored TOTP authenticator information. If you enable MFA again +previously enrolled users will be prompted for the same authenticator they registered previously. +