Okta

You need an Okta admin and a Handbooks workspace admin.

1. Create the app in Okta

1. In the Okta Admin Console, go to Applications → Applications → Create App Integration, choose SAML 2.0 and click Next.

2. Name it Handbooks and click Next.

3. Under SAML Settings, enter:

   Field	Value
   Single sign-on URL	https://www.handbooks.io/api/auth/saml/callback/
   Use this for Recipient URL and Destination URL	checked
   Audience URI (SP Entity ID)	https://handbooks.io
   Name ID format	EmailAddress
   Application username	Email

4. Under Attribute Statements, add:

   Name	Value
   email	user.email
   firstName	user.firstName
   lastName	user.lastName

5. Click Next, choose that this is an internal app, and click Finish.

6. On the app's Assignments tab, assign the people or groups that should use Handbooks.

2. Add Okta's details to Handbooks

Open the app's Sign On tab. Newer Okta shows the values under SAML 2.0 → Metadata details; older Okta shows them after you click View SAML setup instructions. In Handbooks, go to Workspace settings → SSO SAML → Configure SSO and enter:

Handbooks field	From Okta
SP Entity ID	keep https://handbooks.io
IdP Entity ID (Issuer)	Issuer (or Identity Provider Issuer)
IdP SSO URL	Sign on URL (or Identity Provider Single Sign-On URL)
X.509 Signing Certificate	Signing Certificate (or X.509 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. Opening Handbooks from the Okta dashboard works too. See troubleshooting if sign-in fails.

4. Sync users automatically (optional)

Once SSO works, Okta 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 Okta, open the Handbooks app's General tab, click Edit under App Settings, set Provisioning to SCIM and save.

3. On the new Provisioning tab, click Edit under SCIM Connection and enter:

   Field	Value
   SCIM connector base URL	https://www.handbooks.io/api/scim/v2
   Unique identifier field for users	userName
   Supported provisioning actions	Push New Users and Push Profile Updates
   Authentication Mode	HTTP Header, with the token from step 1

   Click Test Connector Configuration, then Save.

4. Under Provisioning → To App, click Edit, enable Create Users, Update User Attributes and Deactivate Users, and save.

5. Leave Push Groups off. People assigned to the app are now added to your workspace; unassigning or deactivating them disables their membership.