Directory Synchronization and Data Freshness#

User Info Service maintains a local replica of the organization’s directory and serves API responses from that replica rather than querying the identity provider on every request. This section describes the data freshness contract that consuming services MUST design against.

Consistency model#

Directory data served by the API is eventually consistent with the identity provider. Changes made in the identity provider — new users, updated profiles, disabled accounts, modified group memberships, deleted entries — are reflected in API responses only after the service’s next successful synchronization with the identity provider.

The synchronization interval MUST be deployment-configurable. Consuming services MUST NOT assume that directory changes are reflected immediately. For example, a user added to a group in the identity provider MAY NOT appear in the group’s member list until the next synchronization completes.

Readiness#

The service MUST expose a readiness probe compatible with the deployment orchestrator (e.g. Kubernetes). The service MUST report itself as not ready until it has successfully populated its local directory replica at least once. The orchestrator MUST use this probe to avoid routing traffic to an instance that has no directory data.

Once the service becomes ready, it MUST remain ready even if subsequent synchronizations fail — it continues serving the most recently synchronized data.

Identity provider unavailability#

If synchronization with the identity provider fails, the service MUST behave as follows:

  • Local replica already populated (service was previously ready): the service MUST continue serving the last successfully synchronized data. API availability MUST NOT be affected. Data staleness grows until the next successful synchronization.

  • Local replica not yet populated (initial synchronization has not completed): the service MUST remain not ready. API requests that depend on directory data MUST fail until a synchronization succeeds.

The service MUST NOT expose partially synchronized data to callers. Updated directory data MUST become visible atomically — either all changes from a synchronization cycle are reflected, or none are.

Enterprise-application scoping (optional)#

A deployment MAY restrict the served directory to the groups assigned to a specific enterprise application, so that the groups exposed here match those the application emits into user tokens (the set usable by downstream services such as the Permission Service). When this scoping is enabled:

  • Groups are limited to those assigned to the enterprise application. Groups that are not assigned are absent from all group and membership responses, even if they exist in the identity provider.

  • Memberships are limited to the assigned groups; a user’s group listing reflects only their memberships within that assigned set.

  • Users are not restricted — the full set of directory users remains available. Additionally, service principals assigned to the application MAY be surfaced as users so that they can be resolved like any other caller.

  • The assigned set is re-evaluated every synchronization cycle, so assignment additions, removals, and renames converge under the same eventual-consistency contract as any other directory change.

When scoping is disabled (the default), the full tenant directory is served. This scoping affects only which entities are visible; it does not change response shapes, error codes, or any other part of the API contract.

See next#