The SSO section under Burrow Settings lets members sign in to your Burrow through your organisation's identity provider, over SAML 2.0 or OpenID Connect. Only the Burrow's owner can open it. Single sign-on is included on eligible plans. On other plans the section shows what it adds, and a setup made while your plan covered it stays visible, read-only, until the plan covers it again.
The line at the top of the section says whether the sign-in page offers single sign-on right now, and when it doesn't, what is still missing. Setup is three steps, in order. A finished step folds to a one-line summary, and you can open it again to change it.
Verify your domain#
Your identity provider signs people in by their email address, so first prove which addresses are your organisation's. Enter a domain, such as example.com, and add it. The Burrow shows a TXT record for it: a name of the form _ratelkey-verification.example.com and a value to go with it. Copy both into your DNS provider, then select Verify.
DNS changes can take a few minutes to be seen. If the record isn't found yet, wait and verify again. Verification happens once, and removing the record afterwards changes nothing. Add every domain your organisation's addresses use, and remove one you no longer want with Remove.
People whose address is at a verified domain sign in through your identity provider. At least one domain has to be verified before sign-in can be turned on.
Connect your identity provider#
Choose SAML 2.0 or OpenID Connect, whichever your identity provider offers for a new application. Under For Your Identity Provider are the values your identity provider's administrator enters on their side, each with a copy button:
SAML: the Entity ID and the ACS URL. Once you have saved a SAML connection, the Metadata URL and the fingerprint of the Burrow's signing certificate appear too, for identity providers that read metadata or ask to check the certificate.
OpenID Connect: the Redirect URI.
Then enter your identity provider's side of the connection.
SAML. Paste your identity provider's metadata XML, or upload the metadata file, and the entity ID, sign-in URL and signing certificate are read from it. You can also fill in those three by hand. Your identity provider must sign its assertions. Its current certificates are listed with their expiry dates, and pasting a new certificate replaces them, which is how you follow your identity provider through a certificate rotation.
OpenID Connect. Enter the issuer, the client ID and the client secret from the application you created in your identity provider. The issuer must publish its discovery document. The client secret is stored and never shown again. To change it, enter a new one.
Select Save connection. The connection is checked when you save, and anything missing or unusable is named under the button.
Turn on sign-in#
The last step holds the settings you come back to. Change any of them and select Save.
Sign in through the identity provider. Turn it on and the Burrow's sign-in page offers single sign-on. It can't be turned on until a domain is verified.
Require it for everyone but you. Every member except the owner has to sign in through your identity provider. See Requiring single sign-on below.
Let it add new members. Someone at a verified domain who isn't a member yet becomes one the first time they sign in, taking a seat on your plan. With it off, only existing members and people your identity provider provisioned over SCIM can get in.
Role for new members. The role a new member gets, unless a SCIM group mapping decides it.
Session length. How long a sign-in through your identity provider lasts, from 1 to 720 hours. The default is 24. When your identity provider says its own sign-in ends sooner, the session ends then.
Remove, beside Save, takes single sign-on off the Burrow. Members stop signing in through your identity provider and any requirement to use it is lifted. Linked sign-ins are kept, so connecting the same identity provider again restores them.
Signing in#
Once sign-in is on, the Burrow's sign-in page offers single sign-on. A member chooses it, signs in at your identity provider, and comes back signed in to the Burrow. What happens the first time depends on their address.
An address at a verified domain with no RatelKey account. An account is created and signed in, when Let it add new members is on or your identity provider provisioned them over SCIM. Otherwise the sign-in is refused.
An address at a verified domain that already has a RatelKey account. The account moves to your identity provider on its first sign-in through it. Its password, passkeys, authenticator app, recovery codes and linked GitHub account are removed, every other session of the account ends, and the person gets an email saying so. From then on your identity provider is the only way to sign in to that account, and its account page shows that your Burrow manages its sign-in. If the account's address was never confirmed, the sign-in is refused and a confirmation email is sent. Once the address is confirmed, they sign in through your identity provider again.
An address outside your verified domains. This is someone like a contractor who keeps their own RatelKey account. After signing in at your identity provider, they sign in once with their own account to link the two. After that, entering this Burrow goes through your identity provider, and their account and its other Burrows stay their own.
Requiring single sign-on#
With Require it for everyone but you on, every member except the owner has to sign in through your identity provider. Sessions started any other way end when you save, and a password or passkey sign-in to this Burrow is refused. The owner is left out, so an identity provider that is down or misconfigured can never lock you out of your own Burrow.
If your plan stops including single sign-on, the requirement is lifted until it does again.
Linked sign-ins#
Under the steps is every identity-provider sign-in linked to an account in this Burrow: the person's email address, the name your identity provider knows them by when it differs, and when they last used it.
An account your identity provider created or took over is marked Managed. Its only way in is your identity provider, so it can't be unlinked. To take its access away, remove the member on the Members page or deactivate them in your identity provider. A sign-in someone linked to their own account can be unlinked, and the next time they sign in through your identity provider they are asked to link again.