> ## Documentation Index
> Fetch the complete documentation index at: https://docs.northbeam.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Single sign-on (SSO)

> Set up single sign-on for your organization, connect your identity provider, and manage your team's access.

Beta

Single sign-on (SSO) lets members on your configured email domains sign in to Northbeam through your identity provider (IdP), such as Okta, Microsoft Entra ID, or Google Workspace, instead of with a Northbeam password. You configure SSO once for your **organization**, which can own one or more dashboards.

## Before you begin

* **Organization admin access:** You need permission to manage SSO for the organization. Being a dashboard account manager does not by itself grant this permission. Members with view-only access can see the configuration but cannot change it.
* **Identity-provider access:** You or your IT administrator must be able to configure an application in your IdP.
* **Your team's email domains:** Use the domain after `@` in members' work email addresses, not a website URL or a full email address.

If you do not see Organization Settings or cannot manage SSO, [contact Northbeam Support](https://www.northbeam.io/submit-a-support-ticket) to check availability and your access.

> [!NOTE]
>
> Screenshots use the fictional organization **Acme Widgets** and the example domain `acme.example`. Use your own organization's name and email domains when following these steps.

## Open Organization Settings

You can reach organization settings from either of these places:

> [tab] Dashboard menu
>
> From a dashboard, open the **menu** (the three lines in the top-right corner) and select **Organization Settings**.
>
> ![The dashboard menu with Organization Settings highlighted](https://mintlify.s3.us-west-1.amazonaws.com/northbeam/images/organization-sso/dashboard-menu.png)

> [tab] Settings sidebar
>
> Open a dashboard's **Settings** and find **Organization** at the top of the left sidebar. If you have access to one organization, select its **name**. If you have access to multiple organizations, select **Organizations**.
>
> ![The Settings sidebar showing Acme Widgets under Organization for a user with access to one organization](https://mintlify.s3.us-west-1.amazonaws.com/northbeam/images/organization-sso/settings-organization.png)

With access to one organization, you go directly to its **Single sign-on** page. With access to multiple organizations, first choose the organization you want to configure. You can also open [the Organizations page](https://dashboard.northbeam.io/organizations) directly.

Check the organization name before making changes. **Back to dashboard**, in the top-right corner of the organization page, returns you to your dashboard.

## Set up SSO

**1. Enter your email domains and create the configuration**

In **Email domains**, enter each domain your team will use to sign in, such as `acme.example`. Press Enter, comma, or space to add each domain. Enter subdomains separately if members use them in their email addresses.

Click **Create SSO configuration**. Northbeam generates the connection name from your organization name.

![Acme Widgets SSO form with acme.example entered and Create SSO configuration highlighted](https://mintlify.s3.us-west-1.amazonaws.com/northbeam/images/organization-sso/sso-create.png)

**2. Check whether domain approval is needed**

**No approval is needed when every domain you enter matches your login email domain.** For example, if you are signed in as `jordan@acme.example` and enter `acme.example`, you can go straight to **Open the setup link** once the status is **Setup pending**.

If any domain you enter differs from your login email domain, the configuration shows **Awaiting Northbeam approval**. For example, an administrator signed in as `jordan@partner.example` needs approval to configure `acme.example`.

[Contact Northbeam Support](https://www.northbeam.io/submit-a-support-ticket) with your **organization name** and the **email domains** you want to use. A Northbeam team member must review and approve the request before you can get a setup link. You cannot approve it yourself from Organization Settings.

Northbeam staff can follow the [internal SSO approval runbook (staff access required)](https://docs.northbeam.io/docs/organization-sso-internal.md).

![Awaiting Northbeam approval for Acme Widgets because the claimed email domain differs from the signed-in user's domain](https://mintlify.s3.us-west-1.amazonaws.com/northbeam/images/organization-sso/sso-approval-required.png)

After Support confirms approval, return to this page and click **Check status**. Continue when the status is **Setup pending**. If your configuration already shows Setup pending, you can go straight to the next step.

**3. Open the setup link**

Click **Set up identity provider**. If a link has already been generated, the button is **Generate new setup link** instead.

![Setup pending with Check status and Generate new setup link highlighted](https://mintlify.s3.us-west-1.amazonaws.com/northbeam/images/organization-sso/sso-pending.png)

In the **Set up your identity provider** dialog, click **Open Auth0 setup**, or **Copy** the link for the IT administrator completing the setup. Auth0 provides the step-by-step instructions for your identity provider and its SAML or OpenID Connect (OIDC) connection.

![The setup-link dialog with the URL blurred and the Copy and Open Auth0 setup buttons highlighted](https://mintlify.s3.us-west-1.amazonaws.com/northbeam/images/organization-sso/sso-setup-link.png)

> [!WARNING]
>
> Anyone with this link can configure the connection. Share it only with the administrator responsible for your IdP. The URL is shown only in this dialog and expires at the time displayed. If you close the dialog without saving it, or the link expires, generate a new one. Generating a new link immediately invalidates the previous one.

**4. Complete your IdP setup and check the status**

Finish the Auth0 walkthrough, then return to Northbeam's **Organization Settings** and click **Check status**.

![Check status highlighted after returning from the identity-provider walkthrough](https://mintlify.s3.us-west-1.amazonaws.com/northbeam/images/organization-sso/sso-check-status.png)

When Northbeam detects the completed connection, the status changes to **SSO active**. There is no separate Enable SSO step during initial setup; that button is used to turn a previously disabled configuration back on.

![SSO active for Acme Widgets and acme.example, with Back to dashboard visible](https://mintlify.s3.us-west-1.amazonaws.com/northbeam/images/organization-sso/sso-active.png)

If the page still shows **Setup pending**, confirm that the Auth0 walkthrough is complete, then click **Check status** again. If it remains pending, [contact Northbeam Support](https://www.northbeam.io/submit-a-support-ticket).

## Statuses

| Status | What it means | Next step |
| :- | :- | :- |
| **Awaiting Northbeam approval** | At least one claimed domain differs from your signed-in email domain and needs review. | Contact Northbeam Support. After approval, click **Check status** to continue setup. |
| **Setup pending** | The configuration exists, but Northbeam has not yet detected a completed IdP connection. | Open a setup link and finish the Auth0 walkthrough, then click **Check status**. |
| **Setup link expired** | The setup link expired before the connection was completed. | Generate a new setup link and complete the walkthrough. |
| **SSO active** | SSO is enabled for the configured email domains. | Members can sign in through your IdP. |
| **SSO disabled** | SSO has been turned off; the configuration is retained. | Click **Enable SSO** to turn it back on. |
| **Setup error** | Auth0 could not generate the setup link. | Generate a new setup link. Contact Support if the error continues. |

## What changes for your team

* **Existing members on a configured domain** use your IdP the next time they sign in. Make sure they have access to the Northbeam application in your IdP.
* **New members** still need an invitation to the appropriate Northbeam dashboard. While SSO is active, invitees on a configured domain receive an SSO invitation that links to the dashboard, without a password-creation link. See [Adding / Removing Users](https://docs.northbeam.io/docs/adding-or-removing-users-copy.md).
* **Members outside the configured domains**, such as agency partners, keep their existing sign-in method.

## Change email domains

While setup is pending, you can edit **Email domains** and click **Save changes**. Adding a domain that differs from your signed-in email domain requires Northbeam approval.

Domains are read-only while the configuration is **SSO active**. If you need to add or change domains after activation, contact Northbeam Support before making changes so the team can help with any required approval and sign-in interruption.

## Disable or remove SSO

> [!WARNING]
>
> Prepare password sign-in for affected members before disabling or removing SSO. Members invited through SSO may never have set a Northbeam password. While they can still sign in, ask them to open **Settings > User settings**, click **Reset password**, and follow the emailed link to set one. If they cannot complete this, [contact Northbeam Support](https://www.northbeam.io/submit-a-support-ticket) before proceeding.

Only an organization admin with SSO management access can perform these actions:

* **Disable SSO** stops SSO sign-ins and retains the configuration. Click **Disable SSO**, then **Yes, disable SSO** to confirm. Members will need to sign in with a Northbeam password while it is disabled. Click **Enable SSO** to turn it back on later.
* **Remove SSO configuration**, in **Danger zone**, deletes the identity-provider connection. Type the organization's name exactly as displayed to enable the removal button. To use SSO again afterward, you must create a new configuration and reconnect your IdP.

If SSO is already disabled and a member does not know their Northbeam password, they can use the password reset flow from [dashboard.northbeam.io](https://dashboard.northbeam.io). Contact Northbeam Support if they cannot reset their password or sign in.

## Frequently asked questions

> [accordion] Why do I need Northbeam approval?
>
> **You do not need approval if every claimed domain matches your login email domain.** Approval is required when a claimed email domain differs from the domain of the account you are signed in with, including when you add another domain later. This can happen when an agency or IT partner configures SSO for a customer. [Contact Northbeam Support](https://www.northbeam.io/submit-a-support-ticket) with the organization name and requested domains. After the team approves the request, click **Check status** in Organization Settings.

> [accordion] A member's first sign-in through SSO failed. What should they do?
>
> Ask them to try again from their invitation link or [dashboard.northbeam.io](https://dashboard.northbeam.io) using their work email. Confirm that SSO is active, their email domain is listed in the configuration, they have access to the Northbeam application in your IdP, and they have been invited to the dashboard. If they still cannot sign in, contact Northbeam Support.

> [accordion] Northbeam rejected one of my domains.
>
> Check the message beside **Email domains**. Public email domains such as `gmail.com` cannot be claimed, and a domain can belong to only one organization. Enter only the domain, without `https://` or an email username. Contact Northbeam Support if a domain you control is already claimed.

> [accordion] Can I use SSO for some dashboards but not others?
>
> SSO is configured for the organization and applies to the dashboards it owns. There is no per-dashboard SSO toggle. Members outside the configured email domains keep their existing sign-in method.

> [accordion] I can see the SSO settings but cannot change them.
>
> You have view-only access. Ask an organization admin to make the change, or contact Northbeam Support to check your SSO management access. Dashboard account-manager permissions are separate from organization-level SSO permissions.
