|
| 1 | +--- |
| 2 | +title: Directory provisioning (SCIM) |
| 3 | +description: Create, update, and deactivate Sim members automatically from your identity provider |
| 4 | +--- |
| 5 | + |
| 6 | +import { Callout } from 'fumadocs-ui/components/callout' |
| 7 | +import { Step, Steps } from 'fumadocs-ui/components/steps' |
| 8 | +import { Tab, Tabs } from 'fumadocs-ui/components/tabs' |
| 9 | +import { FAQ } from '@/components/ui/faq' |
| 10 | + |
| 11 | +Directory provisioning connects your identity provider to Sim over SCIM 2.0. Your provider creates members when someone joins, updates them when their details change, and deactivates them the moment they leave — without anyone touching Sim. |
| 12 | + |
| 13 | +It pairs with [SSO](/platform/enterprise/sso). SSO proves who someone is when they sign in. Directory provisioning decides who exists and what they can reach, before and after that. |
| 14 | + |
| 15 | +<Callout type="info"> |
| 16 | + Included with Enterprise plans. Requires [SSO](/platform/enterprise/sso) to be enabled, because provisioning is configured from the SSO settings page, and at least one [verified domain](/platform/enterprise/verified-domains) for your organization. Self-hosted deployments get it with the other enterprise features through `ENTERPRISE_ENABLED=true`, or turn just this feature on or off with `SCIM_ENABLED` and `NEXT_PUBLIC_SCIM_ENABLED`, alongside the [SSO variables](/platform/enterprise/sso#self-hosted-setup). |
| 17 | +</Callout> |
| 18 | + |
| 19 | +## What it does |
| 20 | + |
| 21 | +| Your provider does this | Sim does this | |
| 22 | +| --- | --- | |
| 23 | +| Assigns a person to the Sim app | Creates their account and adds them to your organization as a Member | |
| 24 | +| Updates their name or email | Updates the Sim account, and ends their sessions if the address changed | |
| 25 | +| Deactivates them | Blocks sign-in and stops their personal API keys. Everything they own, and every grant they hold, is left untouched; shared workspace keys keep working | |
| 26 | +| Reactivates them | Restores access exactly as it was | |
| 27 | +| Removes them from the app | Removes their organization membership, ends their sessions, deletes their personal API keys, and reassigns what they owned | |
| 28 | +| Adds them to a group | Grants whatever that group maps to | |
| 29 | + |
| 30 | +Deactivation is reversible and never destructive. Someone on leave keeps their workflows, their credentials, and their workspace history; they simply cannot sign in. |
| 31 | + |
| 32 | +## Turn it on |
| 33 | + |
| 34 | +<Steps> |
| 35 | + |
| 36 | +<Step> |
| 37 | +### Verify your domain |
| 38 | + |
| 39 | +Sim only provisions people whose email is in a domain your organization has verified. See [Verified domains](/platform/enterprise/verified-domains). |
| 40 | + |
| 41 | +This is what stops another tenant's directory from claiming an address it does not own. |
| 42 | +</Step> |
| 43 | + |
| 44 | +<Step> |
| 45 | +### Enable directory provisioning |
| 46 | + |
| 47 | +In **Settings → SSO → Directory provisioning**, turn it on. Sim shows your SCIM base URL: |
| 48 | + |
| 49 | +``` |
| 50 | +https://<your-sim-domain>/api/scim/v2 |
| 51 | +``` |
| 52 | +</Step> |
| 53 | + |
| 54 | +<Step> |
| 55 | +### Issue a token |
| 56 | + |
| 57 | +Choose whether the token expires (never, 90 days, or a year) and select **Issue token**. It appears once — copy it straight into your provider. |
| 58 | + |
| 59 | +Two tokens can be active at a time, so you can rotate without downtime: issue the new one, update your provider, confirm a sync succeeds, then revoke the old one. |
| 60 | +</Step> |
| 61 | + |
| 62 | +<Step> |
| 63 | +### Configure your provider |
| 64 | + |
| 65 | +<Tabs items={['Okta', 'Microsoft Entra ID', 'OneLogin', 'JumpCloud']}> |
| 66 | +<Tab value="Okta"> |
| 67 | + |
| 68 | +In your Okta app, open **Provisioning → Integration** and select **Configure API Integration**. |
| 69 | + |
| 70 | +- **SCIM connector base URL**: `https://<your-sim-domain>/api/scim/v2` |
| 71 | +- **Unique identifier field for users**: `userName` |
| 72 | +- **Supported provisioning actions**: Push New Users, Push Profile Updates, Push Groups |
| 73 | +- **Authentication Mode**: HTTP Header, with your Sim token |
| 74 | + |
| 75 | +Select **Test API Credentials**, then save. Under **Provisioning → To App**, enable Create Users, Update User Attributes, and Deactivate Users. |
| 76 | + |
| 77 | +Okta never deletes users over SCIM. Unassigning someone, or deactivating them in Okta, sends a deactivation — which Sim applies as a suspension. |
| 78 | + |
| 79 | +</Tab> |
| 80 | +<Tab value="Microsoft Entra ID"> |
| 81 | + |
| 82 | +In your enterprise application, open **Provisioning** and set Provisioning Mode to **Automatic**. |
| 83 | + |
| 84 | +- **Tenant URL**: `https://<your-sim-domain>/api/scim/v2` |
| 85 | +- **Secret Token**: your Sim token |
| 86 | + |
| 87 | +Select **Test Connection**, then save and start provisioning. |
| 88 | + |
| 89 | +Entra runs an initial cycle over everyone in scope, then incremental cycles roughly every 40 minutes. Removing someone from the app sends a deactivation; a permanent delete in Entra sends a removal about 30 days later. |
| 90 | + |
| 91 | +</Tab> |
| 92 | +<Tab value="OneLogin"> |
| 93 | + |
| 94 | +Add a **SCIM Provisioner with SAML** app. |
| 95 | + |
| 96 | +- **SCIM Base URL**: `https://<your-sim-domain>/api/scim/v2` |
| 97 | +- **SCIM Bearer Token**: your Sim token |
| 98 | + |
| 99 | +Enable provisioning and choose what happens when a user is removed. Suspend maps to a Sim suspension; Delete removes their membership. |
| 100 | + |
| 101 | +</Tab> |
| 102 | +<Tab value="JumpCloud"> |
| 103 | + |
| 104 | +Add a **Custom SCIM** identity management integration. |
| 105 | + |
| 106 | +- **Base URL**: `https://<your-sim-domain>/api/scim/v2` |
| 107 | +- **Token Key**: your Sim token |
| 108 | + |
| 109 | +Enable group sync if you plan to map groups. |
| 110 | + |
| 111 | +</Tab> |
| 112 | +</Tabs> |
| 113 | +</Step> |
| 114 | + |
| 115 | +<Step> |
| 116 | +### Map your groups |
| 117 | + |
| 118 | +Groups mean nothing to Sim until you say what they stand for. In **Settings → SSO → Directory provisioning → Group mappings**, point each pushed group at one or more of: |
| 119 | + |
| 120 | +- a **permission group**, which governs models, integrations, and capabilities |
| 121 | +- a **workspace**, at Read, Write, or Admin |
| 122 | +- the **organization admin role** |
| 123 | + |
| 124 | +A group can carry several mappings. When two groups grant the same workspace at different levels, the stronger one wins. The organization's default permission group cannot be a target: it governs by having no members. |
| 125 | + |
| 126 | +Turning on **Match permission groups by name** maps a pushed group to an existing permission group of the same name automatically, and remaps it when the group is renamed. Nothing is created. |
| 127 | + |
| 128 | +Mapping a permission group to a directory group switches that permission group to explicit membership permanently: it governs exactly the people in it, and an empty group governs nobody. A permission group that governed everyone in its workspaces stops doing so the moment it is mapped, so map groups you created for the directory rather than your organization-wide ones. |
| 129 | + |
| 130 | +</Step> |
| 131 | + |
| 132 | +</Steps> |
| 133 | + |
| 134 | +## How access is withdrawn |
| 135 | + |
| 136 | +Sim records every grant it makes on your behalf. When someone leaves a group, what the directory granted is taken back. |
| 137 | + |
| 138 | +**Managed membership locking**, on by default, makes the directory the source of truth for provisioned members: Sim refuses invitations, workspace grants, workspace role changes, and organization role changes for them, because the next sync would revert them anyway. Access a member already held by hand when a mapping started covering it counts as directory access from then on, so it is withdrawn with the mapping. Removals stay possible so an administrator can always act in an emergency. |
| 139 | + |
| 140 | +With locking off, manual access layers on top of directory access: access granted by hand stays when a group is left, and a workspace role raised by hand above what the directory set is left alone. |
| 141 | + |
| 142 | +## Provisioning and SSO together |
| 143 | + |
| 144 | +A member the directory created can sign in with SSO immediately; the two resolve to the same account through your verified domain. |
| 145 | + |
| 146 | +If you want the directory to be the only way in, enable **Disable just-in-time provisioning** in the connection settings. Sim then refuses to create membership for someone signing in who was never provisioned. |
| 147 | + |
| 148 | +## Watching a sync |
| 149 | + |
| 150 | +**Settings → SSO → Directory provisioning → Activity** lists recent authenticated requests with their status and, for a failure, what was wrong. Providers report a failed cycle without saying what they sent, so this is usually the fastest way to see the cause. A request that fails to authenticate has no connection to log against, so a wrong or revoked token shows up only as your provider's own authentication error. |
| 151 | + |
| 152 | +Sim also re-applies every group mapping once an hour, so drift cannot persist. You can run it on demand with **Reconcile now**, which is also how a change to the connection settings reaches members before the next sync. |
| 153 | + |
| 154 | +## Reference |
| 155 | + |
| 156 | +- Base URL: `https://<your-sim-domain>/api/scim/v2` |
| 157 | +- Authentication: `Authorization: Bearer <token>` |
| 158 | +- Resources: `/Users`, `/Groups`, plus `/ServiceProviderConfig`, `/ResourceTypes`, and `/Schemas` |
| 159 | +- Filters: `eq` only, up to ten terms joined with `and`. Users: `id`, `userName`, `externalId`, `emails.value` (also `emails[type eq "work"].value`), `active`. Groups: `id`, `displayName`, `externalId` |
| 160 | +- Limits: 1,500 requests per minute per connection, 1 MB per request, 5,000 members per group |
| 161 | +- `userName` is stored and returned lower-cased; top-level attributes and schema extensions Sim does not model (custom attributes included) are kept and returned as sent, and a PUT preserves ones it omits |
| 162 | +- Group display names are unique within a connection, ignoring case |
| 163 | +- Page size: up to 100 per request |
| 164 | + |
| 165 | +<FAQ items={[ |
| 166 | + { |
| 167 | + question: "What happens to someone's workflows when they are deactivated?", |
| 168 | + answer: "Nothing. A deactivation blocks sign-in and stops their personal API keys, and leaves every workspace, workflow, and credential they own exactly as it was. Reactivating them restores access. Only a removal — which your provider sends explicitly — reassigns what they owned. A deactivated member also keeps their seat until they are removed." |
| 169 | + }, |
| 170 | + { |
| 171 | + question: "Can the directory provision someone outside our verified domains?", |
| 172 | + answer: "No. Sim refuses to create or move an account to an address whose domain your organization has not verified. This is what prevents one tenant's directory from claiming an account it does not own." |
| 173 | + }, |
| 174 | + { |
| 175 | + question: "What if the email already belongs to a Sim account?", |
| 176 | + answer: "If the account is in your organization, or in none, Sim attaches to it. If it belongs to a different organization, Sim returns a conflict — a Sim account can belong to only one organization, so someone has to be removed there first." |
| 177 | + }, |
| 178 | + { |
| 179 | + question: "Can the directory remove our organization owner?", |
| 180 | + answer: "No. Sim refuses, because it would leave nobody able to administer billing or transfer ownership. Transfer ownership in Sim first." |
| 181 | + }, |
| 182 | + { |
| 183 | + question: "What happens when we run out of seats?", |
| 184 | + answer: "Sim refuses the new member with a message your provider shows to its administrator. Add seats in Sim and the next sync will pick them up. Team plans grow their seat count automatically; fixed-seat plans do not." |
| 185 | + }, |
| 186 | + { |
| 187 | + question: "Does a deactivation sign someone out immediately?", |
| 188 | + answer: "Their sessions are deleted at once and their personal API keys stop authenticating immediately. The organization's security version changes at the same time, so a browser still holding a cached session cookie is re-checked on its next request and refused." |
| 189 | + }, |
| 190 | + { |
| 191 | + question: "What happens to deactivated members if we turn provisioning off?", |
| 192 | + answer: "They stay deactivated. Disabling the connection stops the directory from making changes; it does not undo the ones it made. To restore someone without the directory, remove them from the organization and invite them again." |
| 193 | + }, |
| 194 | + { |
| 195 | + question: "Can we still invite people manually?", |
| 196 | + answer: "Only with managed membership locking turned off. With it on, Sim refuses manual changes for provisioned members, because the directory would revert them on its next sync." |
| 197 | + } |
| 198 | +]} /> |
0 commit comments