# Single sign-on

Connect an identity provider, prove it works, then require it for your staff.

Single sign-on is configured per organisation, by someone with the **Head Office** role, at
**ToolboxFM › Admin › Single sign-on**. Credentials are encrypted before they are stored.
There is no DNS record to publish: a connection works as soon as it is switched on.

## How staff sign in

Each connection has a setting for how staff sign in:

| Setting | What it does |
| --- | --- |
| **Off** | Nobody signs in through the provider. Passwords keep working for everyone. |
| **Optional** | Staff can sign in with your provider or their password. |
| **Required** | Staff on the connection's email domains must sign in with your provider to use your organisation. Head Office can still use a password. |

**Optional is where you prove the connection.** It is not a staging environment — sign-ins
through it are real and are recorded. That is what makes requiring it meaningful.

## Who can sign in through your provider

ToolboxFM never trusts an email address just because of its domain. Your provider signs someone in
only when there is proof of who they are:

- **An invitation.** Someone invited to your organisation accepts through your provider, and their
  account is created.
- **The staff sign-in link.** Each connection that is switched on shows a link to share with staff.
  It signs in anyone who was invited through the provider or has connected their account.
- **Connecting their account.** Someone who already has a password links it at
  **ToolboxFM › Account settings › Connected accounts**, or from the page shown when your
  organisation requires single sign-on.

Once someone's account is connected, the sign-in page sends them straight to your provider.

:::caution
A sign-in through your provider only works in your organisation. If that person also belongs to
another organisation, they sign in there with their password. Anyone can set up a provider for any
domain, so a provider is never trusted beyond the organisation that connected it.
:::

## Requiring single sign-on

When single sign-on is required, it applies to members of your organisation whose email address is on
one of the connection's domains:

| Member | Must use your provider |
| --- | --- |
| Staff on a connection domain, for example `sam@northbuild.com.au` | Yes |
| Head Office | No, so a broken provider can always be fixed |
| Subcontractors and anyone on another domain | No |

A staff member who signed in with a password sees a page explaining that your organisation uses
single sign-on, with a button to continue with your provider. Continuing connects their account if it
is not connected yet. Their password keeps working in any other organisation they belong to, and the
page lets them switch to one.

You cannot require a connection just by saying it is ready. ToolboxFM checks for evidence first, and
refuses the change if either is missing:

1. **At least one email domain** on the connection.
2. **At least one completed sign-in** through that connection.

The sign-in requirement is what makes the setup wizard's "Signed in" row real rather than a checkbox.
It means a connection has been used successfully at least once before anyone depends on it.

This check runs in the same transaction as the change, not only in the interface, so it holds however
the change is made.

## If it goes wrong

Because a required connection keeps staff out of your organisation until they sign in with your
provider, a broken provider could lock them out. ToolboxFM keeps a way back in: someone with the
Head Office role can always use a password. See
[Signing in](/getting-started/signing-in/#if-an-administrator-is-locked-out).

## Related

- [Signing in](/getting-started/signing-in/)
- [Users and roles](/tenant-setup/users-and-roles/)