some file

Embedded IdP issues

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

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.

Fix: Recreate the user (delete and re-add, or create a new one with a new password via the API). For the owner account with no other admins, you may need to reset the database.

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

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.

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.