Set up SSO with Google Workspace
This page covers the Google Workspace half of an SSO connection. The Bird half (verifying a domain, testing, activating, and requiring SSO) is the same for every provider and lives on SSO and provisioning.
Google and Bird each need values from the other, so where you start depends on the protocol. Keep both open as you work.
Two Google behaviours cause most failed first tests, and neither reports anything to Bird:
- Turn on user access before you test. A new custom SAML app starts off for everyone. Until you enable it for the people who will sign in, Google refuses at its own side and the test window shows nothing.
- Wait a few minutes after saving. Google applies changes to a SAML app (response signing, Name ID format, user access) after a delay of roughly two to four minutes. A test run inside that window reports the previous configuration, which reads as a Bird problem and is not one.
SAML
Start in Bird for SAML. A SAML connection's Entity ID and Assertion Consumer Service URL derive from the connection itself, so create it with I have not set up my provider yet, register the values it then shows, and come back to Supply the details. Setting up SAML without placeholder values walks through that flow.
Google publishes no metadata URL for a custom SAML app. Download the metadata file from the Google Admin console and paste its contents into Supply the details on the Bird connection, choosing the metadata-document option.
Google's field names do not match Bird's:
| In Bird, under Register these with your identity provider | In Google Workspace |
|---|---|
| Assertion Consumer Service URL | ACS URL |
| Entity ID | Entity ID |
| Sign-in URL for this connection | Start URL (optional) |
Turn off Signed response
Leave Signed response unchecked. With it checked, Google signs the response and leaves the assertion inside it unsigned, and Bird verifies the assertion's own signature, so every sign-in is refused with a signature error that reads like a certificate problem. Unchecking it restores a signed assertion and the sign-ins pass.
Identify members by their email address
Set Name ID format to EMAIL. Google's other formats do not work with Bird:
- UNSPECIFIED is refused outright.
- PERSISTENT is refused because the format does not match the one the connection expects. Google sends the member's email address as the value regardless, so it is not the opaque, never-reassigned identifier a persistent format is meant to carry.
Google offers no opaque identifier for the NameID, so EMAIL is the only usable choice here. That makes the address permanent for anyone who signs in through this connection: if your organization ever reassigns it, the next person given it inherits the Bird account. Read How members are identified before you rely on it.
Assertion validity and certificates
Google signs assertions valid from five minutes before issue to five minutes after, which Bird accepts.
Google manages the signing certificate and its expiry date, and gives you no rotation control on a custom SAML app. Note the expiry shown on the Bird connection and plan to replace the metadata before it passes, because every sign-in through the connection fails on the day it does.
OIDC
Start in the Google Cloud console for OIDC. Bird needs the issuer, client ID and client secret to create an OIDC connection, so register the application at Google first. Bird's Redirect URI is the same for every connection and is shown in Add connection before you create anything, so you can register it up front.
Create OAuth client credentials in the Google Cloud console for the project that serves your Workspace users, and copy the client ID and secret into Bird with https://accounts.google.com as the Issuer. Bird reads the discovery document from there and authenticates to the token endpoint with client_secret_basic.
Register Bird's Redirect URI as an authorized redirect URI on the client.
Google's OIDC path has no app-tile step: a custom OAuth client does not appear in the Google apps launcher, so members start from Bird's sign-in page or from a link you give them.
Next steps
- SSO and provisioning: verify a domain, test the connection, and require SSO
- Set up SSO with Okta
- Set up SSO with Microsoft Entra ID
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.
Pahami konsepnyaShould I use an API key or an OAuth token, and how do I rotate one?Panduan implementasiAuthentication & API keys
Dapatkan ringkasan implementasi