Single Sign-On lets people sign in to Buttons through an identity provider your organization already uses, instead of maintaining a separate local password. This page covers the shared setup that applies no matter which provider you connect, and the safe order to bring it online.
Important
Local username/password sign-in can never be disabled through SSO configuration. It's not a setting you might accidentally turn off: the code path that handles local sign-in has no dependency on SSO at all. Whatever happens with your identity provider, the local sign-in option stays reachable from the same login page.
Before you begin#
- An Enterprise license: SSO is gated to this tier, and only system administrators can configure it.
- A plan for at least one role your identity provider's claims or groups should map to: see Map identity claims to roles.
Understand the page#
Settings → SSO ("SSO connections") has two parts:
- Sign-in policy: a master SSO login toggle ("Allow users to sign in with configured identity providers."), a Default login choice of which sign-in view loads first, local or SSO (you can't actually set this to SSO until at least one provider exists), and Allowed email domains: an optional allowlist restricting which email domains can register a new account through SSO (leave it empty to allow any domain). Both sign-in views remain reachable regardless of the default: that setting only changes which one someone sees without clicking through.
- Identity providers: the list of configured connections, added via Add provider. You can add more than one: Google, Microsoft Entra ID, GitHub, Okta, Generic OIDC, and LDAP/Active Directory can all coexist, each enabled independently.
Bring SSO online safely#
- Add a connection for your provider: see Connect a generic OIDC provider or Connect LDAP or Active Directory for the provider-specific fields.
- Add at least one role mapping before you expect anyone to actually use it: see Map identity claims to roles. Without a mapping, a successful sign-in still won't grant any role.
- Sign in yourself as a real test of the whole path. Only LDAP has a built-in Test connection check (a service-account bind and search): for every other provider, an actual sign-in is the only way to confirm the whole chain works, since there's no separate pre-flight test.
- Only once that works, turn on the master SSO login toggle and, if you want it to be what people see first, switch the default sign-in view to SSO.
Until the master toggle is on, the interface reminds you directly: "Local login remains active until SSO login is enabled." Turning it on adds SSO as an option: it never removes or restricts local sign-in.
Know what isn't a safety net#
There's no separate "rollback" feature to reach for if something goes wrong: no watchdog-level override, no external kill switch. The reason you don't need one is architectural: local sign-in was never dependent on SSO in the first place, so there's nothing to roll back to. Keep a local administrator account's credentials on hand as ordinary good practice, not because Buttons would otherwise lock you out.
If you get stuck#
What you see | What to try |
|---|
A user signs in through SSO but gets no role. | |
You're not sure SSO is configured correctly before turning it on for everyone. | Sign in yourself as a real test: beyond LDAP's own connection check, this is the only way to confirm the full path works. |
You're worried about being locked out while testing. | You won't be: local sign-in is never disabled by anything in this settings area, at any point. |
The SSO login toggle is off and users are asking why SSO isn't available yet. | That's expected until you turn it on deliberately, once you've verified the connection and its role mappings work. |
A user can authenticate with your identity provider but still can't get an account. | Check Allowed email domains, if it's set, only matching email domains can register a new account through SSO; leave it empty to allow any domain. |
Where to go next#
