some file

Embedded IdP issues

Updated

Problems with the embedded identity provider (IdP) and SSO (single sign-on) on a self-hosted deployment. For other areas, start from Troubleshooting.

Setup page not accessible

Symptom: You can't open the /setup page to create the first user.

Likely causes and fixes (most common first):

  1. A user already exists. /setup is only available when no users exist. If you've already created one, use the regular login page.
  2. The embedded IdP is disabled. Confirm it is enabled in your configuration.
  3. Management isn't running. Check docker compose logs netbird-server (management on installs from before v0.65.0).

Confirm: /setup loads (first run), or the regular login page loads (setup already done).

"Setup already completed" error (HTTP 412)

Symptom: The setup endpoint returns a 412 error.

Cause: Setup has already completed; the first user exists.

Fix: Use the regular login page to sign in.

Password not working after user creation

Symptom: You created a user but the password doesn't work.

Cause: Passwords are shown only once at creation. If it wasn't saved, it can't be recovered, but you can set a new one.

Fix: Set a new password with the admin CLI (NetBird v0.75.0 and later). This works for the owner account too:

read -rsp 'New password: ' NB_PASSWORD; echo
printf '%s\n' "$NB_PASSWORD" | docker exec -i netbird-server \
  /go/bin/netbird-server --config /etc/netbird/config.yaml admin user change-password \
  --email user@example.com \
  --password-file -
unset NB_PASSWORD

The password is read from a silent prompt, so it doesn't end up in your shell history.

See Change a local user's password for the password rules and other options.

Confirm: You can log in with the new credentials.

SSO connector not appearing on login page

Symptom: You configured an identity provider but it doesn't show on the login page.

Likely causes and fixes (most common first):

  1. The connector wasn't saved. Check Settings → Identity Providers.
  2. The redirect URI is wrong. Ensure the IdP application has the exact redirect URI shown by NetBird.
  3. A configuration error. Review docker compose logs netbird-server for connector errors.

Confirm: The SSO button appears on the login page and starts the IdP flow.

"Invalid redirect URI" error from IdP

Symptom: Clicking an SSO button returns an invalid redirect URI error from the IdP.

Cause: The redirect URI registered at the IdP doesn't exactly match the one NetBird sends.

Fix: Copy the exact redirect URL from NetBird (shown after saving the connector) into your IdP's allowed redirect URIs. Watch for trailing slashes, typos, and case sensitivity.

Confirm: The SSO flow completes and lands you on the dashboard.

Identity Providers tab not visible

Symptom: The Identity Providers tab is missing from Settings.

Cause: The tab only appears when the embedded IdP is enabled and your role is allowed to read identity providers.

Fix: Check your deployment: quickstart enables it by default, the combined setup always has it on, and older multi-container deployments need EmbeddedIdP.Enabled set to true in management.json. If the embedded IdP is on and the tab is still missing, sign in with a role that can manage identity providers, or ask an administrator to check your role's permissions.

Confirm: The Identity Providers tab appears under Settings.

Users not syncing from SSO provider

Symptom: Users who authenticate via SSO don't appear in the user list.

Likely causes and fixes (most common first):

  1. They haven't logged in yet. Users appear after their first successful login, not when the connector is configured.
  2. The SSO flow isn't completing. Confirm the user lands on the dashboard after authenticating.
  3. Token validation is failing. Review the Management logs for token errors.

Confirm: After a successful SSO login, the user appears in the dashboard user list.