Single sign-on

Connect your identity provider so people at your company's email domain sign in with the account they already have, instead of a WorkMonitor password.

Who this is for

Owners only. Both viewing and changing the single sign-on connection need the permission that manages the organisation, which the default Manager role doesn't hold. A manager sees a locked page, not a read-only one.

Before you start

You'll need values from your identity provider (a client ID and secret for OpenID Connect, or a signing certificate and sign-on URL for SAML 2.0), and it helps to have your provider's admin console open in another tab, since you'll also need to paste values the other way.

Only OpenID Connect actually completes sign-in from the "Continue with SSO" button on the sign-in screen today. You can configure either protocol here, and the setup screens describe both as supported, but the sign-in button only recognises an OpenID Connect connection for a domain. If you configure SAML 2.0 instead, someone typing their work email at that button is told single sign-on "isn't set up" for their domain, not because the connection is missing, but because that entry point doesn't route SAML. Choose OpenID Connect if you want your team to actually be able to use it.

Steps

1. Open Single sign-on. Before anything is configured, you'll see "Your identity provider needs these", a panel with values to paste into the application you create on your provider's side: Redirect URI (OpenID Connect), Assertion consumer service URL (SAML), and Service provider entity ID (SAML) (also called the audience or identifier). Each has a Copy button.
2. Select Set up single sign-on. Choose OpenID Connect or SAML 2.0, then fill in the fields your provider gave you: for OpenID Connect that's Issuer URL, Client ID, and Client secret; for SAML 2.0 it's Sign-on URL, IdP entity ID, and a pasted Signing certificate (PEM). Either way, add the Email domain members sign in from, and pick the Role for new members they'll get the first time they sign in. Select Save configuration.
3. Once configured, use the Single sign-on enabled toggle to turn it on or off without touching anything else. Turning it off means everyone at that domain goes back to signing in with a password.
4. To change the Role for new members later, use the dropdown next to it. *"Applied the first time someone signs in through SSO. A name that matches no role leaves them with none."*
5. To review what's connected, open Single sign-on. The Connection section shows the protocol, the Email domain, the Sign-on URL or Issuer, the IdP entity ID or Client ID, whether a Secret is set, and the exact address members are sent to sign in.
6. To change the secret, certificate, or protocol itself, select Replace configuration at the top of the page. This is a full replacement, so both secret fields are required again, since your provider won't show you a secret a second time.
7. To turn federated sign-in off entirely, select Remove connection under Remove single sign-on and confirm.

What happens next

Once enabled, anyone with an email address at the configured domain is redirected to your identity provider when they try to sign in; matching them up is automatic. The very first person from that domain to sign in through it is created as a new member and given the role you chose. Turning the toggle off, or removing the connection, sends everyone at that domain back to a password. Accounts already created through SSO keep working, they just authenticate a different way.

If it doesn't work

• If you can't reach this page at all, you'll see "Only an owner can manage single sign-on", *"Ask an owner to set up your identity provider, or sign in as one."*
• If you try to save configuration without owner access, you'll see "Only an owner can configure single sign-on."
• If someone at a configured domain gets sent back to the sign-in page with a notice, here's what each one means: *"Single sign-on isn't set up for that email's domain yet. Sign in with your password below, or ask your admin to enable SSO."* means no OpenID Connect connection matched that domain. Check the domain is right, that it's enabled, and (see above) that it's configured as OpenID Connect rather than SAML. *"We couldn't reach your identity provider just now. Try SSO again in a moment, or sign in with your password below."* means the provider couldn't be reached at that moment. *"Single sign-on didn't complete. Try again, or sign in with your password below."* covers everything else that can go wrong mid-flow.
• Removing the connection deletes the stored configuration. You'll need the secret from your provider again if you want to set it back up.

Related

• Roles and permissions
• Workspace settings