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.
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 field | Becomes |
|---|---|
| Primary email | The person's email (people already in vastframe keep their id when the email matches). Users without an email are skipped. |
| First and last name | Display name |
Custom attribute department | Department |
Custom attribute job_title | Job title |
Custom attribute manager_email | Manager (matched by email) |
User state (active or not) | Account on or off. Leavers flow into the project lifecycle. |
| Groups | Groups (ids start with wg_) |
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
- Open Admin › Sign-in.
- 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
- Next to Identity provider, select Set up single sign-on. The Admin Portal opens in a new tab.
- 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.
- When the portal confirms the connection, return to vastframe.
Step 3: Connect your directory (optional)
- Next to Directory sync, select Connect directory. The Admin Portal opens on directory setup.
- Follow the steps to create a SCIM connection in your directory and assign users and groups.
- 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
- In a private window, open
https://console.<your-org-domain>. You should be redirected to your identity provider. - Sign in as a member; you land in the console.
- With a directory connected, open Admin › People: it lists your directory users and is read-only.
- Check Admin › Audit log for
sign-in.updateandsign-in.directory-sync.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Enterprise SSO is greyed out: "Not enabled on this installation" | SSO isn't configured for the installation | Contact your vastframe administrator. |
| "Enterprise SSO is not in the … plan" | The licence lacks SSO | Upgrade the plan. |
| "Single sign-on is not set up for this organization yet" at sign-in | SSO is on but no identity provider is connected | Finish step 2, or use emergency access. |
| "No directory is connected yet" on Sync now | The directory isn't linked in the portal | Finish step 3 in the portal. |
| "This sign-in belongs to another organization" | The SSO profile is from a different organization | Check the connection in the portal. |
| A person has no manager or department | The directory doesn't send the custom attributes | Map department, job_title and manager_email in your directory's SCIM settings. |
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.