0
How Pull-Based Sync Works

In a pull architecture, the client application controls when to synchronize, which identities to query, and how to ingest them into its local database. Here is the complete protocol lifecycle:

  1. Machine-to-Machine Authentication (OAuth 2.0 Client Credentials): Because sync jobs run as unattended background services without a human user, the application authenticates directly as itself (RFC 6749 §4.4) against the tenant's token endpoint (/oauth2/v2.0/token) using its registered Application (Client) ID and Client Secret.
  2. Application Scopes & Roles (/.default): The app requests scope https://graph.microsoft.com/.default. Microsoft Entra returns an Access Token containing tenant-wide Application Roles (such as User.Read.All) that have been pre-approved by a directory administrator via Admin Consent.
  3. Targeted Inclusion Filtering (OData): Enterprise directories often contain thousands of service principals, guest accounts, and shared mailboxes. The application constructs an OData query ($filter) to select only active, relevant employees (e.g., department eq 'Sales' and accountEnabled eq true).
  4. Graph Advanced Queries (ConsistencyLevel: eventual): Standard queries are strictly consistent. However, advanced filters (such as ne, endsWith, or searching custom directory extensions) leverage Entra's distributed indexing layer. Microsoft Graph requires passing the ConsistencyLevel: eventual header and $count=true.
  5. Batch Ingestion & Cursor Pagination (@odata.nextLink): Graph returns matching users in pages (default 100). If more users match, Graph provides an opaque cursor URL (@odata.nextLink). The application loops through these pages to import and reconcile all identities in its local store.
1
Application Configuration

Obtain credentials from your Microsoft Entra App Registration. These identify and authorize your application to read the directory. Secrets are transmitted only to the local backend proxy to perform the token exchange and are never persisted in the browser.

Directory (tenant) GUID or primary domain (e.g. contoso.onmicrosoft.com).
Application (client) ID found on the App Registration Overview page.
Use the secret Value (visible only upon creation), not the Secret ID (GUID).
v1.0 is recommended for production; beta provides preview properties.
2
OAuth 2.0 Access Token (Client Credentials)

Execute a machine-to-machine token exchange against the Entra OAuth2 v2.0 token endpoint. The requested scope https://graph.microsoft.com/.default instructs Entra to include all Application permissions statically consented to the app. Inspect the decoded JWT below to verify the roles claim.

POSTToken Endpoint
// Fill in config above to preview
// Awaiting request…
3
Inclusion Filter (OData Query Builder)

Define criteria to select which users to import. Multiple conditions are automatically combined using and. If no conditions are set, all directory users will be pulled. Advanced queries (using ne, endsWith, or on-premises extension attributes) automatically attach the required ConsistencyLevel: eventual header.

Comma-separated attributes. Reduces payload size and latency. Filtered attributes are added automatically.
Number of user objects returned per HTTP page from Microsoft Graph.
If set, overrides the visual condition builder above with raw OData syntax.
4
Microsoft Graph Request Preview

The exact HTTP GET request that will be sent to the Microsoft Graph REST API. Notice the bearer token authorization, the OData query parameters, and the ConsistencyLevel header.

GETMicrosoft Graph

      
5
Graph Response & User Ingestion

The raw response from Microsoft Graph and the resulting directory user table. In a production sync engine, these user records are reconciled and inserted into the local application database.

// Will appear after pulling users
// Awaiting request…