How to set up Enterprise SSO and directory sync

By the end of this guide, your organization will have SAML-based Single Sign-On and, optionally, SCIM directory sync configured so your team can access Heroic Cloud through your corporate identity provider.

Prerequisites #

  • Organization Owner access.
  • Access to your identity provider’s SAML configuration.
  • Access to DNS records for your email domains.

Steps #

  1. Navigate to Organization > Overview and locate the Enterprise Single Sign-On section.
  2. Add your email domains (separate multiple domains with commas) and select Add Domains.
  3. Add the provided TXT record to each domain’s DNS records. Records may take up to 48 hours to propagate. Once verified, the domain shows a Verified badge.
  4. Select Reconfigure your SSO to set up or update your SAML connection. Once configured, the section shows a Configured badge.

Verify #

Your domains show a Verified badge and the SSO section shows a Configured badge. Have a team member sign in using SSO credentials to confirm they reach the dashboard.

Enterprise SSO configured on the Organization Overview page
Enterprise SSO configured on the Organization Overview page

Setting up directory sync (SCIM) #

Steps #

  1. In the SSO section on the Organization Overview page, select Directory Sync Setup to configure SCIM integration. Once configured, a Configured badge appears.
  2. Navigate to the Teams page and select Import Directory Groups to pull groups from your identity provider.
  3. Imported groups appear as teams with a Directory Group badge. Assign permissions to these teams.

Verify #

Imported groups appear on the Teams page with a “Directory Group” badge. A user from one of those groups can sign in and immediately see the resources their team has access to.

Troubleshooting #

  • Domain not verifying: Confirm the TXT record is correct and published. Allow up to 48 hours for DNS propagation.
  • Users not landing with correct permissions: Verify the directory group is imported to the Teams page and that the corresponding team has permissions assigned.
  • User removed from directory but still has access: Remove them from your identity provider to block authentication, then delete their Heroic Cloud account from the Users page to fully clean up.
  • SSO not working after configuration: Confirm the SAML connection shows a Configured badge. Double-check your identity provider’s SAML metadata URL and certificate.

Notes #

These features are powered by WorkOS — a SOC 2 compliant, enterprise-grade identity and management system.

See also #