Directory sync (SCIM)

Directory sync lets your company’s directory tell ZestSSH who joins, who leaves and which groups they are in. It works with Microsoft Entra ID, Okta and any other directory that speaks SCIM 2.0.

The directory can only take access away by itself. Everything that gives access, such as inviting someone or a higher role, waits for an owner or admin, who confirms it on their own device with the team’s usual signed changes. Neither your directory nor ZestSSH Cloud can sign those.

Before you start

You are an owner. Only owners turn directory sync on, make tokens, map groups and turn it off.
The team has Business, active. On a computer, an owner gets it from the Seats page: Buy seats opens zestssh.com, where Business is too. For what it costs, see Seats and Business.
The team has at least one proven domain. Directory sync speaks only for addresses at proven domains. See Prove a domain.
In your directory, each person’s userName is the address they use for their ZestSSH account. ZestSSH matches people by that address and nothing else.

Turning directory sync on, making a new token, mapping a group and turning it off each need a sign-in from the last ten minutes. If ZestSSH asks you to Confirm it’s you, choose Sign in again.

Turn it on

Open the team’s Sign-in page. On a computer: Team in the rail, then Sign-in. On a phone: More, the team under Team, then Sign-in.
In step 3, Directory sync (SCIM), choose Turn on directory sync. The step stays locked until a domain is proven, and shows Needs Business while the team has no Business.
Your directory’s token shows two values. Copy both into your directory’s SCIM settings now. The token is shown only this once.
- SCIM base URL: it ends with /scim/v2/ and your team’s id.
- Token (bearer): your directory sends it as a bearer token.
Choose I saved it.

The section then reads On. Your directory has not been in touch yet. Once the directory calls, it reads On. Last heard from your directory with the date and time, to the minute.

If you see Prove a domain first: directory sync speaks only for your proven domains., prove a domain first.

Set up your directory

In your directory’s provisioning (SCIM) settings, enter the SCIM base URL as the address and the token as the bearer token. Then assign the people and groups to send.

What ZestSSH reads:

From	What it keeps
Users	userName (the address, kept in lower case), active, and externalId (the directory’s own id)
Groups	displayName and the members

Everything else your directory sends, such as names, other email fields or the enterprise extension, is ignored. Only people at the team’s proven domains count. Others are kept as the directory sent them and change nothing in the team.

Map groups to roles

Groups arrive under Groups, each with how many people are in it, such as “Platform (12 people)”. A new group maps to no role, so it changes nothing yet.

For each group, pick a role: No role, Admin, or a role the owners made. A group never maps to Owner.

When a group’s role changes, ZestSSH looks at its members again and queues what the new role calls for. It never applies it by itself. Someone in several mapped groups is given the highest of their roles.

What the directory does by itself

When your directory turns a user off (active false) or deletes them, ZestSSH Cloud holds back the member at that address at once:

ZestSSH Cloud refuses everything they ask of the team and its vaults. Nothing new reaches them, and nothing they change reaches the team.
Their banner says: “Your company’s directory holds you back from Northwind Ops. What’s on this device stays, but nothing syncs until the directory or an owner lets you back in.” The team’s line in the switcher reads Team · Held back by the directory.
Their other teams carry on as before.
They can still leave the team.
A Remove change waits under Directory changes for an owner or admin.

The member is listed under Held back by the directory until one of these happens: the directory turns them on again, an owner or admin removes them, or directory sync is turned off.

Owners are never held back, and no change ever waits for an owner.

A hold stops what reaches the member from then on. It does not take back what is already on their devices. Removing them does: “Their devices take this team off at their next sync, and the keys they held are replaced so nothing written from now on opens with them.” See Suspend, remove and leave.

What waits for a person

Every other change waits under Directory changes, for an owner or admin to act on:

Change	When it is queued	Button
Invite address as role	Someone at a proven domain who is not in the team is in a mapped group.	Invite
Give address the role role	A member’s mapped groups give a higher role than the one they have.	Change role
Move address down to role	A member’s mapped groups give a lower role than the one they have.	Change role
Remove address (held back until then)	The directory turned the user off or deleted them.	Remove

Invite sends the team’s usual invitation. You compare the person’s keys when they accept, as with any invitation.
Until someone acts on a move down, the member keeps the role they have. ZestSSH Cloud holds back only members the directory turned off or deleted.
Acting on a change uses the team’s usual signed changes, so your own role limits what you can do, as it does anywhere else. After a change that takes access away, ZestSSH replaces the keys the person held, as far as you may. Anything left shows Replace keys on the team’s banner.
Set aside removes a change without doing it.
A change about you is for another owner or admin to deal with.
When you open the list, ZestSSH sets aside changes the team’s signed record already reflects, such as a member someone already removed.
One change waits per member, and one per address outside the team. A newer one replaces it.

The Sign-in page is for owners. Admins, and owners too, see waiting changes on the Team Overview under Needs attention, as Your company’s directory asks for a number of changes, with Review.

Make a new token

Choose New token, then confirm Make a new token?. The old token stops working at once. Paste the new one into your directory’s settings: it is shown only this once.

Turn it off

Choose Turn off and confirm Turn off directory sync?. What the directory sent is forgotten, and anyone it held back is let back in. Members stay as they are. You see Directory sync is off. Turning it off does not need Business.

What ZestSSH keeps

Only what directory sync needs: for each user, the directory’s id, the address and whether it is active; for each group, its name, its members and the role an owner mapped it to; and one “last heard” time for the whole connection, to the minute. No names, no times per user or per change, and nothing about the requests themselves.

The token is kept only as a keyed hash, so a copy of the database cannot be turned into a token that works.

Limits

Up to 5,000 users, 500 groups and 50,000 group memberships per team.
Lists come in pages of up to 100. Filters take one form, attribute eq "value": on userName, externalId or id for users, and on displayName, externalId or id for groups.
Users can be replaced with PUT, as Okta does, or changed with PATCH, as Entra ID does. Bulk operations, sorting and ETags are not supported.
At most 600 requests a minute per team.
If Business lapses, directory sync keeps working for 14 days after the paid time ends. After that, ZestSSH Cloud refuses the directory’s requests with Directory sync is part of Business, which is not active for this team.

What directory sync does not do

It adds nobody by itself and raises nobody’s role. It only queues those changes.
It never changes owners.
Taking someone out of every mapped group changes nothing. To take their access away, turn the user off or delete them in your directory.
It speaks only for proven domains. People at other domains, such as guests, are left as they are.
It does not sign anyone in. For that, see Company sign-in (SSO).

Next steps

Company sign-in (SSO): prove domains and let members sign in with their work accounts.
Team rules: what members need to keep syncing.
Suspend, remove and leave: take access away and replace the keys.