Google Workspace

You need a Google Workspace super admin and a Handbooks workspace admin.

1. Create the app in Google

1. In the Google Admin console, go to Apps → Web and mobile apps → Add app → Add custom SAML app.

2. Name it Handbooks and click Continue.

3. On Google Identity Provider details, keep this page open (or download the certificate). You'll copy three values into Handbooks:

   • SSO URL
   • Entity ID
   • Certificate

   Click Continue.

4. On Service provider details, enter:

   Field	Value
   ACS URL	https://www.handbooks.io/api/auth/saml/callback/
   Entity ID	https://handbooks.io
   Start URL	leave empty
   Signed response	optional (either works)
   Name ID format	EMAIL
   Name ID	Basic Information → Primary email

   Click Continue.

5. On Attribute mapping, add (optional, so names show in Handbooks):

   Google Directory attribute	App attribute
   First name	firstName
   Last name	lastName

   Click Finish.

6. Open the new app, click User access, and turn it ON for everyone (or for the organizational units or groups that should use Handbooks). Google apps are off by default; until this is on, Google shows a "403 app_not_configured_for_user" error. Changes can take a few minutes to apply.

2. Add Google's details to Handbooks

In Handbooks, go to Workspace settings → SSO SAML → Configure SSO and enter:

Handbooks field	From Google
SP Entity ID	keep https://handbooks.io
IdP Entity ID (Issuer)	Entity ID (https://accounts.google.com/o/saml2?idpid=…)
IdP SSO URL	SSO URL (https://accounts.google.com/o/saml2/idp?idpid=…)
X.509 Signing Certificate	the whole Certificate, including the BEGIN and END lines

Add your company email domain under Allowed email domains, save, and email [email protected] to activate SSO.

3. Test

Once we confirm SSO is active, go to the Handbooks login page, choose Continue with SAML SSO and enter your work email. You can also open Handbooks from the Google apps menu.

Google Workspace can't sync users to custom SAML apps (SCIM), so people are added to your Handbooks workspace when they first sign in.

Google's certificate is valid for 5 years. Before it expires, add the new one in Google, paste it into Handbooks and email us to reactivate SSO. See troubleshooting if sign-in fails.