How Provisioning Works

The Entra provisioning service is the engine behind all application provisioning scenarios. It runs cycles, evaluates scoping rules, matches users between systems, applies attribute mappings, and executes create/update/disable/delete operations on target applications. Understanding this engine is essential for configuring provisioning correctly and troubleshooting when things go wrong.

The Provisioning Cycle

The service operates in two phases: an initial cycle and recurring incremental cycles.

Initial Cycle

When provisioning starts for the first time (or is restarted), the service runs a full evaluation:

Query all in-scope users and groups from the source system, retrieving all attributes defined in the attribute mappings.
Apply scoping filters and assignment-based scoping to determine which objects should be provisioned.
Match each in-scope user against the target system using the configured matching attributes.
Create users that exist in the source but not the target. Update users that exist in both systems with any attribute differences.
Process reference attributes (like manager assignments) after the primary objects are created.
Persist a watermark that marks the end state. All future incremental cycles start from this point.

The initial cycle can take anywhere from 20 minutes to several hours, depending on the number of users in scope.

Incremental Cycles

After the initial cycle, the service runs incremental cycles approximately every 40 minutes:

Query for changes since the last watermark.
Apply scoping to the changed objects.
Match and update existing users. Create any newly in-scope users.
Handle removals. If a user goes out of scope (unassigned, filtered out, soft-deleted), the service disables or deletes them in the target system.
Persist a new watermark.

Incremental cycles are fast because they only process changes, not the full user population.

sequenceDiagram
    participant Source as Entra ID (Source)
    participant Engine as Provisioning Engine
    participant Target as Target Application

    Note over Engine: Initial Cycle
    Engine->>Source: Query all in-scope users
    Source-->>Engine: Return user set
    Engine->>Engine: Apply scoping filters
    loop For each in-scope user
        Engine->>Target: Search for matching user
        Target-->>Engine: Match result
        alt No match found
            Engine->>Target: Create user
        else Match found
            Engine->>Target: Update user attributes
        end
    end
    Engine->>Engine: Persist watermark

    Note over Engine: Incremental Cycle (every ~40 min)
    Engine->>Source: Query changes since watermark
    Source-->>Engine: Return changed users
    Engine->>Engine: Apply scoping filters
    loop For each changed user
        Engine->>Target: Search for matching user
        Target-->>Engine: Match result
        alt Newly in scope
            Engine->>Target: Create user
        else Attribute changed
            Engine->>Target: Update user
        else Out of scope
            Engine->>Target: Disable or delete user
        end
    end
    Engine->>Engine: Persist new watermark

Scoping: Who Gets Provisioned

The provisioning service supports two scoping mechanisms, and they can be combined.

Assignment-Based Scoping

The most common approach. Only users and groups explicitly assigned to the enterprise application are in scope. This is controlled by the provisioning scope setting:

Sync only assigned users and groups (recommended): Only users directly assigned or members of assigned groups are provisioned.
Sync all users and groups: Every user in the directory is in scope. Use this only when you genuinely need to provision everyone.

Assignment-based scoping integrates with the same assignment model used for SSO, so one assignment controls both access and provisioning.

Nested groups are not supported. If a group is assigned, only its direct members are provisioned, not members of nested subgroups.

Attribute-Based Scoping (Scoping Filters)

Scoping filters let you define attribute-based rules. For example, “only provision users where department equals Sales.”

Filter construction:

Clauses are individual conditions on a single attribute (e.g., department EQUALS Sales).
Multiple clauses within one filter are combined with AND logic: all must be true.
Multiple filters are combined with OR logic: any filter passing is enough.

Common operators include EQUALS, NOT EQUALS, IS NOT NULL, IS NULL, REGEX MATCH, CONTAINS, ENDS_WITH, Greater_Than, and Greater_Than_OR_EQUALS.

Scoping filters are configured within the attribute mapping for each provisioning connector.

Tip: Reducing the number of users in scope improves provisioning performance. Prefer assignment-based scoping where possible and use scoping filters for additional refinement.

Matching Rules

When the provisioning engine encounters an in-scope user, it must determine whether that user already exists in the target system. This is done through matching attributes.

Each attribute mapping has a matching precedence setting. The engine queries the target system for a user whose target attribute matches the source attribute value. For example, if userPrincipalName in Entra ID maps to userName in the target app with matching precedence 1, the engine searches the target for a user with userName equal to the source user’s UPN.

You can define multiple matching attributes with different precedence levels. The engine tries them in order until it finds a match or exhausts all options.

If no match is found, the user is created. If a match is found, the user is updated with the source attributes. The target system’s ID is cached for all future operations, so subsequent cycles use the cached ID directly instead of re-matching.

Attribute Mappings

Attribute mappings define how data flows from source to target. Each mapping specifies:

Source attribute: The attribute to read from the source system.
Target attribute: The attribute to write in the target system.
Mapping type: Direct (one-to-one), constant (fixed value), or expression (transformation using the provisioning expression language).
Apply this mapping: During object creation only, always, or never.
Default value: What to write if the source attribute is null.

Gallery applications come with pre-configured mappings that cover common attributes. You can customize these, add new mappings, or remove unneeded ones.

Expression Mappings

When a direct mapping is not enough, you write expressions using the provisioning expression language. Common functions include:

Switch() for conditional value assignment
Join() for concatenating multiple attributes
Replace() for string substitution
IIF() for if/then/else logic
FormatDateTime() for date transformations

Example: generating a username from first name and last name:

Join(".", [givenName], [surname])

The expression builder in the Entra admin center lets you test expressions against real user data before applying them.

Deprovisioning

When a user goes out of scope, the provisioning service handles the removal based on your configuration:

Soft-delete (disable): The default. Sets the user’s active property to false in the target system via an update.
Hard-delete: Sends a DELETE request to permanently remove the user. This happens when a user is hard-deleted from Entra ID (permanently removed after the 30-day recycle bin period).

You can control this behavior through:

The Target object actions checkboxes (Create, Update, Delete) in the mapping configuration.
The isSoftDeleted attribute mapping, which controls how the active/inactive state is communicated.
The skip out-of-scope deletions flag, which prevents any deprovisioning action when users fall out of scope.

Error Handling and Retries

When an operation fails against the target system, the provisioning engine retries with exponential backoff:

First retry: 6 hours after the failure
Second retry: 12 hours after the failure
Third retry: 24 hours after the failure
Subsequent retries: every 24 hours for up to 28 days

If retries continue to fail, the failed operation enters escrow. If escrow failures exceed the threshold (more than 40% of operations fail, with a minimum of 5,000 total operations), the provisioning job enters quarantine.

Common error causes:

Missing required attributes in the source system
Unique constraint violations in the target system (duplicate values)
Invalid admin credentials
SCIM endpoint returning unexpected responses

The troubleshooting deep-dive covers these scenarios in detail.

Next Steps

Gallery vs SCIM explains the difference between pre-integrated gallery apps and generic SCIM provisioning.
Configure Provisioning walks through setting up provisioning for an application.