Directory Sync

Directory sync helps organizations automate the provisioning and de-provisioning of their users. It is based on the System for Cross-domain Identity Management (SCIM) protocol.

As a result, it streamlines the user lifecycle management process by saving valuable organizational hours, creating a single truth source of the user identity data, and facilitating them to keep the data secure.

Directory Sync is part of the Ory Polis service (and npm library) from v1.2.1 onwards. Follow the instructions in Ory Polis for details on deployment. Or check out Ory Polis on GitHub.

We currently only support SCIM 2.0 protocol because SCIM 1.1 is deprecated and support will be discontinued on December 2nd, 2022. If you still need support for SCIM 1.1 and are unable to move away from it then please contact us.

caution

Directory sync does not work on DynamoDB for directories with more than DB_PAGE_LIMIT users or groups. SCIM pages through a directory with a startIndex, and DynamoDB cannot skip records, so an identity provider reads the first DB_PAGE_LIMIT users or groups and cannot reach the rest. Use another database engine for directory sync.

SCIM discovery endpoints

Each directory exposes the SCIM 2.0 discovery endpoints defined in RFC 7644 §4 under its SCIM base URL. Identity providers and SCIM clients use them to discover which protocol features the server supports. All discovery endpoints require the directory's bearer token, the same credential used for the Users and Groups endpoints.

Endpoint	Description
GET <scim-url>/ServiceProviderConfig	Supported protocol features (PATCH, filtering, pagination, authentication schemes)
GET <scim-url>/Schemas	The User, Group, and Enterprise User schema definitions
GET <scim-url>/Schemas/{urn}	A single schema definition by its URN
GET <scim-url>/ResourceTypes	The User and Group resource types
GET <scim-url>/ResourceTypes/{id}	A single resource type by ID

<scim-url> is the directory's SCIM endpoint, for example https://your-domain.com/api/scim/v2.0/{directoryId}.

ServiceProviderConfig reports filter.maxResults, the largest number of resources a Users or Groups query returns in one response. It defaults to 50. Self-hosted deployments can change it with DB_PAGE_LIMIT.

Group membership updates

Identity providers change a group's members with either PATCH or PUT on <scim-url>/Groups/{id}, and Ory Polis supports both.

• PATCH applies add, remove, and replace operations on the members attribute.
• PUT replaces the group. When the body carries members, the membership is replaced with that list, and an empty list removes every member. When the body carries no members attribute, the current membership is kept and only the other attributes, such as displayName, change.

Each user added to or removed from a group emits a group.user_added or group.user_removed event, whichever method the identity provider uses.