SSO and provisioning
Single sign-on (SSO) lets members sign in to Bird through your identity provider instead of using a separate Bird password. Bird supports SAML 2.0 and OpenID Connect (OIDC) connections.
Setting one up is an organization Owner's task, and the controls live on your organization's Single sign-on page. A member granted the SSO permission can manage connections without being an Owner.
Personal Google or GitHub sign-in is separate from organization SSO. See Login, password & MFA.
How SSO works
An SSO connection covers one or more verified email domains, such as yourcompany.com. Members on those domains authenticate with your identity provider. Their Bird permissions still come from their organization and workspace roles.
What setup involves
An organization Owner and identity-provider administrator complete the setup:
- Prove you own the domain. Bird gives you a DNS record to publish for each email domain covered by the connection. Enforcement can't be turned on until the domain is verified.
- Configure the connection. For SAML, provide the identity-provider metadata, or the sign-in URL and signing certificates. For OIDC, provide the issuer and client credentials. Copy Bird's service-provider or redirect details into your identity provider.
- Test the connection. Complete a test sign-in before you activate the connection. Whichever protocol you chose, a draft whose test passes is activated for you, provided your organization has a verified domain and is under its limit on active connections.
- Choose whether to require SSO. When SSO is optional, members may use SSO or another available sign-in method. When it is required, members must complete SSO to access the organization. Requiring SSO needs an active connection and at least one verified domain.
Requiring SSO takes effect immediately, on every request, and not only on the next sign-in. A member whose current session was not established through your identity provider loses access to the organization until they sign in again through it, so plan the change around your team's day rather than announcing it afterwards. Organization Owners are the exception: an Owner keeps access with their Bird password, which is what stops a misconfigured connection locking everyone out.
Set up your identity provider
Step 2 is the half that differs by provider: the same value has a different name in each one, and each has a setting that refuses every sign-in if it is wrong. Bird's own field names are the ones on the connection page, under Register these with your identity provider.
For any other SAML 2.0 or OpenID Connect provider, the four steps above are the whole contract.
Setting up SAML without placeholder values
A SAML connection's Entity ID and Assertion Consumer Service URL are derived from the connection itself, so they do not exist until you create it. That leaves a circle: your identity provider needs those values, and they need the connection.
Create the connection first. In Add connection, choose SAML and then I have not set up my provider yet. The connection is created as a draft with no identity-provider details, and opening it shows the values to register under Register these with your identity provider. Configure your provider with those, then come back and use Supply the details on the same connection, in whichever form you have them:
- a metadata URL, which we fetch and read
- the metadata document itself, for a provider that hands out a file rather than hosting one
- the entity ID, sign-in URL and signing certificates, entered directly
An uploaded document is read for those three values and not stored.
Until the details arrive, the connection stays a draft: it serves no sign-ins and cannot be activated.
How members are identified
A SAML connection identifies each member by the NameID your provider sends, and that identifier is permanent for anyone who signs in. Setting a connection up does not ask you which format to use. If you supplied a metadata URL or document, we read what your provider advertises there and key the connection on it. If you entered the details by hand there is no metadata to read, so the connection is keyed on a permanent ID.
What you do control is the value behind it. Set the application username at your provider to something opaque and never reassigned, and send the address separately as an email attribute. An email address as the identifier is weaker forever: if the address is ever reassigned, the next person given it inherits the Bird account.
Metadata says what your provider can send; its application configuration decides what it does send, and those can differ. So the test sign-in in step 3 reports the identifier and format the assertion actually carried, and that report is how you check the two agree before anyone relies on the connection. We also refuse an identifier labelled persistent that is really an email address.
If the test reports a format you did not expect, you have two ways to correct it, and which one is right depends on what is wrong:
- The provider is sending the wrong thing. Change the application username at your provider, then test again. This is usually the right fix, because the opaque identifier is the one worth keeping.
- The connection is keyed on the wrong thing. Open Edit on the connection and change the NameID format to the one your provider sends.
Do either before members start signing in. Once they have, their accounts are linked to the identifier in force, so the format is fixed and the change is refused. Create a connection for the new format instead.
Replacing a provider
A SAML connection's identity-provider details can be replaced while it has signed nobody in. Once members have used it, their accounts are linked to the identifiers your current provider sends, so replacing those is refused. Create a connection for the new provider instead. On an OIDC connection you can rotate the client secret at any time, which does not change what identifies members, but the provider itself cannot be replaced.
The test sign-in in step 3 does not count. A test links no account and grants no access, so a connection you have set up and tested but not yet given to your team can still be re-pointed.
What changes for your team
A connection can grant default organization and workspace access to a member on their first successful SSO sign-in. Configure that default access explicitly; otherwise, invite members and assign roles before they sign in. See Users, teams & roles.
Suspending a connection prevents new sign-ins through it. Review Bird memberships and active sessions separately when someone leaves your company.
Next steps
- Login, password & MFA: individual account security, including personal Google/GitHub sign-in
- Users, teams & roles: how roles and permissions work once members are in
- Authentication & API keys: the developer-facing authentication reference
Related resources
Continue with the documentation, guides and examples for this topic. Resources are in English.