Skip to main content

Microsoft Entra ID (Azure AD)

You need a Microsoft Entra admin (Application Administrator or higher) and a Handbooks workspace admin.

1. Create the app in Microsoft Entra​

  1. In the Microsoft Entra admin center, go to Enterprise apps → New application → Create your own application.

  2. Name it Handbooks, choose Integrate any other application you don't find in the gallery (Non-gallery) and click Create.

  3. Open Single sign-on and choose SAML.

  4. Under Basic SAML Configuration, click Edit and enter:

    FieldValue
    Identifier (Entity ID)https://handbooks.io
    Reply URL (Assertion Consumer Service URL)https://www.handbooks.io/api/auth/saml/callback/
    Sign on URLhttps://www.handbooks.io/login/sso/ (optional)

    Save.

  5. Under Attributes & Claims, the defaults work: Handbooks reads the email address, given name and surname claims. If your users' sign-in name (UPN) differs from their email address, set Unique User Identifier (Name ID) to user.mail.

  6. Under SAML Certificates, download Certificate (Base64).

  7. Under Users and groups, assign the people or groups that should use Handbooks.

2. Add Microsoft's details to Handbooks​

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

Handbooks fieldFrom Microsoft Entra
SP Entity IDkeep https://handbooks.io
IdP Entity ID (Issuer)Microsoft Entra Identifier (under Set up Handbooks)
IdP SSO URLLogin URL (under Set up Handbooks)
X.509 Signing Certificatethe contents of the Certificate (Base64) file

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. Opening Handbooks from My Apps works too.

Entra signing certificates expire after 3 years by default. Before yours expires, create a new one, paste it into Handbooks and email us to reactivate SSO. See troubleshooting if sign-in fails.

4. Sync users automatically (optional)​

Once SSO works, Microsoft Entra can add and remove Handbooks members for you with SCIM:

  1. In Handbooks, go to Workspace settings → SSO SAML, turn on SCIM provisioning, open SCIM 2.0 Provisioning and click Generate token. Copy the token.

  2. In the Handbooks enterprise app in Entra, open Provisioning, click Get started (or New configuration) and choose Automatic.

  3. Under Admin Credentials, enter:

    FieldValue
    Tenant URLhttps://www.handbooks.io/api/scim/v2
    Secret Tokenthe token from step 1

    Click Test Connection, then Save.

  4. Under Mappings, turn off Provision Microsoft Entra ID Groups. In Provision Microsoft Entra ID Users, keep userName as the matching attribute and make sure emails[type eq "work"].value maps to the user's email (mail).

  5. Under Settings, set Scope to Sync only assigned users and groups, set Provisioning Status to On and save. Entra syncs about every 40 minutes; use Provision on demand to test one person straight away.