SAML single sign-on

Workspace admins can let their team sign in to Handbooks with their company identity provider (IdP): Google Workspace, Okta, Microsoft Entra ID (Azure AD) or any other SAML 2.0 provider.

Setup guides

• Google Workspace
• Okta
• Microsoft Entra ID (Azure AD)

Using another provider? Create a SAML 2.0 app with the values below and copy its issuer, sign-in URL and signing certificate into Handbooks.

Values for your identity provider

Setting in your IdP	Value
ACS URL / Reply URL / Single sign-on URL	https://www.handbooks.io/api/auth/saml/callback/
Entity ID / Audience / Identifier	https://handbooks.io
Name ID	The user's email address
Signing	Sign the assertion or the response with SHA-256
Encryption	Off (encrypted assertions aren't supported)

Handbooks also reads these attributes if your IdP sends them: email, firstName, lastName (or name). Without a name, the part of the email before the @ is used.

How it works

1. In your IdP, create a SAML app for Handbooks with the values above and give your team access to it.
2. In Handbooks, go to Workspace settings → SSO SAML → Configure SSO. Paste your IdP's Entity ID (Issuer), SSO URL and X.509 signing certificate, add your company email domain (for example acme.com) and save.
3. Email [email protected] to activate SSO. We confirm your email domain and turn SSO on for your workspace.
4. Sign in: on the Handbooks login page, choose Continue with SAML SSO and enter your work email. Opening the Handbooks app from your IdP's app list works too.

People with your email domain who sign in through your IdP join your workspace as members. Your existing password and Google sign-ins keep working.

Require SSO (optional)

Once SSO works, an admin can turn on Force SSO in the SSO settings. People with your email domain can then only sign in through your IdP. Test SSO with at least one account before turning it on.

Changing your settings

Changing your IdP details in the SSO settings (certificate, SSO URL or entity IDs) turns SSO off until the Handbooks team reactivates it, so a changed IdP is always checked. Email [email protected] before your IdP's certificate expires. A new email domain also needs our confirmation before it works. Turning Force SSO on or off doesn't need us.

Troubleshooting

Message on the login page	What to check
No SSO is configured for this email domain, or No SSO configuration found	SSO isn't activated yet, or your email domain isn't confirmed for the workspace.
The SSO request could not be validated	The ACS URL or Entity ID in your IdP doesn't match the values above, or the sign-in took longer than 10 minutes. Start again from the Handbooks login page.
The SAML response came from an unrecognised identity provider	The IdP Entity ID (Issuer) in Handbooks doesn't match your IdP's.
The SAML response signature could not be verified	The certificate in Handbooks isn't your IdP's current signing certificate, or your IdP signs with SHA-1 instead of SHA-256.
Your identity is not allowed to access this SSO workspace	The email your IdP sent isn't on your workspace's verified domain, or the account is disabled in the workspace.
Your identity provider did not send required user attributes	Your IdP didn't send an email address. Set the Name ID to the user's email.

Still stuck? Email [email protected] with the time you tried to sign in.