Skip to main content

Enterprise SSO (SAML) and directory sync (SCIM)

Overview​

Enterprise SSO connects any SAML identity provider (Okta, Ping, ADFS, Microsoft Entra ID and others) and, optionally, a SCIM directory that keeps people and groups up to date. Your IT team sets up the identity provider and directory themselves in a guided Admin Portal, provided through vastframe's SSO partner, WorkOS.

Plan requirement

Enterprise SSO needs WorkOS to be enabled on the installation. If your organization has a licence, its plan must also include SSO; otherwise saving shows "Enterprise SSO is not in the … plan." Check Admin › License under Included, and contact vastframe to upgrade.

Prerequisites​

  • Org Admin in vastframe.
  • On a licensed organization, a plan that includes SSO.
  • Admin access to your identity provider (and to your directory, for SCIM).
  • Recommended: a verified email domain. Verified domains are added to your SSO organization when you turn SSO on.

What directory sync brings in​

Directory sync is a source for Org Sync. Directory users become people and directory groups become groups, so roles, delegated scopes, access rules and the org chart work as they do for Entra ID organizations.

Directory fieldBecomes
Primary emailThe person's email (people already in vastframe keep their id when the email matches). Users without an email are skipped.
First and last nameDisplay name
Custom attribute departmentDepartment
Custom attribute job_titleJob title
Custom attribute manager_emailManager (matched by email)
User state (active or not)Account on or off. Leavers flow into the project lifecycle.
GroupsGroups (ids start with wg_)
warning

With a directory connected, Admin › People and Groups become read-only. Change people in your directory; sync picks it up.

Setup steps​

Step 1: Turn on enterprise SSO​

  1. Open Admin › Sign-in.
  2. Select Enterprise SSO, then Turn on enterprise SSO.

If the option says "Not enabled on this installation", SSO isn't configured for your installation. Contact your vastframe administrator.

Step 2: Connect your identity provider​

  1. Next to Identity provider, select Set up single sign-on. The Admin Portal opens in a new tab.
  2. Follow the portal's steps for your provider. It gives you the values to enter there (such as the ACS URL and entity ID) and asks for your provider's metadata.
  3. When the portal confirms the connection, return to vastframe.

Step 3: Connect your directory (optional)​

  1. Next to Directory sync, select Connect directory. The Admin Portal opens on directory setup.
  2. Follow the steps to create a SCIM connection in your directory and assign users and groups.
  3. Back in vastframe, select Sync now. People and groups appear in Admin › People within a minute.

Directory sync shows Connected once a directory is linked. Use Manage to change it later.

Verify​

  1. In a private window, open https://console.<your-org-domain>. You should be redirected to your identity provider.
  2. Sign in as a member; you land in the console.
  3. With a directory connected, open Admin › People: it lists your directory users and is read-only.
  4. Check Admin › Audit log for sign-in.update and sign-in.directory-sync.

Troubleshooting​

SymptomCauseFix
Enterprise SSO is greyed out: "Not enabled on this installation"SSO isn't configured for the installationContact your vastframe administrator.
"Enterprise SSO is not in the … plan"The licence lacks SSOUpgrade the plan.
"Single sign-on is not set up for this organization yet" at sign-inSSO is on but no identity provider is connectedFinish step 2, or use emergency access.
"No directory is connected yet" on Sync nowThe directory isn't linked in the portalFinish step 3 in the portal.
"This sign-in belongs to another organization"The SSO profile is from a different organizationCheck the connection in the portal.
A person has no manager or departmentThe directory doesn't send the custom attributesMap department, job_title and manager_email in your directory's SCIM settings.
Availability

Enterprise SSO is built and tested against a local WorkOS stand-in; connecting a real WorkOS account is the next step. It's available to vastframe cloud organizations. A self-hosted installation signs in with its own Entra ID and doesn't offer this option.

Was this page helpful?