- 1. In the Azure portal toolbar, select the **Directories + subscriptions** (:::image type="icon" source="./../active-directory/develop/media/common/portal-directory-subscription-filter.png" border="false":::) icon.

- 1. In the Azure portal toolbar, select the **Directories + subscriptions** (:::image type="icon" source="./../active-directory/develop/media/common/portal-directory-subscription-filter.png" border="false":::) icon.

- 1. In the Azure portal toolbar, select the **Directories + subscriptions** (:::image type="icon" source="./../active-directory/develop/media/common/portal-directory-subscription-filter.png" border="false":::) icon.

- 1. In the Azure portal toolbar, select the **Directories + subscriptions** (:::image type="icon" source="./../active-directory/develop/media/common/portal-directory-subscription-filter.png" border="false":::) icon.

-1. In the Azure portal toolbar, select the **Directories + subscriptions** filter icon (:::image type="icon" source="./../active-directory/develop/media/common/portal-directory-subscription-filter.png" border="false":::).

-description: Enable accidental deletions prevention in the Microsoft Entra provisioning service for applications and cross-tenant synchronization.

-zone_pivot_groups: app-provisioning-cross-tenant-synchronization

-# Enable accidental deletions prevention in the Microsoft Entra provisioning service

-The Microsoft Entra provisioning service includes a feature to help avoid accidental deletions. This feature ensures that users aren't disabled or deleted in an application unexpectedly.

-The Microsoft Entra provisioning service includes a feature to help avoid accidental deletions. This feature ensures that users aren't disabled or deleted in the target tenant unexpectedly.

-You use accidental deletions to specify a deletion threshold. Anything above the threshold that you set requires an admin to explicitly allow the processing of the deletions.

-## Configure accidental deletion prevention

-To enable accidental deletion prevention:

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. Select your application.

-1. Select **Provisioning** and then on the provisioning page select **Edit provisioning**.

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **External Identities** > **Cross-tenant synchronization** > **Configurations** and then select your configuration.

-1. Select **Provisioning**.

-1. Under **Settings**, select the **Prevent accidental deletions** check box and specify a deletion

-threshold.

-1. Ensure the **Notification Email** address is completed.

- If the deletion threshold is met, an email is sent.

-1. Select **Save** to save the changes.

-When the deletion threshold is met, the job goes into quarantine, and a notification email is sent. The quarantined job can then be allowed or rejected. To learn more about quarantine behavior, see [Application provisioning in quarantine status](application-provisioning-quarantine-status.md).

-## Recovering from an accidental deletion

-When you encounter an accidental deletion, you see it on the provisioning status page. It says `Provisioning has been quarantined. See quarantine details for more information`.

-You can click either **Allow deletes** or **View provisioning logs**.

-### Allowing deletions

-The **Allow deletes** action deletes the objects that triggered the accidental delete threshold. Use the procedure to accept the deletions.

-1. Select **Allow deletes**.

-2. Click **Yes** on the confirmation to allow the deletions.

-3. View the confirmation that the deletions were accepted. The status returns to healthy with the next cycle.

-### Rejecting deletions

-Investigate and reject deletions as necessary:

-### Test deletion prevention

-You can test the feature by triggering disable / deletion events by setting the threshold to a low number, for example 3, and then changing scoping filters, unassigning users, and deleting users from the directory (see common scenarios in next section).

-Let the provisioning job run (20 ΓÇô 40 mins) and navigate back to the provisioning page. Check the provisioning job in quarantine and choose to allow the deletions or review the provisioning logs to understand why the deletions occurred.

-## Common deprovisioning scenarios to test

-To learn more about deprovisioning scenarios, see [How Application Provisioning Works](how-provisioning-works.md#deprovisioning).

-## Frequently Asked Questions

-### What scenarios count toward the deletion threshold?

-When a user is set for removal from the target application (or target tenant), it's counted against the

-deletion threshold. Scenarios that could lead to a user being removed from the target

-application (or target tenant) could include: unassigning the user from the application (or configuration) and soft / hard deleting a user in the directory. Groups

-evaluated for deletion count towards the deletion threshold. In addition to deletions, the same functionality also works for disables.

-### What is the interval that the deletion threshold is evaluated on?

-It's evaluated each cycle. If the number of deletions doesn't exceed the threshold during a

-single cycle, the ΓÇ£circuit breakerΓÇ¥ isn't triggered. If multiple cycles are needed to reach a

-steady state, the deletion threshold is evaluated per cycle.

-### How are these deletion events logged?

-You can find users that should be disabled / deleted but havenΓÇÖt due to the deletion threshold.

-Navigation to **Provisioning logs** and then filter **Action** with *StagedAction* or *StagedDelete*.

-## Next steps

-description: How to troubleshoot common issues faced when you don't see users appearing in a Microsoft Entra Gallery Application you have configured for user provisioning with Microsoft Entra ID

-# No users are being provisioned

->[!NOTE]

->Starting 04/16/2020 we have changed the behavior for users assigned the default access role. Please see the section below for details.

->

-After automatic provisioning has been configured for an application (including verifying that the app credentials provided to Microsoft Entra ID to connect to the app are valid), then users and/or groups are provisioned to the app. Provisioning is determined by the following things:

-If you observe that users are not being provisioned, consult the [Provisioning logs (preview)](../reports-monitoring/concept-provisioning-logs.md?context=azure/active-directory/manage-apps/context/manage-apps-context) in Microsoft Entra ID. Search for log entries for a specific user.

-You can access the provisioning logs in the Microsoft Entra admin center by browsing to **Identity** > **Applications** > **Enterprise applications** > **Provisioning logs**. You can also select a specific application and then select **Provisioning logs** in the **Activity** section. You can search the provisioning data based on the name of the user or the identifier in either the source system or the target system. For details, see [Provisioning logs (preview)](../reports-monitoring/concept-provisioning-logs.md?context=azure/active-directory/manage-apps/context/manage-apps-context).

-The provisioning logs record all the operations performed by the provisioning service, including querying Microsoft Entra ID for assigned users that are in scope for provisioning, querying the target app for the existence of those users, comparing the user objects between the system. Then add, update, or disable the user account in the target system based on the comparison.

-## General Problem Areas with Provisioning to consider

-Below is a list of the general problem areas that you can drill into if you have an idea of where to start.

-## Provisioning service does not appear to start

-If you set the **Provisioning Status** to be **On** in the **Enterprise applications > \[Application Name\] >Provisioning** section of the Microsoft Entra admin center. However no other status details are shown on that page after subsequent reloads, it is likely that the service is running but has not completed an initial cycle yet. Check the **Provisioning logs (preview)** described above to determine what operations the service is performing, and if there are any errors.

->[!NOTE]

->An initial cycle can take anywhere from 20 minutes to several hours, depending on the size of the Microsoft Entra directory and the number of users in scope for provisioning. Subsequent syncs after the initial cycle are faster, as the provisioning service stores watermarks that represent the state of both systems after the initial cycle. The initial cycle improves performance of subsequent syncs.

->

-## Provisioning logs say users are skipped and not provisioned even though they are assigned

-When a user shows up as ΓÇ£skippedΓÇ¥ in the provisioning logs, it is important to review the **Steps** tab of the log to determine the reason. Below are common reasons and resolutions:

-## Provisioning users assigned to the default access role

-The default role on an application from the gallery is called the "default access" role. Historically, users assigned to this role are not provisioned and are marked as skipped in the [provisioning logs](../reports-monitoring/concept-provisioning-logs.md) due to being "not effectively entitled."

-**Behavior for provisioning configurations created after 04/16/2020:**

-Users assigned to the default access role will be evaluated the same as all other roles. A user that is assigned the default access will not be skipped as "not effectively entitled."

-**Behavior for provisioning configurations created before 04/16/2020:**

-For the next 3 months, the behavior will continue as it is today. Users with the default access role will be skipped as not effectively entitled. After July 2020, the behavior will be uniform for all applications. We will not skip provisioning users with the default access role due to being "not effectively entitled." This change will be made by Microsoft, with no customer action required. If you would like to ensure that these users continue to be skipped, even after this change, please apply the appropriate scoping filters or unassign the user from the application to ensure they are out of scope.

-For questions about these changes, please reach out to provisioningfeedback@microsoft.com

-## Next steps

-[Microsoft Entra Connect Sync: Understanding Declarative Provisioning](../hybrid/connect/concept-azure-ad-connect-sync-declarative-provisioning.md)

-description: How to solve common protocol compatibility issues faced when adding a non-gallery application that supports SCIM 2.0 to Microsoft Entra ID

-# Known issues and resolutions with SCIM 2.0 protocol compliance of the Microsoft Entra user provisioning service

-Microsoft Entra ID can automatically provision users and groups to any application or system that is fronted by a web service with the interface defined in the [System for Cross-Domain Identity Management (SCIM) 2.0 protocol specification](https://tools.ietf.org/html/draft-ietf-scim-api-19).

-Microsoft Entra ID support for the SCIM 2.0 protocol is described in [Using System for Cross-Domain Identity Management (SCIM) to automatically provision users and groups from Microsoft Entra ID to applications](use-scim-to-provision-users-and-groups.md), which lists the specific parts of the protocol that it implements in order to automatically provision users and groups from Microsoft Entra ID to applications that support SCIM 2.0.

-This article describes current and past issues with the Microsoft Entra user provisioning service's adherence to the SCIM 2.0 protocol, and how to work around these issues.

-## Understanding the provisioning job

-The provisioning service uses the concept of a job to operate against an application. The jobID can be found in the [progress bar](application-provisioning-when-will-provisioning-finish-specific-user.md#view-the-provisioning-progress-bar). All new provisioning applications are created with a jobID starting with "scim". The scim job represents the current state of the service. Older jobs have the ID "customappsso". This job represents the state of the service in 2018.

-If you are using an application in the gallery, the job generally contains the name of the app (such as zoom snowFlake or dataBricks). You can skip this documentation when using a gallery application. This primarily applies for non-gallery applications with jobID SCIM or customAppSSO.

-## SCIM 2.0 compliance issues and status

-In the table below, any item marked as fixed means that the proper behavior can be found on the SCIM job. We have worked to ensure backwards compatibility for the changes we have made. We recommend using the new behavior for any new implementations and updating existing implementations. Please note that the customappSSO behavior that was the default prior to December 2018 is not supported anymore.

-> [!NOTE]

-> For the changes made in 2018, it is possible to revert back to the customappsso behavior. For the changes made since 2018, you can use the URLs to revert back to the older behavior. We have worked to ensure backwards compatibility for the changes we have made by allowing you to revert back to the old jobID or by using a flag. However, as previously mentioned, we do not recommend implementing old behavior as it is not supported anymore. We recommend using the new behavior for any new implementations and updating existing implementations.

-| **SCIM 2.0 compliance issue** | **Fixed?** | **Fix date** | **Backwards compatibility** |

-||||

-| Microsoft Entra ID requires "/scim" to be in the root of the application's SCIM endpoint URL | Yes | December 18, 2018 | downgrade to customappSSO |

-| Extension attributes use dot "." notation before attribute names instead of colon ":" notation | Yes | December 18, 2018 | downgrade to customappSSO |

-| Patch requests for multi-value attributes contain invalid path filter syntax | Yes | December 18, 2018 | downgrade to customappSSO |

-| Group creation requests contain an invalid schema URI | Yes | December 18, 2018 | downgrade to customappSSO |

-| Update PATCH behavior to ensure compliance (e.g. active as boolean and proper group membership removals) | No | TBD| use feature flag |

-## Flags to alter the SCIM behavior

-Use the flags below in the tenant URL of your application in order to change the default SCIM client behavior.

-Use the following URL to update PATCH behavior and ensure SCIM compliance. The flag will alter the following behaviors:

-This behavior is currently only available when using the flag, but will become the default behavior over the next few months. Note this feature flag currently does not work with on-demand provisioning.

- * **URL (SCIM Compliant):** aadOptscim062020

- * **SCIM RFC references:**

- * https://tools.ietf.org/html/rfc7644#section-3.5.2

-Below are sample requests to help outline what the sync engine currently sends versus the requests that are sent once the feature flag is enabled.

-**Requests made to disable users:**

-**Without feature flag**

- ```json

- {

- "schemas": [

- "urn:ietf:params:scim:api:messages:2.0:PatchOp"

- ],

- "Operations": [

- {

- "op": "Replace",

- "path": "active",

- "value": "False"

- }

- ]

- }

- ```

-**With feature flag**

- ```json

- {

- "schemas": [

- "urn:ietf:params:scim:api:messages:2.0:PatchOp"

- ],

- "Operations": [

- {

- "op": "replace",

- "path": "active",

- "value": false

- }

- ]

- }

- ```

-**Requests made to add a single-value string attribute:**

-**Without feature flag**

- ```json

- {

- "schemas": [

- "urn:ietf:params:scim:api:messages:2.0:PatchOp"

- ],

- "Operations": [

- {

- "op": "Add",

- "path": "nickName",

- "value": "Babs"

- }

- ]

- }

- ```

-**With feature flag**

- ```json

- {

- "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],

- "Operations": [

- {

- "op": "add",

- "path": "nickName",

- "value": "Babs"

- }

- ]

- }

- ```

-**Requests to replace multiple attributes:**

-**Without feature flag**

- ```json

- {

- "schemas": [

- "urn:ietf:params:scim:api:messages:2.0:PatchOp"

- ],

- "Operations": [

- {

- "op": "Replace",

- "path": "displayName",

- "value": "Pvlo"

- },

- {

- "op": "Replace",

- "path": "emails[type eq \"work\"].value",

- "value": "TestBcwqnm@test.microsoft.com"

- },

- {

- "op": "Replace",

- "path": "name.givenName",

- "value": "Gtfd"

- },

- {

- "op": "Replace",

- "path": "name.familyName",

- "value": "Pkqf"

- },

- {

- "op": "Replace",

- "path": "externalId",

- "value": "Eqpj"

- },

- {

- "op": "Replace",

- "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber",

- "value": "Eqpj"

- }

- ]

- }

- ```

-**With feature flag**

- ```json

- {

- "schemas": [

- "urn:ietf:params:scim:api:messages:2.0:PatchOp"

- ],

- "Operations": [

- {

- "op": "replace",

- "path": "emails[type eq \"work\"].value",

- "value": "TestMhvaes@test.microsoft.com"

- },

- {

- "op": "replace",

- "value": {

- "displayName": "Bjfe",

- "name.givenName": "Kkom",

- "name.familyName": "Unua",

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber": "Aklq"

- }

- }

- ]

- }

- ```

-**Requests made to remove a group member:**

-**Without feature flag**

- ```json

- {

- "schemas": [

- "urn:ietf:params:scim:api:messages:2.0:PatchOp"

- ],

- "Operations": [

- {

- "op": "Remove",

- "path": "members",

- "value": [

- {

- "value": "u1091"

- }

- ]

- }

- ]

- }

- ```

-**With feature flag**

- ```json

- {

- "schemas": [

- "urn:ietf:params:scim:api:messages:2.0:PatchOp"

- ],

- "Operations": [

- {

- "op": "remove",

- "path": "members[value eq \"7f4bc1a3-285e-48ae-8202-5accb43efb0e\"]"

- }

- ]

- }

- ```

- * **Downgrade URL:** Once the new SCIM compliant behavior becomes the default on the non-gallery application, you can use the following URL to roll back to the old, non SCIM compliant behavior: AzureAdScimPatch2017

-## Upgrading from the older customappsso job to the SCIM job

-Following the steps below will delete your existing customappsso job and create a new SCIM job.

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. Locate and select your existing SCIM application.

-1. In the **Properties** section of your existing SCIM app, copy the **Object ID**.

-1. In a new web browser window, go to https://developer.microsoft.com/graph/graph-explorer and sign in as the administrator for the Microsoft Entra tenant where your app is added.

-1. In the Graph Explorer, run the command below to locate the ID of your provisioning job. Replace "[object-id]" with the service principal ID (object ID) copied from the third step.

- `GET https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs`

- 

-6. In the results, copy the full "ID" string that begins with either "customappsso" or "scim".

-7. Run the command below to retrieve the attribute-mapping configuration, so you can make a backup. Use the same [object-id] as before, and replace [job-id] with the provisioning job ID copied from the last step.

- `GET https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs/[job-id]/schema`

- 

-8. Copy the JSON output from the last step, and save it to a text file. The JSON contains any custom attribute-mappings that you added to your old app, and should be approximately a few thousand lines of JSON.

-9. Run the command below to delete the provisioning job:

- `DELETE https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs/[job-id]`

-10. Run the command below to create a new provisioning job that has the latest service fixes.

- `POST https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs`

- `{ "templateId": "scim" }`

-11. In the results of the last step, copy the full "ID" string that begins with "scim". Optionally, reapply your old attribute-mappings by running the command below, replacing [new-job-id] with the new job ID you copied, and entering the JSON output from step #7 as the request body.

- `PUT https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs/[new-job-id]/schema`

- `{ <your-schema-json-here> }`

-12. Return to the first web browser window, and select the **Provisioning** tab for your application.

-13. Verify your configuration, and then start the provisioning job.

-## Downgrading from the SCIM job to the customappsso job (not recommended)

- We allow you to downgrade back to the old behavior but don't recommend it as the customappsso does not benefit from some of the updates we make, and may not be supported forever.

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. In the **Create application** section, create a new **Non-gallery** application.

-1. In the **Properties** section of your new custom app, copy the **Object ID**.

-1. In a new web browser window, go to https://developer.microsoft.com/graph/graph-explorer and sign in as the administrator for the Microsoft Entra tenant where your app is added.

-1. In the Graph Explorer, run the command below to initialize the provisioning configuration for your app.

- Replace "[object-id]" with the service principal ID (object ID) copied from the third step.

- `POST https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs`

- `{ templateId: "customappsso" }`

-6. Return to the first web browser window, and select the **Provisioning** tab for your application.

-7. Complete the user provisioning configuration as you normally would.

-## Next steps

-[Learn more about provisioning and de-provisioning to SaaS applications](user-provisioning.md)

-description: How to troubleshoot common issues faced when configuring user provisioning to an application already listed in the Microsoft Entra Application Gallery

-# Problem configuring user provisioning to a Microsoft Entra Gallery application

-Configuring [automatic user provisioning](user-provisioning.md) for an app (where supported), requires that specific instructions be followed to prepare the application for automatic provisioning. Then you can use the Microsoft Entra admin center to configure the provisioning service to synchronize user accounts to the application.

-You should always start by finding the setup tutorial specific to setting up provisioning for your application. Then follow those steps to configure both the app and Microsoft Entra ID to create the provisioning connection. A list of app tutorials can be found at [List of Tutorials on How to Integrate SaaS Apps with Microsoft Entra ID](../saas-apps/tutorial-list.md).

-## How to see if provisioning is working

-Once the service is configured, most insights into the operation of the service can be drawn from two places:

-## General problem areas with provisioning to consider

-Below is a list of the general problem areas that you can drill into if you have an idea of where to start.

-* [Provisioning service does not appear to start](#provisioning-service-does-not-appear-to-start)

-* CanΓÇÖt save configuration due to app credentials not working

-* [Provisioning logs say users are ΓÇ£skippedΓÇ¥ and not provisioned, even though they are assigned](#provisioning-logs-say-users-are-skipped-and-not-provisioned-even-though-they-are-assigned)

-## Provisioning service does not appear to start

-If you set the **Provisioning Status** to be **On** in the **Identity** > **Applications** > **Enterprise applications** > [Application Name\] > **Provisioning** section of the Microsoft Entra admin center. However no other status details are shown on that page after subsequent reloads. It is likely that the service is running but has not completed an initial cycle yet. Check the **Provisioning logs** described above to determine what operations the service is performing, and if there are any errors.

->[!NOTE]

->An initial cycle can take anywhere from 20 minutes to several hours, depending on the size of the Microsoft Entra directory and the number of users in scope for provisioning. Subsequent syncs after the initial cycle be faster, as the provisioning service stores watermarks that represent the state of both systems after the initial cycle, improving performance of subsequent syncs.

->

->

-## CanΓÇÖt save configuration due to app credentials not working

-In order for provisioning to work, Microsoft Entra ID requires valid credentials that allow it to connect to a user management API provided by that app. If these credentials donΓÇÖt work, or you donΓÇÖt know what they are, review the tutorial for setting up this app, described previously.

-## Provisioning logs say users are skipped and not provisioned even though they are assigned

-When a user shows up as ΓÇ£skippedΓÇ¥ in the provisioning logs, it is very important to read the extended details in the log message to determine the reason. Below are common reasons and resolutions:

- * **Attribute mappings for groups:** Provisioning of the group name and group details, in addition to the members, if supported for some applications. You can enable or disable this functionality by enabling or disabling the **Mapping** for group objects shown in the **Provisioning** tab. If provisioning groups is enabled, be sure to review the attribute mappings to ensure an appropriate field is being used for the ΓÇ£matching IDΓÇ¥. This can be the display name or email alias), as the group and its members not be provisioned if the matching property is empty or not populated for a group in Microsoft Entra ID.

-## Next steps

-[Automate User Provisioning and Deprovisioning to SaaS Applications with Microsoft Entra ID](user-provisioning.md)

-description: Learn how to save time by using the Microsoft Graph APIs to automate the configuration of automatic provisioning.

-# Configure provisioning using Microsoft Graph APIs

-The Microsoft Entra admin center is a convenient way to configure provisioning for individual apps one at a time. But if you're creating severalΓÇöor even hundredsΓÇöof instances of an application, it can be easier to automate app creation and configuration with the Microsoft Graph APIs. This article outlines how to automate provisioning configuration through APIs. This method is commonly used for applications like [Amazon Web Services](../saas-apps/amazon-web-service-tutorial.md#configure-azure-ad-sso).

-**Overview of steps for using Microsoft Graph APIs to automate provisioning configuration**

-|Step |Details |

-|||

-|[Step 1. Create the gallery application](#step-1-create-the-gallery-application) |Sign-in to the API client <br> Retrieve the gallery application template <br> Create the gallery application |

-|[Step 2. Create provisioning job based on template](#step-2-create-the-provisioning-job-based-on-the-template) |Retrieve the template for the provisioning connector <br> Create the provisioning job |

-|[Step 3. Authorize access](#step-3-authorize-access) |Test the connection to the application <br> Save the credentials |

-|[Step 4. Start provisioning job](#step-4-start-the-provisioning-job) |Start the job |

-|[Step 5. Monitor provisioning](#step-5-monitor-provisioning) |Check the status of the provisioning job <br> Retrieve the provisioning logs |

-## Step 1: Create the gallery application

-### Sign in to Microsoft Graph Explorer (recommended), Postman, or any other API client you use

-1. Start [Microsoft Graph Explorer](https://developer.microsoft.com/graph/graph-explorer).

-1. Select the "Sign-In with Microsoft" button and sign in using Microsoft Entra Global Administrator or App Admin credentials.

-1. Upon successful sign-in, you'll see the user account details in the left-hand pane.

-### Retrieve the gallery application template identifier

-Applications in the Microsoft Entra application gallery each have an [application template](/graph/api/applicationtemplate-list?tabs=http&view=graph-rest-beta&preserve-view=true) that describes the metadata for that application. Using this template, you can create an instance of the application and service principal in your tenant for management. Retrieve the identifier of the application template for **AWS Single-Account Access** and from the response, record the value of the **id** property to use later in this tutorial.

-#### Request

-```msgraph-interactive

-GET https://graph.microsoft.com/beta/applicationTemplates?$filter=displayName eq 'AWS Single-Account Access'

-```

-#### Response

-<!-- {

- "blockType": "response",

- "truncated": true,

- "@odata.type": "microsoft.graph.applicationTemplate",

- "isCollection": true

-} -->

-```http

-HTTP/1.1 200 OK

-Content-type: application/json

-{

- "value": [

- {

- "id": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",

- "displayName": "AWS Single-Account Access",

- "homePageUrl": "http://aws.amazon.com/",

- "supportedSingleSignOnModes": [

- "password",

- "saml",

- "external"

- ],

- "supportedProvisioningTypes": [

- "sync"

- ],

- "logoUrl": "https://az495088.vo.msecnd.net/app-logo/aws_215.png",

- "categories": [

- "developerServices"

- ],

- "publisher": "Amazon",

- "description": "Federate to a single AWS account and use SAML claims to authorize access to AWS IAM roles. If you have many AWS accounts, consider using the AWS Single Sign-On gallery application instead."

-}

-```

-### Create the gallery application

-Use the template ID retrieved for your application in the last step to [create an instance](/graph/api/applicationtemplate-instantiate?tabs=http&view=graph-rest-beta&preserve-view=true) of the application and service principal in your tenant.

-#### Request

-```msgraph-interactive

-POST https://graph.microsoft.com/beta/applicationTemplates/{id}/instantiate

-Content-type: application/json

-{

- "displayName": "AWS Contoso"

-}

-```

-#### Response

-```http

-HTTP/1.1 201 OK

-Content-type: application/json

-{

- "application": {

- "objectId": "cbc071a6-0fa5-4859-8g55-e983ef63df63",

- "appId": "92653dd4-aa3a-3323-80cf-e8cfefcc8d5d",

- "applicationTemplateId": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",

- "displayName": "AWS Contoso",

- "homepage": "https://signin.aws.amazon.com/saml?metadata=aws|ISV9.1|primary|z",

- "replyUrls": [

- "https://signin.aws.amazon.com/saml"

- ],

- "logoutUrl": null,

- "samlMetadataUrl": null,

- },

- "servicePrincipal": {

- "objectId": "f47a6776-bca7-4f2e-bc6c-eec59d058e3e",

- "appDisplayName": "AWS Contoso",

- "applicationTemplateId": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",

- "appRoleAssignmentRequired": true,

- "displayName": "My custom name",

- "homepage": "https://signin.aws.amazon.com/saml?metadata=aws|ISV9.1|primary|z",

- "replyUrls": [

- "https://signin.aws.amazon.com/saml"

- ],

- "servicePrincipalNames": [

- "93653dd4-aa3a-4323-80cf-e8cfefcc8d7d"

- ],

- "tags": [

- "WindowsAzureActiveDirectoryIntegratedApp"

- ],

- }

-}

-```

-## Step 2: Create the provisioning job based on the template

-### Retrieve the template for the provisioning connector

-Applications in the gallery that are enabled for provisioning have templates to streamline configuration. Use the request below to [retrieve the template for the provisioning configuration](/graph/api/synchronization-synchronization-list-templates?preserve-view=true&tabs=http&view=graph-rest-beta). Note that you will need to provide the ID. The ID refers to the preceding resource, which in this case is the servicePrincipal resource.

-#### Request

-```msgraph-interactive

-GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/templates

-```

-#### Response

-```http

-HTTP/1.1 200 OK

-{

- "value": [

- {

- "id": "aws",

- "factoryTag": "aws",

- "schema": {

- "directories": [],

- "synchronizationRules": []

- }

- }

- ]

-}

-```

-### Create the provisioning job

-To enable provisioning, you'll first need to [create a job](/graph/api/synchronization-synchronization-post-jobs?preserve-view=true&tabs=http&view=graph-rest-beta). Use the following request to create a provisioning job. Use the templateId from the previous step when specifying the template to be used for the job.

-#### Request

-```msgraph-interactive

-POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs

-Content-type: application/json

-{

- "templateId": "aws"

-}

-```

-#### Response

-```http

-HTTP/1.1 201 OK

-Content-type: application/json

-{

- "id": "{jobId}",

- "templateId": "aws",

- "schedule": {

- "expiration": null,

- "interval": "P10675199DT2H48M5.4775807S",

- "state": "Disabled"

- },

- "status": {

- "countSuccessiveCompleteFailures": 0,

- "escrowsPruned": false,

- "synchronizedEntryCountByType": [],

- "code": "NotConfigured",

- "lastExecution": null,

- "lastSuccessfulExecution": null,

- "lastSuccessfulExecutionWithExports": null,

- "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",

- "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",

- "quarantine": null,

- "troubleshootingUrl": null

- }

-}

-```

-## Step 3: Authorize access

-### Test the connection to the application

-Test the connection with the third-party application. The following example is for an application that requires a client secret and secret token. Each application has its own requirements. Applications often use a base address in place of a client secret. To determine what credentials your app requires, go to the provisioning configuration page for your application, and in developer mode, click **test connection**. The network traffic will show the parameters used for credentials. For a full list of credentials, see [synchronizationJob: validateCredentials](/graph/api/synchronization-synchronizationjob-validatecredentials?tabs=http&view=graph-rest-beta&preserve-view=true). Most applications, such as Azure Databricks, rely on a BaseAddress and SecretToken. The BaseAddress is referred to as a tenant URL in the Microsoft Entra admin center.

-#### Request

-```msgraph-interactive

-POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{id}/validateCredentials

-{

- "credentials": [

- {

- "key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx"

- },

- {

- "key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"

- }

- ]

-}

-```

-#### Response

-```http

-HTTP/1.1 204 No Content

-```

-### Save your credentials

-Configuring provisioning requires establishing a trust between Microsoft Entra ID and the application. Authorize access to the third-party application. The following example is for an application that requires a client secret and a secret token. Each application has its own requirements. Review the [API documentation](/graph/api/synchronization-synchronizationjob-validatecredentials?tabs=http&view=graph-rest-beta&preserve-view=true) to see the available options.

-#### Request

-```msgraph-interactive

-PUT https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/secrets

-{

- "value": [

- {

- "key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx"

- },

- {

- "key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"

- }

- ]

-}

-```

-#### Response

-```http

-HTTP/1.1 204 No Content

-```

-## Step 4: Start the provisioning job

-Now that the provisioning job is configured, use the following command to [start the job](/graph/api/synchronization-synchronizationjob-start?tabs=http&view=graph-rest-beta&preserve-view=true).

-#### Request

-```http

-POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/start

-```

-#### Response

-```http

-HTTP/1.1 204 No Content

-```

-## Step 5: Monitor provisioning

-### Monitor the provisioning job status

-Now that the provisioning job is running, use the following command to track the progress of the current provisioning cycle as well as statistics to date such as the number of users and groups that have been created in the target system.

-#### Request

-```msgraph-interactive

-GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/

-```

-#### Response

-```http

-HTTP/1.1 200 OK

-Content-type: application/json

-{

- "id": "{jobId}",

- "templateId": "aws",

- "schedule": {

- "expiration": null,

- "interval": "P10675199DT2H48M5.4775807S",

- "state": "Disabled"

- },

- "status": {

- "countSuccessiveCompleteFailures": 0,

- "escrowsPruned": false,

- "synchronizedEntryCountByType": [],

- "code": "Paused",

- "lastExecution": null,

- "lastSuccessfulExecution": null,

- "progress": [],

- "lastSuccessfulExecutionWithExports": null,

- "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",

- "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",

- "quarantine": null,

- "troubleshootingUrl": null

- },

- "synchronizationJobSettings": [

- {

- "name": "QuarantineTooManyDeletesThreshold",

- "value": "500"

- }

- ]

-}

-```

-### Monitor provisioning events using the provisioning logs

-In addition to monitoring the status of the provisioning job, you can use the [provisioning logs](/graph/api/provisioningobjectsummary-list?tabs=http&view=graph-rest-beta&preserve-view=true) to query for all the events that are occurring. For example, query for a particular user and determine if they were successfully provisioned.

-#### Request

-```msgraph-interactive

-GET https://graph.microsoft.com/beta/auditLogs/provisioning

-```

-#### Response

-```http

-HTTP/1.1 200 OK

-Content-type: application/json

-{

- "@odata.context": "https://graph.microsoft.com/beta/$metadata#auditLogs/provisioning",

- "value": [

- {

- "id": "gc532ff9-r265-ec76-861e-42e2970a8218",

- "activityDateTime": "2019-06-24T20:53:08Z",

- "tenantId": "7928d5b5-7442-4a97-ne2d-66f9j9972ecn",

- "cycleId": "44576n58-v14b-70fj-8404-3d22tt46ed93",

- "changeId": "eaad2f8b-e6e3-409b-83bd-e4e2e57177d5",

- "action": "Create",

- "durationInMilliseconds": 2785,

- "sourceSystem": {

- "id": "0404601d-a9c0-4ec7-bbcd-02660120d8c9",

- "displayName": "Azure Active Directory",

- "details": {}

- },

- "targetSystem": {

- "id": "cd22f60b-5f2d-1adg-adb4-76ef31db996b",

- "displayName": "AWS Contoso",

- "details": {

- "ApplicationId": "f2764360-e0ec-5676-711e-cd6fc0d4dd61",

- "ServicePrincipalId": "chc46a42-966b-47d7-9774-576b1c8bd0b8",

- "ServicePrincipalDisplayName": "AWS Contoso"

- }

- },

- "initiatedBy": {

- "id": "",

- "displayName": "Azure AD Provisioning Service",

- "initiatorType": "system"

- }

- ]

- }

- ]

-}

-```

-## See also

-description: Understand how Provisioning integrates with Azure Monitor logs in Microsoft Entra ID.

-# Understand how provisioning integrates with Azure Monitor logs

-Provisioning integrates with Azure Monitor logs and Log Analytics. With Azure monitoring you can do things like create workbooks, also known as dashboards, store provisioning logs for 30+ days, and create custom queries and alerts. This article discusses how provisioning logs integrate with Azure Monitor logs. To learn more about how provisioning logs work in general, see [provisioning logs](../reports-monitoring/concept-provisioning-logs.md).

-## Enabling provisioning logs

-You should already be familiar with Azure monitoring and Log Analytics. If not, jump over to learn about them, and then come back to learn about application provisioning logs. To learn more about Azure monitoring, see [Azure Monitor overview](/azure/azure-monitor/overview). To learn more about Azure Monitor logs and Log Analytics, see [Overview of log queries in Azure Monitor](/azure/azure-monitor/logs/log-query-overview).

-Once you've configured Azure monitoring, you can enable logs for application provisioning. The option is located on the **Diagnostics settings** page.

-> [!NOTE]

-> If you have just recently provisioned a workspace, it can take some time before you can send logs to it. If you receive an error that the subscription is not registered to use *microsoft.insights* then check back after a few minutes.

-## Understanding the data

-The underlying data stream that Provisioning sends log viewers is almost identical. Azure Monitor logs gets nearly the same stream as the Azure portal UI and Azure API. There are only a few **differences** in the log fields as outlined in the following table. To learn more about these fields, see [List provisioningObjectSummary](/graph/api/provisioningobjectsummary-list?preserve-view=true&tabs=http&view=graph-rest-beta).

-|Azure Monitor logs |Azure portal UI |Azure API |

-|-|--||

-|errorDescription |reason |resultDescription |

-|status |resultType |resultType |

-|activityDateTime |TimeGenerated |TimeGenerated |

-## Azure Monitor workbooks

-Azure Monitor workbooks provide a flexible canvas for data analysis. They also provide for the creation of rich visual reports within the Azure portal. To learn more, see [Azure Monitor Workbooks overview](/azure/azure-monitor/visualize/workbooks-overview).

-Application provisioning comes with a set of prebuilt workbooks. You can find them on the Workbooks page. To view the data, ensure that all the filters (timeRange, jobID, appName) are populated. Also confirm the app was provisioned, otherwise there isn't any data in the logs.

-## Custom queries

-You can create custom queries and show the data on Azure dashboards. To learn how, see [Create and share dashboards of Log Analytics data](/azure/azure-monitor/logs/get-started-queries). Also, be sure to check out [Overview of log queries in Azure Monitor](/azure/azure-monitor/logs/log-query-overview).

-Here are some samples to get started with application provisioning.

-Query the logs for a user a based on their ID in the source system:

-```kusto

-AADProvisioningLogs

-| extend SourceIdentity = parse_json(SourceIdentity)

-| where tostring(SourceIdentity.Id) == "49a4974bb-5011-415d-b9b8-78caa7024f9a"

-```

-Summarize count per ErrorCode:

-```kusto

-AADProvisioningLogs

-| summarize count() by ErrorCode = ResultSignature

-```

-Summarize count of events per day by action:

-```kusto

-AADProvisioningLogs

-| where TimeGenerated > ago(7d)

-| summarize count() by Action, bin(TimeGenerated, 1d)

-```

-Take 100 events and project key properties:

-```kusto

-AADProvisioningLogs

-| extend SourceIdentity = parse_json(SourceIdentity)

-| extend TargetIdentity = parse_json(TargetIdentity)

-| extend ServicePrincipal = parse_json(ServicePrincipal)

-| where tostring(SourceIdentity.identityType) == "Group"

-| project tostring(ServicePrincipal.Id), tostring(ServicePrincipal.Name), ModifiedProperties, JobId, Id, CycleId, ChangeId, Action, SourceIdentity.identityType, SourceIdentity.details, TargetIdentity.identityType, TargetIdentity.details, ProvisioningSteps

-|take 100

-```

-## Custom alerts

-Azure Monitor lets you configure custom alerts so that you can get notified about key events related to Provisioning. For example, you might want to receive an alert on spikes in failures. Or perhaps spikes in disables or deletes. Another example of where you might want to be alerted is a lack of any provisioning, which indicates something is wrong.

-To learn more about alerts, see [Azure Monitor Log Alerts](/azure/azure-monitor/alerts/alerts-create-new-alert-rule).

-Alert when there's a spike in failures. Replace the jobID with the jobID for your application.

-There may be an issue that caused the provisioning service to stop running. Use the following alert to detect when there are no provisioning events during a given time interval.

-Alert when there's a spike in disables or deletes.

-## Community contributions

-We're taking an open source and community-based approach to application provisioning queries and dashboards. Build a query, alert, or workbook that you think is useful to others, then publish it to the [AzureMonitorCommunity GitHub repo](https://github.com/microsoft/AzureMonitorCommunity). Shoot us an email with a link. We review and publish queries and dashboards to the service so others benefit too. Contact us at provisioningfeedback@microsoft.com.

-## Next steps

-description: When you've configured an application for automatic user provisioning, learn what a provisioning status of Quarantine means and how to clear it.

-# Application provisioning in quarantine status

-The Microsoft Entra provisioning service monitors the health of your configuration. It also places unhealthy apps in a "quarantine" state. If most, or all, of the calls made against the target system consistently fail then the provisioning job is marked as in quarantine. An example of a failure is an error received because of invalid admin credentials.

-While in quarantine:

-## How do I know if my application is in quarantine?

-There are three ways to check whether an application is in quarantine:

- 

-```microsoft-graph

- GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/

-```

- - Make sure you've specified a valid **Notification Email** in the provisioning configuration for the application.

- - Make sure there's no spam filtering on the notification email inbox.

- - Make sure you haven't unsubscribed from emails.

- - Check for emails from `azure-noreply@microsoft.com`

-## Why is my application in quarantine?

-Below are the common reasons your application may go into quarantine

-|Description|Recommended Action|

-|||

-|**SCIM Compliance issue:** An HTTP/404 Not Found response was returned rather than the expected HTTP/200 OK response. In this case, the Microsoft Entra provisioning service has made a request to the target application and received an unexpected response.|Check the admin credentials section. See if the application requires specifying the tenant URL and that the URL is correct. If you don't see an issue, contact the application developer to ensure that their service is SCIM-compliant. https://tools.ietf.org/html/rfc7644#section-3.4.2 |

-|**Invalid credentials:** When attempting to authorize, access to the target application, we received a response from the target application that indicates the credentials provided are invalid.|Navigate to the admin credentials section of the provisioning configuration UI and authorize access again with valid credentials. If the application is in the gallery, review the application configuration tutorial for anymore required steps.|

-|**Duplicate roles:** Roles imported from certain applications like Salesforce and Zendesk must be unique. |Navigate to the application [manifest](../develop/reference-app-manifest.md) in the Microsoft Entra admin center and remove the duplicate role.|

- A Microsoft Graph request to get the status of the provisioning job shows the following reason for quarantine:

-**Escrow thresholds**

-If the proportional escrow threshold is met, the provisioning job will go into quarantine. This logic is subject to change, but works roughly as described below:

-A job can go into quarantine regardless of failure counts for issues such as admin credentials or SCIM compliance. However, in general, 5,000 failures are the minimum to start evaluating whether to quarantine because of too many failures. For example, a job with 4,000 failures wouldn't go into quarantine. But, a job with 5,000 failures would trigger an evaluation. An evaluation uses the following criteria:

-**Retry duration**

-The logic documented here may be different for certain connectors to ensure best customer experience, but we generally have the below retry cycles after a failure:

-After the failure, the first retry will happen in 6 hours.

-There will be retries every 24 hours after the 3rd retry. The retries will go on for 28 days after the first failure after which the escrow entry is removed and the job is disabled.

-If any of the retries above gets a successful response, the job is automatically put out of quarantine and shall resume regular sync behavior.

-## How do I get my application out of quarantine?

-First, resolve the issue that caused the application to be placed in quarantine.

-After you've resolved the issue, restart the provisioning job. Certain changes to the application's provisioning settings, such as attribute mappings or scoping filters, will automatically restart provisioning for you. The progress bar on the application's **Provisioning** page indicates when provisioning last started. If you need to restart the provisioning job manually, use one of the following methods:

-```microsoft-graph

- POST /servicePrincipals/{id}/synchronization/jobs/{jobId}/restart

-```

-Replace "{ID}" with the value of the Application ID, and replace "{jobId}" with the [ID of the synchronization job](/graph/synchronization-configure-with-directory-extension-attributes?preserve-view=true&tabs=http&view=graph-rest-beta#list-synchronization-jobs-in-the-context-of-the-service-principal).

-description: How to find out when a critically important user is able to access an application you have configured for user provisioning with Microsoft Entra ID.

-# Check the status of user provisioning

-The Microsoft Entra provisioning service runs an initial provisioning cycle against the source system and target system, followed by periodic incremental cycles. When you configure provisioning for an app, you can check the current status of the provisioning service and see when a user is able to access an app.

-## View the provisioning progress bar

- On the **Provisioning** page for an app, you can view the status of the Microsoft Entra provisioning service. The **Current Status** section at the bottom of the page shows whether a provisioning cycle has started provisioning user accounts. You can watch the progress of the cycle, see how many users and groups have been provisioned, and see how many roles are created.

-When you first configure automatic provisioning, the **Current Status** section at the bottom of the page shows the status of the initial provisioning cycle. This section updates each time an incremental cycle is run. The following details are shown:

-After a provisioning cycle is complete, the **Statistics to date** section shows the cumulative numbers of users and groups that have been provisioned to date, along with the completion date and duration of the last cycle. The **Activity ID** uniquely identifies the most recent provisioning cycle. The **Job ID** is a unique identifier for the provisioning job, and is specific to the app in your tenant.

-The provisioning progress is viewed in the Microsoft Entra admin center at **Identity** > **Applications** > **Enterprise applications** > \[*application name*\] > **Provisioning**.

-

-## Use provisioning logs to check a user's provisioning status

-To see the provisioning status for a selected user, consult the [Provisioning logs (preview)](../reports-monitoring/concept-provisioning-logs.md?context=azure/active-directory/manage-apps/context/manage-apps-context) in Microsoft Entra ID. All operations run by the user provisioning service are recorded in the Microsoft Entra provisioning logs. The logs include read and write operations made to the source and target systems. Associated user data related to read and write operations is also logged.

-You can access the provisioning logs in the Microsoft Entra admin center by selecting **Identity** > **Applications** > **Enterprise applications** > **Provisioning logs** in the **Activity** section. You can search the provisioning data based on the name of the user or the identifier in either the source system or the target system. For details, see [Provisioning logs (preview)](../reports-monitoring/concept-provisioning-logs.md?context=azure/active-directory/manage-apps/context/manage-apps-context).

-The provisioning logs record all the operations performed by the provisioning service, including:

-* Querying Microsoft Entra ID for assigned users that are in scope for provisioning

-* Querying the target app for the existence of those users

-* Comparing the user objects between the system

-* Adding, updating, or disabling the user account in the target system based on the comparison

-For more information on how to read the provisioning logs in the Microsoft Entra admin center, see [provisioning reporting guide](check-status-user-account-provisioning.md).

-## How long will it take to provision users?

-When you're using automatic user provisioning with an application, there are some things to keep in mind. First, Microsoft Entra ID automatically provisions and updates user accounts in an app based on things like [user and group assignment](../manage-apps/assign-user-or-group-access-portal.md). The sync happens at a regularly scheduled time interval, typically every 40 minutes.

-The time it takes for a given user to be provisioned depends mainly on whether your provisioning job is running an initial cycle or an incremental cycle.

-The following table summarizes synchronization times for common provisioning scenarios. In these scenarios, the source system is Microsoft Entra ID and the target system is a SaaS application. The sync times are derived from a statistical analysis of sync jobs for the SaaS applications ServiceNow, Workplace, Salesforce, and G Suite.

-| Scope configuration | Users, groups, and members in scope | Initial cycle time |

-| -- | -- | -- |

-| Sync assigned users and groups only | < 1,000 | < 30 minutes |

-| Sync assigned users and groups only | 1,000 - 10,000 | 142 - 708 minutes |

-| Sync assigned users and groups only | 10,000 - 100,000 | 1,170 - 2,340 minutes |

-| Sync all users and groups in Microsoft Entra ID | < 1,000 | < 30 minutes |

-| Sync all users and groups in Microsoft Entra ID | 1,000 - 10,000 | < 30 - 120 minutes |

-| Sync all users and groups in Microsoft Entra ID | 10,000 - 100,000 | 713 - 1,425 minutes |

-| Sync all users in Microsoft Entra ID| < 1,000 | < 30 minutes |

-| Sync all users in Microsoft Entra ID | 1,000 - 10,000 | 43 - 86 minutes |

-For the configuration **Sync assigned user and groups only**, you can use the following formulas to determine the approximate minimum and maximum expected **initial cycle** times:

-Summary of factors that influence the time it takes to complete an **initial cycle**:

-In most cases, the **incremental cycle** completes in 30 minutes. However, when there are hundreds or thousands of user changes or group membership changes, the incremental cycle time will increase proportionally with the number of changes to process and can take several hours. Using **sync assigned users and groups** and minimizing the number of users / groups in scope for provisioning will help to reduce the sync time.

-## Recommendations for reducing the time to provision a user and / or group:

-1. Set the provisioning scope to sync `assigned users and groups`, rather than `sync all users and groups`.

-2. Minimize the number of users and groups in scope for provisioning.

-3. Create multiple provisioning jobs targeting the same system. When doing this, each sync job will operate independently, reducing the time to process changes. Please make sure that the scope of users is distinct between these provisioning jobs to avoid changes from one job impacting another.

-4. Add scoping filters to further limit the number of users and groups in scope for provisioning.

-## Next steps

-[Automate user provisioning and deprovisioning to SaaS applications with Microsoft Entra ID](user-provisioning.md)

-description: 'Learn how to check the status of automatic user account provisioning jobs, and how to troubleshoot the provisioning of individual users.'

-# Tutorial: Reporting on automatic user account provisioning

-Microsoft Entra ID includes a [user account provisioning service](user-provisioning.md). The service helps automate the provisioning deprovisioning of user accounts in SaaS apps and other systems. The automation helps with end-to-end identity lifecycle management. Microsoft Entra ID supports preintegrated user provisioning connectors for many applications and systems. To learn more about user provisioning tutorials, see [Provisioning Tutorials](../saas-apps/tutorial-list.md).

-This article describes how to check the status of provisioning jobs after they have been set up, and how to troubleshoot the provisioning of individual users and groups.

-## Overview

-Provisioning connectors are set up and configured using the [Microsoft Entra admin center](https://entra.microsoft.com), by following the [provided documentation](../saas-apps/tutorial-list.md) for the supported application. When the connector is configured and running, provisioning jobs can be reported using the following methods:

-### Definitions

-This article uses the following terms:

-* **Source System** - The repository of users that the Microsoft Entra provisioning service synchronizes from. Microsoft Entra ID is the source system for most preintegrated provisioning connectors, however there are some exceptions (example: Workday Inbound Synchronization).

-* **Target System** - The repository of users where the Microsoft Entra provisioning service synchronizes. The repository is typically a SaaS application, such as Salesforce, ServiceNow, G Suite, and Dropbox for Business. In some cases the repository can be an on-premises system such as Active Directory, such as Workday Inbound Synchronization to Active Directory.

-## Getting provisioning reports from the Microsoft Entra admin center

-To get provisioning report information for a given application:

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. Select **Provisioning logs** in the **Activity** section. You can also browse to the Enterprise Application for which provisioning is configured. For example, if you're provisioning users to LinkedIn Elevate, the navigation path to the application details is:

-**Identity** > **Applications** > **Enterprise applications** > **All applications** > **LinkedIn Elevate**

-From the all applications area, you access both the provisioning progress bar and provisioning logs.

-## Provisioning progress bar

-The [provisioning progress bar](application-provisioning-when-will-provisioning-finish-specific-user.md#view-the-provisioning-progress-bar) is visible in the **Provisioning** tab for a given application. It's located in the **Current Status** section and shows the status of the current initial or incremental cycle. This section also shows:

-* The total number of users and groups that are synchronized and currently in scope for provisioning between the source system and the target system.

-* The last time the synchronization was run. Synchronizations typically occur every 20-40 minutes, after an [initial cycle](../app-provisioning/how-provisioning-works.md#provisioning-cycles-initial-and-incremental) has completed.

-* The status of an [initial cycle](../app-provisioning/how-provisioning-works.md#provisioning-cycles-initial-and-incremental) and if the cycle has been completed.

-* The status of the provisioning process and if it's being placed in quarantine. The status also shows the reason for the quarantine. For example, a status might indicate a failure to communicate with the target system due to invalid admin credentials.

-The **Current Status** should be the first place admins look to check on the operational health of the provisioning job.

- 

-## Provisioning logs

-All activities performed by the provisioning service are recorded in the Microsoft Entra [provisioning logs](../reports-monitoring/concept-provisioning-logs.md?context=azure/active-directory/manage-apps/context/manage-apps-context). You can access the provisioning logs in the Microsoft Entra admin center. You can search the provisioning data based on the name of the user or the identifier in either the source system or the target system. For details, see [Provisioning logs](../reports-monitoring/concept-provisioning-logs.md?context=azure/active-directory/manage-apps/context/manage-apps-context).

-## Troubleshooting

-The provisioning summary report and provisioning logs play a key role helping admins troubleshoot various user account provisioning issues.

-For scenario-based guidance on how to troubleshoot automatic user provisioning, see [Problems configuring and provisioning users to an application](../app-provisioning/application-provisioning-config-problem.md).

-## Next steps

-description: Learn how to manage user account provisioning for enterprise apps using the Microsoft Entra ID.

-# Managing user account provisioning for enterprise apps in the Microsoft Entra admin center

-This article describes the general steps for managing automatic user account provisioning and deprovisioning for applications that support it. *User account provisioning* is the act of creating, updating, and/or disabling user account records in an applicationΓÇÖs local user profile store. Most cloud and SaaS applications store the role and permissions in the user's own local user profile store. The presence of such a user record in the user's local store is *required* for single sign-on and access to work. To learn more about automatic user account provisioning, see [Automate User Provisioning and Deprovisioning to SaaS Applications with Microsoft Entra ID](user-provisioning.md).

-> [!IMPORTANT]

-> Microsoft Entra ID has a gallery that contains thousands of pre-integrated applications that are enabled for automatic provisioning with Microsoft Entra ID. You should start by finding the provisioning setup tutorial specific to your application in the [List of tutorials on how to integrate SaaS apps with Microsoft Entra ID](../saas-apps/tutorial-list.md). You'll likely find step-by-step guidance for configuring both the app and Microsoft Entra ID to create the provisioning connection.

-## Finding your apps in the portal

-Use the Microsoft Entra admin center to view and manage all applications that are configured for single sign-on in a directory. Enterprise apps are apps that are deployed and used within your organization. Follow these steps to view and manage your enterprise applications:

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. A list of all configured apps is shown, including apps that were added from the gallery.

-1. Select any app to load its resource pane, where you can view reports and manage app settings.

-1. Select **Provisioning** to manage user account provisioning settings for the selected app.

- 

-## Provisioning modes

-The **Provisioning** pane begins with a **Mode** menu, which shows the provisioning modes supported for an enterprise application, and lets you configure them. The available options include:

-* **Automatic** - This option is shown if Microsoft Entra ID supports automatic API-based provisioning or deprovisioning of user accounts to this application. Select this mode to display an interface that helps administrators:

- * Configure Microsoft Entra ID to connect to the application's user management API

- * Create account mappings and workflows that define how user account data should flow between Microsoft Entra ID and the app

- * Manage the Microsoft Entra provisioning service

-* **Manual** - This option is shown if Microsoft Entra ID doesn't support automatic provisioning of user accounts to this application. In this case, user account records stored in the application must be managed using an external process, based on the user management and provisioning capabilities provided by that application (which can include SAML Just-In-Time provisioning).

-## Configuring automatic user account provisioning

-Select the **Automatic** option to specify settings for admin credentials, mappings, starting and stopping, and synchronization.

-### Admin Credentials

-Expand **Admin Credentials** to enter the credentials required for Microsoft Entra ID to connect to the application's user management API. The input required varies depending on the application. To learn about the credential types and requirements for specific applications, see the [configuration tutorial for that specific application](user-provisioning.md).

-Select **Test Connection** to test the credentials by having Microsoft Entra ID attempt to connect to the app's provisioning app using the supplied credentials.

-### Mappings

-Expand **Mappings** to view and edit the user attributes that flow between Microsoft Entra ID and the target application when user accounts are provisioned or updated.

-There's a preconfigured set of mappings between Microsoft Entra user objects and each SaaS appΓÇÖs user objects. Some apps also manage group objects. Select a mapping in the table to open the mapping editor, where you can view and customize them.

-Supported customizations include:

-* Enabling and disabling mappings for specific objects, such as the Microsoft Entra user object to the SaaS app's user object.

-* Editing the attributes that flow from the Microsoft Entra user object to the app's user object. For more information on attribute mapping, see [Understanding attribute mapping types](customize-application-attributes.md#understanding-attribute-mapping-types).

-* Filtering the provisioning actions that Microsoft Entra ID runs on the targeted application. Instead of having Microsoft Entra ID fully synchronize objects, you can limit the actions run.

- For example, only select **Update** and Microsoft Entra-only updates existing user accounts in an application but doesn't create new ones. Only select **Create** and Azure only creates new user accounts but doesn't update existing ones. This feature lets admins create different mappings for account creation and update workflows.

-* Adding a new attribute mapping. Select **Add New Mapping** at the bottom of the **Attribute Mapping** pane. Fill out the **Edit Attribute** form and select **Ok** to add the new mapping to the list.

-### Settings

-Expand **Settings** to set an email address to receive notifications and whether to receive alerts on errors. Also select the scope of users to sync. Choose to sync all users and groups or only users that are assigned.

-### Provisioning Status

-If provisioning is being enabled for the first time for an application, turn on the service by changing the **Provisioning Status** to **On**. This change causes the Microsoft Entra provisioning service to run an initial cycle. It reads the users assigned in the **Users and groups** section, queries the target application for them, and then runs the provisioning actions defined in the Microsoft Entra ID **Mappings** section. During this process, the provisioning service stores cached data about what user accounts it's managing. The service stores cached data so nonmanaged accounts inside the target applications that were never in scope for assignment aren't affected in deprovisioning operations. After the initial cycle, the provisioning service automatically synchronizes user and group objects on a forty-minute interval.

-Change the **Provisioning Status** to **Off** to pause the provisioning service. In this state, Azure doesn't create, update, or remove any user or group objects in the app. Change the state back to **On** and the service picks up where it left off.

-description: Learn about attribute mappings for Software as a Service (SaaS) apps in Microsoft Entra Application Provisioning. Learn what attributes are and how you can modify them to address your business needs.

-# Tutorial - Customize user provisioning attribute-mappings for SaaS applications in Microsoft Entra ID

-Microsoft Entra ID provides support for user provisioning to third-party SaaS applications such as Salesforce, G Suite and others. If you enable user provisioning for a third-party SaaS application, the Microsoft Entra admin center controls its attribute values through attribute-mappings.

-Before you get started, make sure you're familiar with app management and **single sign-on (SSO)** concepts. Check out the following links:

-There's a preconfigured set of attributes and attribute-mappings between Microsoft Entra user objects and each SaaS app's user objects. Some apps manage other types of objects along with Users, such as Groups.

-You can customize the default attribute-mappings according to your business needs. So, you can change or delete existing attribute-mappings, or create new attribute-mappings.

-## Editing user attribute-mappings

-Follow these steps to access the **Mappings** feature of user provisioning:

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. A list of all configured apps is shown, including apps that were added from the gallery.

-1. Select any app to load its app management pane, where you can view reports and manage app settings.

-1. Select **Provisioning** to manage user account provisioning settings for the selected app.

-1. Expand **Mappings** to view and edit the user attributes that flow between Microsoft Entra ID and the target application. If the target application supports it, this section lets you optionally configure provisioning of groups and user accounts.

- 

-1. Select a **Mappings** configuration to open the related **Attribute Mapping** screen. SaaS applications require certain attribute-mappings to function correctly. For required attributes, the **Delete** feature is unavailable.

- 

- In this screenshot, you can see that the **Username** attribute of a managed object in Salesforce is populated with the **userPrincipalName** value of the linked Microsoft Entra Object.

-

- > [!NOTE]

- > Clearing **Create** doesn't affect existing users. If **Create** isn't selected, you can't create new users.

-1. Select an existing **Attribute Mapping** to open the **Edit Attribute** screen. Here you can edit the user attributes that flow between Microsoft Entra ID and the target application.

- 

-### Understanding attribute-mapping types

-With attribute-mappings, you control how attributes are populated in a third-party SaaS application.

-There are four different mapping types supported:

-Along with these four basic types, custom attribute-mappings support the concept of an optional **default** value assignment. The default value assignment ensures that a target attribute is populated with a value if there's not a value in Microsoft Entra ID or on the target object. The most common configuration is to leave this blank.

-### Understanding attribute-mapping properties

-In the previous section, you were introduced to the attribute-mapping type property.

-Along with this property, attribute-mappings also supports the attributes:

- - **Always** ΓÇô Apply this mapping on both user creation and update actions.

- - **Only during creation** - Apply this mapping only on user creation actions.

-## Matching users in the source and target systems

-The Microsoft Entra provisioning service can be deployed in both "green field" scenarios (where users don't exist in the target system) and "brownfield" scenarios (where users already exist in the target system). To support both scenarios, the provisioning service uses the concept of matching attributes. Matching attributes allow you to determine how to uniquely identify a user in the source and match the user in the target. As part of planning your deployment, identify the attribute that can be used to uniquely identify a user in the source and target systems. Things to note:

-## Editing group attribute-mappings

-A selected number of applications, such as ServiceNow, Box, and G Suite, support the ability to provision Group objects and User objects. Group objects can contain group properties such as display names and email aliases, along with group members.

-

-Group provisioning can be optionally enabled or disabled by selecting the group mapping under **Mappings**, and setting **Enabled** to the option you want in the **Attribute Mapping** screen.

-The attributes provisioned as part of Group objects can be customized in the same manner as User objects, described previously.

-> [!TIP]

-> Provisioning of group objects (properties and members) is a distinct concept from [assigning groups](../manage-apps/assign-user-or-group-access-portal.md) to an application. It's possible to assign a group to an application, but only provision the user objects contained in the group. Provisioning of full group objects isn't required to use groups in assignments.

-## Editing the list of supported attributes

-The user attributes supported for a given application are preconfigured. Most application's user management APIs don't support schema discovery. So, the Microsoft Entra provisioning service isn't able to dynamically generate the list of supported attributes by making calls to the application.

-However, some applications support custom attributes, and the Microsoft Entra provisioning service can read and write to custom attributes. To enter their definitions into the Microsoft Entra admin center, select the **Show advanced options** check box at the bottom of the **Attribute Mapping** screen, and then select **Edit attribute list for** your app.

-Applications and systems that support customization of the attribute list include:

-> [!NOTE]

-> Editing the list of supported attributes is only recommended for administrators who have customized the schema of their applications and systems, and have first-hand knowledge of how their custom attributes have been defined or if a source attribute isn't automatically displayed in the Microsoft Entra admin center UI. This sometimes requires familiarity with the APIs and developer tools provided by an application or system. The ability to edit the list of supported attributes is locked down by default, but customers can enable the capability by navigating to the following URL: https://portal.azure.com/?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true . You can then navigate to your application to view the [attribute list](#editing-the-list-of-supported-attributes).

-> [!NOTE]

-> When a directory extension attribute in Microsoft Entra ID doesn't show up automatically in your attribute mapping drop-down, you can manually add it to the "Microsoft Entra attribute list". When manually adding Microsoft Entra directory extension attributes to your provisioning app, note that directory extension attribute names are case-sensitive. For example: If you have a directory extension attribute named `extension_53c9e2c0exxxxxxxxxxxxxxxx_acmeCostCenter`, make sure you enter it in the same format as defined in the directory. Provisioning multi-valued directory extension attributes is not supported.

-When you're editing the list of supported attributes, the following properties are provided:

- - *Binary* - Attribute contains binary data.

- - *Boolean* - Attribute contains a True or False value.

- - *DateTime* - Attribute contains a date string.

- - *Integer* - Attribute contains an integer.

- - *Reference* - Attribute contains an ID that references a value stored in another table in the target application.

- - *String* - Attribute contains a text string.

-#### Provisioning a custom extension attribute to a SCIM compliant application

-The SCIM RFC defines a core user and group schema, while also allowing for extensions to the schema to meet your application's needs. To add a custom attribute to a SCIM application:

- 1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

- 1. Browse to **Identity** > **Applications** > **Enterprise applications**.

- 1. Select your application, and then select **Provisioning**.

- 1. Under **Mappings**, select the object (user or group) for which you'd like to add a custom attribute.

- 1. At the bottom of the page, select **Show advanced options**.

- 1. Select **Edit attribute list for AppName**.

- 1. At the bottom of the attribute list, enter information about the custom attribute in the fields provided. Then select **Add Attribute**.

-For SCIM applications, the attribute name must follow the pattern shown in the example. The "CustomExtensionName" and "CustomAttribute" can be customized per your application's requirements, for example: urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:CustomAttribute

-These instructions are only applicable to SCIM-enabled applications. Applications such as ServiceNow and Salesforce aren't integrated with Microsoft Entra ID using SCIM, and therefore they don't require this specific namespace when adding a custom attribute.

-Custom attributes can't be referential attributes, multi-value or complex-typed attributes. Custom multi-value and complex-typed extension attributes are currently supported only for applications in the gallery. The custom extension schema header is omitted in the example because it isn't sent in requests from the Microsoft Entra SCIM client.

-

-**Example representation of a user with an extension attribute:**

-```json

-{

- "schemas":[

- "urn:ietf:params:scim:schemas:core:2.0:User",

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"

- ],

- "userName":"bjensen",

- "id": "48af03ac28ad4fb88478",

- "externalId":"bjensen",

- "name":{

- "formatted":"Ms. Barbara J Jensen III",

- "familyName":"Jensen",

- "givenName":"Barbara"

- },

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

- "employeeNumber": "701984",

- "costCenter": "4130",

- "organization": "Universal Studios",

- "division": "Theme Park",

- "department": "Tour Operations",

- "manager": {

- "value": "26118915-6090-4610-87e4-49d8ca9f808d",

- "$ref": "../Users/26118915-6090-4610-87e4-49d8ca9f808d",

- "displayName": "John Smith"

- }

- },

- "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User": {

- "CustomAttribute": "701984",

- },

- "meta": {

- "resourceType": "User",

- "created": "2010-01-23T04:56:22Z",

- "lastModified": "2011-05-13T04:42:34Z",

- "version": "W\/\"3694e05e9dff591\"",

- "location": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646"

- }

-}

-```

-## Provisioning a role to a SCIM app

-Use the steps in the example to provision roles for a user to your application. The description is specific to custom SCIM applications. For gallery applications such as Salesforce and ServiceNow, use the predefined role mappings. The bullets describe how to transform the AppRoleAssignments attribute to the format your application expects.

- - **When to use:** Use the SingleAppRoleAssignment expression to provision a single role for a user and to specify the primary role.

- - **How to configure:** Use the steps described to navigate to the attribute mappings page and use the SingleAppRoleAssignment expression to map to the roles attribute. There are three role attributes to choose from (`roles[primary eq "True"].display`, `roles[primary eq "True"].type`, and `roles[primary eq "True"].value`). You can choose to include any or all of the role attributes in your mappings. If you would like to include more than one, just add a new mapping and include it as the target attribute.

- 

- - **Things to consider**

- - Ensure that multiple roles aren't assigned to a user. There's no guarantee which role is provisioned.

- - SingleAppRoleAssignments isn't compatible with setting scope to "Sync All users and groups."

- - **Example request (POST)**

- ```json

- {

- "schemas": [

- "urn:ietf:params:scim:schemas:core:2.0:User"

- ],

- "externalId": "alias",

- "userName": "alias@contoso.OnMicrosoft.com",

- "active": true,

- "displayName": "First Name Last Name",

- "meta": {

- "resourceType": "User"

- },

- "roles": [

- {

- "primary": true,

- "type": "WindowsAzureActiveDirectoryRole",

- "value": "Admin"

- }

- ]

- }

- ```

- - **Example output (PATCH)**

- ```json

- "Operations": [

- {

- "op": "Add",

- "path": "roles",

- "value": [

- {

- "value": "{\"id\":\"06b07648-ecfe-589f-9d2f-6325724a46ee\",\"value\":\"25\",\"displayName\":\"Role1234\"}"

- }

- ]

- }

- ]

- ```

-The request formats in the PATCH and POST differ. To ensure that POST and PATCH are sent in the same format, you can use the feature flag described [here](./application-provisioning-config-problem-scim-compatibility.md#flags-to-alter-the-scim-behavior).

- - **When to use:** Use the AppRoleAssignmentsComplex expression to provision multiple roles for a user.

- - **How to configure:** Edit the list of supported attributes as described to include a new attribute for roles:

-

- <br>

- Then use the AppRoleAssignmentsComplex expression to map to the custom role attribute as shown in the image:

- <br>

- - **Things to consider**

- - All roles are provisioned as primary = false.

- - The POST contains the role type. The PATCH request doesn't contain type. We're working on sending the type in both POST and PATCH requests.

- - AppRoleAssignmentsComplex isn't compatible with setting scope to "Sync All users and groups."

- - The AppRoleAssignmentsComplex only supports the PATCH add function. For multi-role SCIM applications, roles deleted in Microsoft Entra ID will therefore not be deleted from the application. We're working to support additional PATCH functions and address the limitation.

-

- - **Example output**

-

- ```json

- {

- "schemas": [

- "urn:ietf:params:scim:schemas:core:2.0:User"

- ],

- "externalId": "alias",

- "userName": "alias@contoso.OnMicrosoft.com",

- "active": true,

- "displayName": "First Name Last Name",

- "meta": {

- "resourceType": "User"

- },

- "roles": [

- {

- "primary": false,

- "type": "WindowsAzureActiveDirectoryRole",

- "display": "Admin",

- "value": "Admin"

- },

- {

- "primary": false,

- "type": "WindowsAzureActiveDirectoryRole",

- "display": "User",

- "value": "User"

- }

- ]

- }

- ```

-## Provisioning a multi-value attribute

-Certain attributes such as phoneNumbers and emails are multi-value attributes where you may need to specify different types of phone numbers or emails. Use the expression for multi-value attributes. It allows you to specify the attribute type and map that to the corresponding Microsoft Entra user attribute for the value.

-* `phoneNumbers[type eq "work"].value`

-* `phoneNumbers[type eq "mobile"]`.value

-* `phoneNumbers[type eq "fax"].value`

- ```json

- "phoneNumbers": [

- {

- "value": "555-555-5555",

- "type": "work"

- },

- {

- "value": "555-555-5555",

- "type": "mobile"

- },

- {

- "value": "555-555-5555",

- "type": "fax"

- }

- ]

- ```

-## Restoring the default attributes and attribute-mappings

-Should you need to start over and reset your existing mappings back to their default state, you can select the **Restore default mappings** check box and save the configuration. Doing so sets all mappings and scoping filters as if the application was added to your Microsoft Entra tenant from the application gallery.

-Selecting this option forces a resynchronization of all users while the provisioning service is running.

-> [!IMPORTANT]

-> We strongly recommend that **Provisioning status** be set to **Off** before invoking this option.

-## What you should know

-## Next steps

-description: Learn how to use scoping filters to define attribute-based rules that determine which users or groups are provisioned in Microsoft Entra ID.

-zone_pivot_groups: app-provisioning-cross-tenant-synchronization

-# Scoping users or groups to be provisioned with scoping filters

-Learn how to use scoping filters in the Microsoft Entra provisioning service to define attribute based rules. The rules are used to determine which users or groups are provisioned.

-## Scoping filter use cases

-You use scoping filters to prevent objects in applications that support automated user provisioning from being provisioned if an object doesn't satisfy your business requirements. A scoping filter allows you to include or exclude any users who have an attribute that matches a specific value. For example, when provisioning users from Microsoft Entra ID to a SaaS application used by a sales team, you can specify that only users with a "Department" attribute of "Sales" should be in scope for provisioning.

-Scoping filters can be used differently depending on the type of provisioning connector:

-* **Outbound provisioning from Microsoft Entra ID to SaaS applications**. When Microsoft Entra ID is the source system, [user and group assignments](../manage-apps/assign-user-or-group-access-portal.md) are the most common method for determining which users are in scope for provisioning. These assignments also are used for enabling single sign-on and provide a single method to manage access and provisioning. Scoping filters can be used optionally, in addition to assignments or instead of them, to filter users based on attribute values.

- >[!TIP]

- > The more users and groups in scope for provisioning, the longer the synchronization process can take. Setting the scope to sync assigned users and groups, limiting the number of groups assigned to the app, and limiting the size of the groups will reduce the time it takes to synchronize everyone that is in scope.

-* **Inbound provisioning from HCM applications to Microsoft Entra ID and Active Directory**. When an [HCM application such as Workday](../saas-apps/workday-tutorial.md) is the source system, scoping filters are the primary method for determining which users should be provisioned from the HCM application to Active Directory or Microsoft Entra ID.

-By default, Microsoft Entra provisioning connectors don't have any attribute-based scoping filters configured.

-When Microsoft Entra ID is the source system, [user and group assignments](../manage-apps/assign-user-or-group-access-portal.md) are the most common method for determining which users are in scope for provisioning. Reducing the number of users in scope improves performance and synchronizing assigned users and groups instead of synchronizing all users and groups is recommended.

-Scoping filters can be used optionally, in addition to scoping by assignment. A scoping filter allows the Microsoft Entra provisioning service to include or exclude any users who have an attribute that matches a specific value. For example, when provisioning users from a sales team, you can specify that only users with a "Department" attribute of "Sales" should be in scope for provisioning.

-## Scoping filter construction

-A scoping filter consists of one or more *clauses*. Clauses determine which users are allowed to pass through the scoping filter by evaluating each user's attributes. For example, you might have one clause that requires that a user's "State" attribute equals "New York", so only New York users are provisioned into the application.

-A single clause defines a single condition for a single attribute value. If multiple clauses are created in a single scoping filter, they're evaluated together using "AND" logic. The "AND" logic means all clauses must evaluate to "true" in order for a user to be provisioned.

-Finally, multiple scoping filters can be created for a single application. If multiple scoping filters are present, they're evaluated together by using "OR" logic. The "OR" logic means that if all the clauses in any of the configured scoping filters evaluate to "true", the user is provisioned.

-Each user or group processed by the Microsoft Entra provisioning service is always evaluated individually against each scoping filter.

-As an example, consider the following scoping filter:

-

-According to this scoping filter, users must satisfy the following criteria to be provisioned:

-* They must be in New York.

-* They must work in the Engineering department.

-* Their company employee ID must be between 1,000,000 and 2,000,000.

-* Their job title must not be null or empty.

-## Create scoping filters

-Scoping filters are configured as part of the attribute mappings for each Microsoft Entra user provisioning connector. The following procedure assumes that you already set up automatic provisioning for [one of the supported applications](../saas-apps/tutorial-list.md) and are adding a scoping filter to it.

-### Create a scoping filter

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-2. Browse to **Identity** > **Applications** > **Enterprise applications** > **All applications**.

-3. Select the application for which you have configured automatic provisioning: for example, "ServiceNow".

-2. Browse to **Identity** > **External Identities** > **Cross-tenant Synchronization** > **Configurations**

-3. Select your configuration.

-4. Select the **Provisioning** tab.

-5. In the **Mappings** section, select the mapping that you want to configure a scoping filter for: for example, "Synchronize Microsoft Entra users to ServiceNow".

-5. In the **Mappings** section, select the mapping that you want to configure a scoping filter for: for example, "Provision Microsoft Entra users".

-6. Select the **Source object scope** menu.

-7. Select **Add scoping filter**.

-8. Define a clause by selecting a source **Attribute Name**, an **Operator**, and an **Attribute Value** to match against. The following operators are supported:

- a. **EQUALS**. Clause returns "true" if the evaluated attribute matches the input string value exactly (case sensitive).

- b. **NOT EQUALS**. Clause returns "true" if the evaluated attribute doesn't match the input string value (case sensitive).

- c. **IS TRUE**. Clause returns "true" if the evaluated attribute contains a Boolean value of true.

- d. **IS FALSE**. Clause returns "true" if the evaluated attribute contains a Boolean value of false.

- e. **IS NULL**. Clause returns "true" if the evaluated attribute is empty.

- f. **IS NOT NULL**. Clause returns "true" if the evaluated attribute isn't empty.

- g. **REGEX MATCH**. Clause returns "true" if the evaluated attribute matches a regular expression pattern. For example: `([1-9][0-9])` matches any number between 10 and 99 (case sensitive).

- h. **NOT REGEX MATCH**. Clause returns "true" if the evaluated attribute doesn't match a regular expression pattern. It returns "false" if the attribute is null / empty.

-

- i. **Greater_Than.** Clause returns "true" if the evaluated attribute is greater than the value. The value specified on the scoping filter must be an integer and the attribute on the user must be an integer [0,1,2,...].

-

- j. **Greater_Than_OR_EQUALS.** Clause returns "true" if the evaluated attribute is greater than or equal to the value. The value specified on the scoping filter must be an integer and the attribute on the user must be an integer [0,1,2,...].

-

- k. **Includes.** Clause returns "true" if the evaluated attribute contains the string value (case sensitive) as described [here](/dotnet/api/system.string.contains).

->[!IMPORTANT]

-> - The IsMemberOf filter is not supported currently.

-> - The members attribute on a group is not supported currently.

-> - Filtering is not supported for multi-valued attributes.

-> - Scoping filters will return "false" if the value is null / empty.

-9. Optionally, repeat steps 7-8 to add more scoping clauses.

-10. In **Scoping Filter Title**, add a name for your scoping filter.

-11. Select **OK**.

-12. Select **OK** again on the **Scoping Filters** screen. Optionally, repeat steps 6-11 to add another scoping filter.

-13. Select **Save** on the **Attribute Mapping** screen.

->[!IMPORTANT]

-> Saving a new scoping filter triggers a new full sync for the application, where all users in the source system are evaluated again against the new scoping filter. If a user in the application was previously in scope for provisioning, but falls out of scope, their account is disabled or deprovisioned in the application. To override this default behavior, refer to [Skip deletion for user accounts that go out of scope](../app-provisioning/skip-out-of-scope-deletions.md).

-## Common scoping filters

-| Target Attribute| Operator | Value | Description|

-|-|-|-|-|

-|userPrincipalName|REGEX MATCH|`.*\@domain.com`|All users with `userPrincipal` that have the domain `@domain.com` are in scope for provisioning. |

-|userPrincipalName|NOT REGEX MATCH|`.*\@domain.com`|All users with `userPrincipal` that has the domain `@domain.com` are out of scope for provisioning. |

-|department|EQUALS|`sales`|All users from the sales department are in scope for provisioning|

-|workerID|REGEX MATCH|`(1[0-9][0-9][0-9][0-9][0-9][0-9])`| All employees with `workerID` between 1000000 and 2000000 are in scope for provisioning.|

-## Related articles

-* [Automate user provisioning and deprovisioning to SaaS applications](../app-provisioning/user-provisioning.md)

-* [Customize attribute mappings for user provisioning](../app-provisioning/customize-application-attributes.md)

-* [Write expressions for attribute mappings](functions-for-customizing-application-data.md)

-* [Account provisioning notifications](../app-provisioning/user-provisioning.md)

-* [Use SCIM to enable automatic provisioning of users and groups from Microsoft Entra ID to applications](../app-provisioning/use-scim-to-provision-users-and-groups.md)

-* [List of tutorials on how to integrate SaaS apps](../saas-apps/tutorial-list.md)

-description: Learn how to export your Application Provisioning configuration and roll back to a known good state for disaster recovery in Microsoft Entra ID.

-# How-to: Export provisioning configuration and roll back to a known good state

-In this article, you learn how to:

-## Export and import your provisioning configuration from the Microsoft Entra admin center

-### Export your provisioning configuration

-To export your configuration:

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications** and choose your application.

-1. In the left navigation pane, select **provisioning**. From the provisioning configuration page, click on **attribute mappings**, then **show advanced options**, and finally **review your schema**. The schema editor opens.

-1. Click on download in the command bar at the top of the page to download your schema.

-### Disaster recovery - roll back to a known good state

-Exporting and saving your configuration allows you to roll back to a previous version of your configuration. We recommend exporting your provisioning configuration and saving it for later use anytime you make a change to your attribute mappings or scoping filters. Open the JSON file that you downloaded, copy the entire contents. Next, replace the entire contents of the JSON payload in the schema editor, and then save. If there's an active provisioning cycle, it completes and the next cycle uses the updated schema. The next cycle is also an initial cycle, which reevaluates every user and group based on the new configuration.

-Some things to consider when rolling back to a previous configuration:

-## Export and import your provisioning configuration by using the Microsoft Graph API

-You can use the Microsoft Graph API and the Microsoft Graph Explorer to export your User Provisioning attribute mappings and schema to a JSON file and import it back into Microsoft Entra ID. You can also use the steps captured here to create a backup of your provisioning configuration.

-### Step 1: Retrieve your Provisioning App Service Principal ID (Object ID)

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com), and navigate to the Properties section of your provisioning application. For example, if you want to export your *Workday to AD User Provisioning application* mapping navigate to the Properties section of that app.

-1. In the Properties section of your provisioning app, copy the GUID value associated with the *Object ID* field. This value is also called the **ServicePrincipalId** of your App and it's used in Microsoft Graph Explorer operations.

- 

-### Step 2: Sign into Microsoft Graph Explorer

-1. Launch [Microsoft Graph Explorer](https://developer.microsoft.com/graph/graph-explorer)

-1. Click on the "Sign-In with Microsoft" button and sign-in using Microsoft Entra Global Administrator or App Admin credentials.

- 

-1. Upon successful sign-in, you see the user account details in the left-hand pane.

-### Step 3: Retrieve the Provisioning Job ID of the Provisioning App

-In the Microsoft Graph Explorer, run the following GET query replacing [servicePrincipalId] with the **ServicePrincipalId** extracted from the [Step 1](#step-1-retrieve-your-provisioning-app-service-principal-id-object-id).

-```http

- GET https://graph.microsoft.com/beta/servicePrincipals/[servicePrincipalId]/synchronization/jobs

-```

-You get a response as shown. Copy the `id` attribute present in the response. This value is the **ProvisioningJobId** and is used to retrieve the underlying schema metadata.

- [](./media/export-import-provisioning-configuration/wd_export_03.png#lightbox)

-### Step 4: Download the Provisioning Schema

-In the Microsoft Graph Explorer, run the following GET query, replacing [servicePrincipalId] and [ProvisioningJobId] with the ServicePrincipalId and the ProvisioningJobId retrieved in the previous steps.

-```http

- GET https://graph.microsoft.com/beta/servicePrincipals/[servicePrincipalId]/synchronization/jobs/[ProvisioningJobId]/schema

-```

-Copy the JSON object from the response and save it to a file to create a backup of the schema.

-### Step 5: Import the Provisioning Schema

-> [!CAUTION]

-> Perform this step only if you need to modify the schema for configuration that cannot be changed using the Microsoft Entra admin center or if you need to restore the configuration from a previously backed up file with valid and working schema.

-In the Microsoft Graph Explorer, configure the following PUT query, replacing [servicePrincipalId] and [ProvisioningJobId] with the ServicePrincipalId and the ProvisioningJobId retrieved in the previous steps.

-```http

- PUT https://graph.microsoft.com/beta/servicePrincipals/[servicePrincipalId]/synchronization/jobs/[ProvisioningJobId]/schema

-```

-In the "Request Body" tab, copy the contents of the JSON schema file.

- [](./media/export-import-provisioning-configuration/wd_export_04.png#lightbox)

-In the "Request Headers" tab, add the Content-Type header attribute with value ΓÇ£application/jsonΓÇ¥

- [](./media/export-import-provisioning-configuration/wd_export_05.png#lightbox)

-Select **Run Query** to import the new schema.

-description: Understand how expression builder works with Application Provisioning in Microsoft Entra ID.

-# Understand how expression builder in Application Provisioning works

-You can use [expressions](functions-for-customizing-application-data.md) to [map attributes](./customize-application-attributes.md). Previously, you had to create these expressions manually and enter them into the expression box. Expression builder is a tool you can use to help you create expressions.

-For reference on building expressions, see [Reference for writing expressions for attribute mappings](functions-for-customizing-application-data.md).

-## Finding the expression builder

-In application provisioning, you use expressions for attribute mappings. You access Express Builder on the attribute-mapping page by selecting **Show advanced options** and then select **Expression builder**.

-## Using expression builder

-To use expression builder, select a function and attribute and then enter a suffix if needed. Then select **Add expression** to add the expression to the code box. To learn more about the functions available and how to use them, see [Reference for writing expressions for attribute mappings](functions-for-customizing-application-data.md).

-Test the expression by searching for a user or providing values and selecting **Test expression**. The output of the expression test appears in the **View expression output** box.

-When you're satisfied with the expression, move it to an attribute mapping. Copy and paste it into the expression box for the attribute mapping you're working on.

-## Known limitations

-* Extension attributes aren't available for selection in the expression builder. However, extension attributes can be used in the attribute mapping expression.

-## Next steps

-[Reference for writing expressions for attribute mappings](functions-for-customizing-application-data.md)

-description: Learn how to use expression mappings to transform attribute values into an acceptable format during automated provisioning of SaaS app objects in Microsoft Entra ID. Includes a reference list of functions.

-# Reference for writing expressions for attribute mappings in Microsoft Entra ID

-When you configure provisioning to a SaaS application, one of the types of attribute mappings that you can specify is an expression mapping. For these mappings, you must write a script-like expression that allows you to transform your users' data into formats that are more acceptable for the SaaS application.

-## Syntax overview

-The syntax for Expressions for Attribute Mappings is reminiscent of Visual Basic for Applications (VBA) functions.

-* The entire expression must be defined in terms of functions, which consist of a name followed by arguments in parentheses:

- *FunctionName(`<<argument 1>>`,`<<argument N>>`)*

-* You may nest functions within each other. For example: *FunctionOne(FunctionTwo(`<<argument1>>`))*

-* You can pass three different types of arguments into functions:

-

- 1. Attributes, which must be enclosed in square brackets. For example: [attributeName]

- 2. String constants, which must be enclosed in double quotes. For example: "United States"

- 3. Other Functions. For example: FunctionOne(`<<argument1>>`, FunctionTwo(`<<argument2>>`))

-* For string constants, if you need a backslash ( \ ) or quotation mark ( " ) in the string, it must be escaped with the backslash ( \ ) symbol. For example: "Company name: \\"Contoso\\""

-* The syntax is case-sensitive, which must be considered while typing them as strings in a function vs copy pasting them directly from here.

-## List of Functions

-[Append](#append) &nbsp;&nbsp;&nbsp;&nbsp; [AppRoleAssignmentsComplex](#approleassignmentscomplex) &nbsp;&nbsp;&nbsp;&nbsp; [BitAnd](#bitand) &nbsp;&nbsp;&nbsp;&nbsp; [CBool](#cbool) &nbsp;&nbsp;&nbsp;&nbsp; [CDate](#cdate) &nbsp;&nbsp;&nbsp;&nbsp; [Coalesce](#coalesce) &nbsp;&nbsp;&nbsp;&nbsp; [ConvertToBase64](#converttobase64) &nbsp;&nbsp;&nbsp;&nbsp; [ConvertToUTF8Hex](#converttoutf8hex) &nbsp;&nbsp;&nbsp;&nbsp; [Count](#count) &nbsp;&nbsp;&nbsp;&nbsp; [CStr](#cstr) &nbsp;&nbsp;&nbsp;&nbsp; [DateAdd](#dateadd) &nbsp;&nbsp;&nbsp;&nbsp; [DateDiff](#datediff) &nbsp;&nbsp;&nbsp;&nbsp; [DateFromNum](#datefromnum) &nbsp;[FormatDateTime](#formatdatetime) &nbsp;&nbsp;&nbsp;&nbsp; [Guid](#guid) &nbsp;&nbsp;&nbsp;&nbsp; [IgnoreFlowIfNullOrEmpty](#ignoreflowifnullorempty) &nbsp;&nbsp;&nbsp;&nbsp;[IIF](#iif) &nbsp;&nbsp;&nbsp;&nbsp;[InStr](#instr) &nbsp;&nbsp;&nbsp;&nbsp; [IsNull](#isnull) &nbsp;&nbsp;&nbsp;&nbsp; [IsNullOrEmpty](#isnullorempty) &nbsp;&nbsp;&nbsp;&nbsp; [IsPresent](#ispresent) &nbsp;&nbsp;&nbsp;&nbsp; [IsString](#isstring) &nbsp;&nbsp;&nbsp;&nbsp; [Item](#item) &nbsp;&nbsp;&nbsp;&nbsp; [Join](#join) &nbsp;&nbsp;&nbsp;&nbsp; [Left](#left) &nbsp;&nbsp;&nbsp;&nbsp; [Mid](#mid) &nbsp;&nbsp;&nbsp;&nbsp; [NormalizeDiacritics](#normalizediacritics) &nbsp;&nbsp; &nbsp;&nbsp; [Not](#not) &nbsp;&nbsp;&nbsp;&nbsp; [Now](#now) &nbsp;&nbsp;&nbsp;&nbsp; [NumFromDate](#numfromdate) &nbsp;&nbsp;&nbsp;&nbsp; [PCase](#pcase) &nbsp;&nbsp;&nbsp;&nbsp; [RandomString](#randomstring) &nbsp;&nbsp;&nbsp;&nbsp; [Redact](#redact) &nbsp;&nbsp;&nbsp;&nbsp; [RemoveDuplicates](#removeduplicates) &nbsp;&nbsp;&nbsp;&nbsp; [Replace](#replace) &nbsp;&nbsp;&nbsp;&nbsp; [SelectUniqueValue](#selectuniquevalue)&nbsp;&nbsp;&nbsp;&nbsp; [SingleAppRoleAssignment](#singleapproleassignment)&nbsp;&nbsp;&nbsp;&nbsp; [Split](#split)&nbsp;&nbsp;&nbsp;&nbsp;[StripSpaces](#stripspaces) &nbsp;&nbsp;&nbsp;&nbsp; [Switch](#switch)&nbsp;&nbsp;&nbsp;&nbsp; [ToLower](#tolower)&nbsp;&nbsp;&nbsp;&nbsp; [ToUpper](#toupper)&nbsp;&nbsp;&nbsp;&nbsp; [Word](#word)

-### Append

-**Function:**

-Append(source, suffix)

-**Description:**

-Takes a source string value and appends the suffix to the end of it.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source** |Required |String |Usually name of the attribute from the source object. |

-| **suffix** |Required |String |The string that you want to append to the end of the source value. |

-#### Append constant suffix to user name

-Example: If you're using a Salesforce Sandbox, you might need to append another suffix to all your user names before synchronizing them.

-**Expression:**

-`Append([userPrincipalName], ".test")`

-**Sample input/output:**

-* **INPUT**: (userPrincipalName): "John.Doe@contoso.com"

-* **OUTPUT**: "John.Doe@contoso.com.test"

-### AppRoleAssignmentsComplex

-**Function:**

-AppRoleAssignmentsComplex([appRoleAssignments])

-**Description:**

-Used to provision multiple roles for a user. For detailed usage, see [Tutorial - Customize user provisioning attribute-mappings for SaaS applications in Microsoft Entra ID](customize-application-attributes.md#provisioning-a-role-to-a-scim-app).

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **[appRoleAssignments]** |Required |String |**[appRoleAssignments]** object. |

-### BitAnd

-**Function:**

-BitAnd(value1, value2)

-**Description:**

-This function converts both parameters to the binary representation and sets a bit to:

-In other words, it returns 0 in all cases except when the corresponding bits of both parameters are 1.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **value1** |Required |Num |Numeric value that should be AND'ed with value2|

-| **value2** |Required |Num |Numeric value that should be AND'ed with value1|

-**Example:**

-`BitAnd(&HF, &HF7)`

-11110111 AND 00000111 = 00000111 so `BitAnd` returns 7, the binary value of 00000111.

-### CBool

-**Function:**

-`CBool(Expression)`

-**Description:**

-`CBool` returns a boolean based on the evaluated expression. If the expression evaluates to a non-zero value, then `CBool` returns *True*, else it returns *False*.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **Expression** |Required | expression | Any valid expression |

-**Example:**

-`CBool([attribute1] = [attribute2])`

-Returns True if both attributes have the same value.

-### CDate

-**Function:**

-`CDate(expression)`

-**Description:**

-The CDate function returns a UTC DateTime from a string. DateTime isn't a native attribute type but it can be used within date functions such as [FormatDateTime](#formatdatetime) and [DateAdd](#dateadd).

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **Expression** |Required | Expression | Any valid string that represents a date/time. For supported formats, refer to [.NET custom date and time format strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). |

-**Remarks:**

-The returned string is always in UTC and follows the format **M/d/yyyy h:mm:ss tt**.

-**Example 1:** <br>

-`CDate([StatusHireDate])`

-**Sample input/output:**

-* **INPUT** (StatusHireDate): "2020-03-16-07:00"

-* **OUTPUT**: "3/16/2020 7:00:00 AM" <-- *Note that UTC equivalent of the above DateTime is returned*

-**Example 2:** <br>

-`CDate("2021-06-30+08:00")`

-**Sample input/output:**

-* **INPUT**: "2021-06-30+08:00"

-* **OUTPUT**: "6/29/2021 4:00:00 PM" <-- *Note that UTC equivalent of the above DateTime is returned*

-**Example 3:** <br>

-`CDate("2009-06-15T01:45:30-07:00")`

-**Sample input/output:**

-* **INPUT**: "2009-06-15T01:45:30-07:00"

-* **OUTPUT**: "6/15/2009 8:45:30 AM" <-- *Note that UTC equivalent of the above DateTime is returned*

-### Coalesce

-**Function:**

-Coalesce(source1, source2, ..., defaultValue)

-**Description:**

-Returns the first source value that isn't NULL. If all arguments are NULL and defaultValue is present, the defaultValue will be returned. If all arguments are NULL and defaultValue isn't present, Coalesce returns NULL.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source1 … sourceN** | Required | String |Required, variable-number of times. Usually name of the attribute from the source object. |

-| **defaultValue** | Optional | String | Default value to be used when all source values are NULL. Can be empty string ("").

-#### Flow mail value if not NULL, otherwise flow userPrincipalName

-Example: You wish to flow the mail attribute if it is present. If it isn't, you wish to flow the value of userPrincipalName instead.

-**Expression:**

-`Coalesce([mail],[userPrincipalName])`

-**Sample input/output:**

-* **INPUT** (mail): NULL

-* **INPUT** (userPrincipalName): "John.Doe@contoso.com"

-* **OUTPUT**: "John.Doe@contoso.com"

-### ConvertToBase64

-**Function:**

-ConvertToBase64(source)

-**Description:**

-The ConvertToBase64 function converts a string to a Unicode base64 string.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source** |Required |String |String to be converted to base 64|

-**Example:**

-`ConvertToBase64("Hello world!")`

-Returns "SABlAGwAbABvACAAdwBvAHIAbABkACEA"

-### ConvertToUTF8Hex

-**Function:**

-ConvertToUTF8Hex(source)

-**Description:**

-The ConvertToUTF8Hex function converts a string to a UTF8 Hex encoded value.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source** |Required |String |String to be converted to UTF8 Hex|

-**Example:**

-`ConvertToUTF8Hex("Hello world!")`

-Returns 48656C6C6F20776F726C6421

-### Count

-**Function:**

-Count(attribute)

-**Description:**

-The Count function returns the number of elements in a multi-valued attribute

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **attribute** |Required |attribute |Multi-valued attribute that will have elements counted|

-### CStr

-**Function:**

-CStr(value)

-**Description:**

-The CStr function converts a value to a string data type.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **value** |Required | numeric, reference, or boolean | Can be a numeric value, reference attribute, or Boolean. |

-**Example:**

-`CStr([dn])`

-Returns "cn=Joe,dc=contoso,dc=com"

-### DateAdd

-**Function:**

-`DateAdd(interval, value, dateTime)`

-**Description:**

-Returns a date/time string representing a date to which a specified time interval has been added. The returned date is in the format: **M/d/yyyy h:mm:ss tt**.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **interval** |Required | String | Interval of time you want to add. See accepted values below this table. |

-| **value** |Required | Number | The number of units you want to add. It can be positive (to get dates in the future) or negative (to get dates in the past). |

-| **dateTime** |Required | DateTime | DateTime representing date to which the interval is added. |

-When passing a date string as input, use [CDate](#cdate) function to wrap the datetime string. To get system time in UTC, use the [Now](#now) function.

-The **interval** string must have one of the following values:

- * yyyy Year

- * m Month

- * d Day

- * ww Week

- * h Hour

- * n Minute

- * s Second

-**Example 1: Generate a date value based on incoming StatusHireDate from Workday** <br>

-`DateAdd("d", 7, CDate([StatusHireDate]))`

-| Example | interval | value | dateTime (value of variable StatusHireDate) | output |

-| | | | | |

-| Add 7 days to hire date | "d" | 7 | 2012-03-16-07:00 | 3/23/2012 7:00:00 AM |

-| Get a date ten days prior to hire date | "d" | -10 | 2012-03-16-07:00 | 3/6/2012 7:00:00 AM |

-| Add two weeks to hire date | "ww" | 2 | 2012-03-16-07:00 | 3/30/2012 7:00:00 AM |

-| Add ten months to hire date | "m" | 10 | 2012-03-16-07:00 | 1/16/2013 7:00:00 AM |

-| Add two years to hire date | "yyyy" | 2 | 2012-03-16-07:00 | 3/16/2014 7:00:00 AM |

-### DateDiff

-**Function:**

-`DateDiff(interval, date1, date2)`

-**Description:**

-This function uses the *interval* parameter to return a number that indicates the difference between the two input dates. It returns

- * a positive number if date2 > date1,

- * a negative number if date2 < date1,

- * 0 if date2 == date1

-**Parameters:**

-| Name | Required/Optional | Type | Notes |

-| | | | |

-| **interval** |Required | String | Interval of time to use for calculating the difference. |

-| **date1** |Required | DateTime | DateTime representing a valid date. |

-| **date2** |Required | DateTime | DateTime representing a valid date. |

-When passing a date string as input, use [CDate](#cdate) function to wrap the datetime string. To get system time in UTC, use the [Now](#now) function.

-The **interval** string must have one of the following values:

- * yyyy Year

- * m Month

- * d Day

- * ww Week

- * h Hour

- * n Minute

- * s Second

-**Example 1: Compare current date with hire date from Workday with different intervals** <br>

-`DateDiff("d", Now(), CDate([StatusHireDate]))`

-| Example | interval | date1 | date2 | output |

-| | | | | |

-| Positive difference in days between two dates | d | 2021-08-18+08:00 | 2021-08-31+08:00 | 13 |

-| Negative difference in days between two dates | d | 8/25/2021 5:41:18 PM | 2012-03-16-07:00 | -3449 |

-| Difference in weeks between two dates | ww | 8/25/2021 5:41:18 PM | 2012-03-16-07:00 | -493 |

-| Difference in months between two dates | m | 8/25/2021 5:41:18 PM | 2012-03-16-07:00 | -113 |

-| Difference in years between two dates | yyyy | 8/25/2021 5:41:18 PM | 2012-03-16-07:00 | -9 |

-| Difference when both dates are same | d | 2021-08-31+08:00 | 2021-08-31+08:00 | 0 |

-| Difference in hours between two dates | h | 2021-08-24 | 2021-08-25 | 24 |

-| Difference in minutes between two dates | n | 2021-08-24 | 2021-08-25 | 1440 |

-| Difference in seconds between two dates | s | 2021-08-24 | 2021-08-25 | 86400 |

-**Example 2: Combine DateDiff with IIF function to set attribute value** <br>

-If an account is Active in Workday, set the *accountEnabled* attribute of the user to True only if hire date is within the next five days.

-```

-Switch([Active], ,

- "1", IIF(DateDiff("d", Now(), CDate([StatusHireDate])) > 5, "False", "True"),

- "0", "False")

-```

-### DateFromNum

-**Function:**

-DateFromNum(value)

-**Description:**

-The DateFromNum function converts a value in AD's date format to a DateTime type.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **value** |Required | Date | AD Date to be converted to DateTime type |

-**Example:**

-`DateFromNum([lastLogonTimestamp])`

-`DateFromNum(129699324000000000)`

-Returns a DateTime representing January 1, 2012 at 11:00PM.

-### FormatDateTime

-**Function:**

-FormatDateTime(source, dateTimeStyles, inputFormat, outputFormat)

-**Description:**

-Takes a date string from one format and converts it into a different format.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source** |Required |String |Usually name of the attribute from the source object. |

-| **dateTimeStyles** | Optional | String | Use this parameter to specify the formatting options that customize string parsing for some date and time parsing methods. For supported values, see [DateTimeStyles doc](/dotnet/api/system.globalization.datetimestyles). If left empty, the default value used is DateTimeStyles.RoundtripKind, DateTimeStyles.AllowLeadingWhite, DateTimeStyles.AllowTrailingWhite |

-| **inputFormat** |Required |String |Expected format of the source value. For supported formats, see [.NET custom date and time format strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). |

-| **outputFormat** |Required |String |Format of the output date. |

-#### Output date as a string in a certain format

-Example: You want to send dates to a SaaS application like ServiceNow in a certain format. You can consider using the following expression.

-**Expression:**

-`FormatDateTime([extensionAttribute1], , "yyyyMMddHHmmss.fZ", "yyyy-MM-dd")`

-**Sample input/output:**

-* **INPUT** (extensionAttribute1): "20150123105347.1Z"

-* **OUTPUT**: "2015-01-23"

-### Guid

-**Function:**

-Guid()

-**Description:**

-The function Guid generates a new random GUID

-**Example:** <br>

-`Guid()`<br>

-Sample output: "1088051a-cd4b-4288-84f8-e02042ca72bc"

-### IgnoreFlowIfNullOrEmpty

-**Function:**

-IgnoreFlowIfNullOrEmpty(expression)

-**Description:**

-The IgnoreFlowIfNullOrEmpty function instructs the provisioning service to ignore the attribute and drop it from the flow if the enclosed function or attribute is NULL or empty.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **Expression** | Required | Expression | Expression to be evaluated |

-**Example 1: Don't flow an attribute if it is null** <br>

-`IgnoreFlowIfNullOrEmpty([department])` <br>

-The above expression will drop the department attribute from the provisioning flow if it is null or empty. <br>

-**Example 2: Don't flow an attribute if the expression mapping evaluates to empty string or null** <br>

-Let's say the SuccessFactors attribute *prefix* is mapped to the on-premises Active Directory attribute *personalTitle* using the following expression mapping: <br>

-`IgnoreFlowIfNullOrEmpty(Switch([prefix], "", "3443", "Dr.", "3444", "Prof.", "3445", "Prof. Dr."))` <br>

-The above expression first evaluates the [Switch](#switch) function. If the *prefix* attribute doesn't have any of the values listed within the *Switch* function, then *Switch* will return an empty string and the attribute *personalTitle* will not be included in the provisioning flow to on-premises Active Directory.

-### IIF

-**Function:**

-IIF(condition,valueIfTrue,valueIfFalse)

-**Description:**

-The IIF function returns one of a set of possible values based on a specified condition.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **condition** |Required |Variable or Expression |Any value or expression that can be evaluated to true or false. |

-| **valueIfTrue** |Required |Variable or String | If the condition evaluates to true, the returned value. |

-| **valueIfFalse** |Required |Variable or String |If the condition evaluates to false, the returned value.|

-The following comparison operators can be used in the *condition*:

-* Equal to (=) and not equal to (<>)

-* Greater than (>) and greater than equal to (>=)

-* Less than (<) and less than equal to (<=)

-**Example:** Set the target attribute value to source country attribute if country="USA", else set target attribute value to source department attribute.

-`IIF([country]="USA",[country],[department])`

-#### Known limitations and workarounds for IIF function

-* The IIF function currently doesn't support AND and OR logical operators.

-* To implement AND logic, use nested IIF statement chained along the *trueValue* path.

- Example: If country="USA" and state="CA", return value "True", else return "False".

- `IIF([country]="USA",IIF([state]="CA","True","False"),"False")`

-* To implement OR logic, use nested IIF statement chained along the *falseValue* path.

- Example: If country="USA" or state="CA", return value "True", else return "False".

- `IIF([country]="USA","True",IIF([state]="CA","True","False"))`

-* If the source attribute used within the IIF function is empty or null, the condition check fails.

- * Unsupported IIF expression examples:

- * `IIF([country]="","Other",[country])`

- * `IIF(IsNullOrEmpty([country]),"Other",[country])`

- * `IIF(IsPresent([country]),[country],"Other")`

- * Recommended workaround: Use the [Switch](#switch) function to check for empty/null values. Example: If country attribute is empty, set value "Other". If it is present, pass the country attribute value to target attribute.

- * `Switch([country],[country],"","Other")`

-<br>

-### InStr

-**Function:**

-InStr(value1, value2, start, compareType)

-**Description:**

-The InStr function finds the first occurrence of a substring in a string

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **value1** |Required |String |String to be searched |

-| **value2** |Required |String |String to be found |

-| **start** |Optional |Integer |Starting position to find the substring|

-| **compareType** |Optional |Enum |Can be vbTextCompare or vbBinaryCompare |

-**Example:**

-`InStr("The quick brown fox","quick")`

-Evaluates to 5

-`InStr("repEated","e",3,vbBinaryCompare)`

-Evaluates to 7

-### IsNull

-**Function:**

-IsNull(Expression)

-**Description:**

-If the expression evaluates to Null, then the IsNull function returns true. For an attribute, a Null is expressed by the absence of the attribute.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **Expression** |Required |Expression |Expression to be evaluated |

-**Example:**

-`IsNull([displayName])`

-Returns True if the attribute isn't present.

-### IsNullorEmpty

-**Function:**

-IsNullOrEmpty(Expression)

-**Description:**

-If the expression is null or an empty string, then the IsNullOrEmpty function returns true. For an attribute, this would evaluate to True if the attribute is absent or is present but is an empty string.

-The inverse of this function is named IsPresent.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **Expression** |Required |Expression |Expression to be evaluated |

-**Example:**

-`IsNullOrEmpty([displayName])`

-Returns True if the attribute isn't present or is an empty string.

-### IsPresent

-**Function:**

-IsPresent(Expression)

-**Description:**

-If the expression evaluates to a string that isn't Null and isn't empty, then the IsPresent function returns true. The inverse of this function is named IsNullOrEmpty.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **Expression** |Required |Expression |Expression to be evaluated |

-**Example:**

-`Switch(IsPresent([directManager]),[directManager], IsPresent([skiplevelManager]),[skiplevelManager], IsPresent([director]),[director])`

-### IsString

-**Function:**

-IsString(Expression)

-**Description:**

-If the expression can be evaluated to a string type, then the IsString function evaluates to True.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **Expression** |Required |Expression |Expression to be evaluated |

-### Item

-**Function:**

-Item(attribute, index)

-**Description:**

-The Item function returns one item from a multi-valued string/attribute.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **attribute** |Required |Attribute |Multi-valued attribute to be searched |

-| **index** |Required |Integer | Index to an item in the multi-valued string|

-**Example:**

-`Item([proxyAddresses], 1)` returns the first item in the multi-valued attribute. Index 0 shouldn't be used.

-### Join

-**Function:**

-Join(separator, source1, source2, …)

-**Description:**

-Join() is similar to Append(), except that it can combine multiple **source** string values into a single string, and each value will be separated by a **separator** string.

-If one of the source values is a multi-value attribute, then every value in that attribute will be joined together, separated by the separator value.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **separator** |Required |String |String used to separate source values when they are concatenated into one string. Can be "" if no separator is required. |

-| **source1 … sourceN** |Required, variable-number of times |String |String values to be joined together. |

-### Left

-**Function:**

-Left(String, NumChars)

-**Description:**

-The Left function returns a specified number of characters from the left of a string.

-If numChars = 0, return empty string.

-If numChars < 0, return input string.

-If string is null, return empty string.

-If string contains fewer characters than the number specified in numChars, a string identical to string (that is, containing all characters in parameter 1) is returned.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **String** |Required |Attribute | The string to return characters from |

-| **NumChars** |Required |Integer | A number identifying the number of characters to return from the beginning (left) of string|

-**Example:**

-`Left("John Doe", 3)`

-Returns "Joh".

-### Mid

-**Function:**

-Mid(source, start, length)

-**Description:**

-Returns a substring of the source value. A substring is a string that contains only some of the characters from the source string.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source** |Required |String |Usually name of the attribute. |

-| **start** |Required |Integer |Index in the **source** string where substring should start. First character in the string will have index of 1, second character will have index 2, and so on. |

-| **length** |Required |Integer |Length of the substring. If length ends outside the **source** string, function will return substring from **start** index until end of **source** string. |

-### NormalizeDiacritics

-**Function:**

-NormalizeDiacritics(source)

-**Description:**

-Requires one string argument. Returns the string, but with any diacritical characters replaced with equivalent non-diacritical characters. Typically used to convert first names and last names containing diacritical characters (accent marks) into legal values that can be used in various user identifiers such as user principal names, SAM account names, and email addresses.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source** |Required |String | Usually a first name or last name attribute. |

-| Character with Diacritic | Normalized character | Character with Diacritic | Normalized character |

-| | | | |

-| ä, à, â, ã, å, á, ą, ă, ā, ā́, ā̀, ā̂, ā̃, ǟ, ā̈, ǡ, a̱, å̄ | a | Ä, À, Â, Ã, Å, Á, Ą, Ă, Ā, Ā́, Ā̀, Ā̂, Ā̃, Ǟ, Ā̈, Ǡ, A̱, Å̄ | A |

-| æ, ǣ | ae | Æ, Ǣ | AE |

-| ç, č, ć, c̄, c̱ | c | Ç, Č, Ć, C̄, C̱ | C |

-| ď, d̄, ḏ | d | Ď, D̄, Ḏ | D |

-| ë, è, é, ê, ę, ě, ė, ē, ḗ, ḕ, ē̂, ē̃, ê̄, e̱, ë̄, e̊̄ | e | Ë, È, É, Ê, Ę, Ě, Ė, Ē, Ḗ, Ḕ, Ē̂, Ē̃, Ê̄, E̱, Ë̄, E̊̄ | E |

-| ğ, ḡ, g̱ | g | Ğ, Ḡ, G̱ | G |

-| ï, î, ì, í, ı, ī, ī́, ī̀, ī̂, ī̃, i̱ | i | Ï, Î, Ì, Í, İ, Ī, Ī́, Ī̀, Ī̂, Ī̃, I̱ | I |

-| ľ, ł, l̄, ḹ, ḻ | l | Ł, Ľ, L̄, Ḹ, Ḻ | L |

-| ñ, ń, ň, n̄, ṉ | n | Ñ, Ń, Ň, N̄, Ṉ | N |

-| ö, ò, ő, õ, ô, ó, ō, ṓ, ṑ, ō̂, ō̃, ȫ, ō̈, ǭ, ȭ, ȱ, o̱ | o | Ö, Ò, Ő, Õ, Ô, Ó, Ō, Ṓ, Ṑ, Ō̂, Ō̃, Ȫ, Ō̈, Ǭ, Ȭ, Ȱ, O̱ | O |

-| ø, ø̄, œ̄ | oe | Ø, Ø̄, Œ̄ | OE |

-| ř, r̄, ṟ, ṝ | r | Ř, R̄, Ṟ, Ṝ | R |

-| ß | ss | | |

-| š, ś, ș, ş, s̄, s̱ | s | Š, Ś, Ș, Ş, S̄, S̱ | S |

-| ť, ț, t̄, ṯ | t | Ť, Ț, T̄, Ṯ | T |

-| ü, ù, û, ú, ů, ű, ū, ū́, ū̀, ū̂, ū̃, u̇̄, ǖ, ṻ, ṳ̄, u̱ | u | Ü, Ù, Û, Ú, Ů, Ű, Ū, Ū́, Ū̀, Ū̂, Ū̃, U̇̄, Ǖ, Ṻ, Ṳ̄, U̱ | U |

-| ÿ, ý, ȳ, ȳ́, ȳ̀, ȳ̃, y̱ | y | Ÿ, Ý, Ȳ, Ȳ́, Ȳ̀, Ȳ̃, Y̱ | Y |

-| ź, ž, ż, z̄, ẕ | z | Ź, Ž, Ż, Z̄, Ẕ | Z |

-#### Remove diacritics from a string

-Example: Replace characters containing accent marks with equivalent characters that don't contain accent marks.

-**Expression:**

-NormalizeDiacritics([givenName])

-**Sample input/output:**

-* **INPUT** (givenName): "Zoë"

-* **OUTPUT**: "Zoe"

-### Not

-**Function:**

-Not(source)

-**Description:**

-Flips the boolean value of the **source**. If **source** value is True, returns False. Otherwise, returns True.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source** |Required |Boolean String |Expected **source** values are "True" or "False". |

-### Now

-**Function:**

-Now()

-**Description:**

-The Now function returns a string representing the current UTC DateTime in the format **M/d/yyyy h:mm:ss tt**.

-**Example:**

-`Now()` <br>

-Example value returned *7/2/2021 3:33:38 PM*

-### NumFromDate

-**Function:**

-NumFromDate(value)

-**Description:**

-The NumFromDate function converts a DateTime value to Active Directory format that is required to set attributes like [accountExpires](/windows/win32/adschema/a-accountexpires). Use this function to convert DateTime values received from cloud HR apps like Workday and SuccessFactors to their equivalent AD representation.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **value** |Required | String | Date time string in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. If the date variable is in a different format, use [FormatDateTime](#formatdatetime) function to convert the date to ISO 8601 format. |

-**Example:**

-* Workday example

- Assuming you want to map the attribute *ContractEndDate* from Workday, which is in the format *2020-12-31-08:00* to *accountExpires* field in AD, here is how you can use this function and change the timezone offset to match your locale.

- `NumFromDate(Join("", FormatDateTime([ContractEndDate], ,"yyyy-MM-ddzzz", "yyyy-MM-dd"), " 23:59:59-08:00"))`

-* SuccessFactors example

- Assuming you want to map the attribute *endDate* from SuccessFactors, which is in the format *M/d/yyyy hh:mm:ss tt* to *accountExpires* field in AD, here is how you can use this function and change the time zone offset to match your locale.

- `NumFromDate(Join("",FormatDateTime([endDate], ,"M/d/yyyy hh:mm:ss tt","yyyy-MM-dd")," 23:59:59-08:00"))`

-### PCase

-**Function:**

-PCase(source, wordSeparators)

-**Description:**

-The PCase function converts the first character of each word in a string to upper case, and all other characters are converted to lower case.

-**Parameters:**

-| Name | Required/Optional | Type | Notes |

-| | | | |

-| **source** |Required |String |**source** value to convert to proper case. |

-| **wordSeparators** |Optional |String |Specify a set of characters that will be used as word separators (example: " ,-'") |

-**Remarks:**

-* If the *wordSeparators* parameter isn't specified, then PCase internally invokes the .NET function [ToTitleCase](/dotnet/api/system.globalization.textinfo.totitlecase) to convert the *source* string to proper case. The .NET function *ToTitleCase* supports a comprehensive set of the [Unicode character categories](https://www.unicode.org/reports/tr44/#General_Category_Values) as word separators.

- * Space character

- * New line character

- * *Control* characters like CRLF

- * *Format* control characters

- * *ConnectorPunctuation* characters like underscore

- * *DashPunctuation* characters like dash and hyphen (including characters such En Dash, Em Dash, double hyphen, etc.)

- * *OpenPunctuation* and *ClosePunctuation* characters that occur in pairs like parenthesis, curly bracket, angle bracket, etc.

- * *InitialQuotePunctuation* and *FinalQuotePunctuation* characters like single quotes, double quotes and angular quotes.

- * *OtherPunctuation* characters like exclamation mark, number sign, percent sign, ampersand, asterisk, comma, full stop, colon, semi-colon, etc.

- * *MathSymbol* characters like plus sign, less-than and greater-than sign, vertical line, tilde, equals sign, etc.

- * *CurrencySymbol* characters like dollar sign, cent sign, pound sign, euro sign, etc.

- * *ModifierSymbol* characters like macron, accents, arrow heads, etc.

- * *OtherSymbol* characters like copyright sign, degree sign, registered sign, etc.

-* If the *wordSeparators* parameter is specified, then PCase only uses the characters specified as word separators.

-**Example:**

-Let's say you're sourcing the attributes *firstName* and *lastName* from SAP SuccessFactors and in HR both these attributes are in upper-case. Using the PCase function, you can convert the name to proper case as shown below.

-| Expression | Input | Output | Notes |

-| | | | |

-| `PCase([firstName])` | *firstName* = "PABLO GONSALVES (SECOND)" | "Pablo Gonsalves (Second)" | As the *wordSeparators* parameter isn't specified, the *PCase* function uses the default word separators character set. |

-| `PCase([lastName]," '-")` | *lastName* = "PINTO-DE'SILVA" | "Pinto-De'Silva" | The *PCase* function uses characters in the *wordSeparators* parameter to identify words and transform them to proper case. |

-| `PCase(Join(" ",[firstName],[lastName]))` | *firstName* = GREGORY, *lastName* = "JAMES" | "Gregory James" | You can nest the Join function within PCase. As the *wordSeparators* parameter isn't specified, the *PCase* function uses the default word separators character set. |

-### RandomString

-**Function:**

-RandomString(Length, MinimumNumbers, MinimumSpecialCharacters, MinimumCapital, MinimumLowerCase, CharactersToAvoid)

-**Description:**

-The RandomString function generates a random string based on the conditions specified. Characters allowed can be identified [here](/windows/security/threat-protection/security-policy-settings/password-must-meet-complexity-requirements#reference).

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **Length** |Required |Number |Total length of the random string. This should be greater than or equal to the sum of MinimumNumbers, MinimumSpecialCharacters, and MinimumCapital. 256 characters max.|

-| **MinimumNumbers** |Required |Number |Minimum numbers in the random string.|

-| **MinimumSpecialCharacters** |Required |Number |Minimum number of special characters.|

-| **MinimumCapital** |Required |Number |Minimum number of capital letters in the random string.|

-| **MinimumLowerCase** |Required |Number |Minimum number of lower case letters in the random string.|

-| **CharactersToAvoid** |Optional |String |Characters to be excluded when generating the random string.|

-**Example 1:** - Generate a random string without special character restrictions:

-`RandomString(6,3,0,0,3)`

-Generates a random string with 6 characters. The string contains 3 numbers and 3 lower case characters (1a73qt).

-**Example 2:** - Generate a random string with special character restrictions:

-`RandomString(10,2,2,2,1,"?,")`

-Generates a random string with 10 characters. The string contains at least 2 numbers, 2 special characters, 2 capital letters, 1 lower case letter and excludes the characters "?" and "," (1@!2BaRg53).

-### Redact

-**Function:**

-Redact()

-**Description:**

-The Redact function replaces the attribute value with the string literal "[Redact]" in the provisioning logs.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **attribute/value** |Required |String|Specify the attribute or constant / string to redact from the logs.|

-**Example 1:** Redact an attribute:

-`Redact([userPrincipalName])`

-Removes the userPrincipalName from the provisioning logs.

-**Example 2:** Redact a string:

-`Redact("StringToBeRedacted")`

-Removes a constant string from the provisioning logs.

-**Example 3:** Redact a random string:

-`Redact(RandomString(6,3,0,0,3))`

-Removes the random string from the provisioning logs.

-### RemoveDuplicates

-**Function:**

-RemoveDuplicates(attribute)

-**Description:**

-The RemoveDuplicates function takes a multi-valued string and make sure each value is unique.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **attribute** |Required |Multi-valued Attribute |Multi-valued attribute that will have duplicates removed|

-**Example:**

-`RemoveDuplicates([proxyAddresses])`

-Returns a sanitized proxyAddress attribute where all duplicate values have been removed.

-### Replace

-**Function:**

-Replace(source, oldValue, regexPattern, regexGroupName, replacementValue, replacementAttributeName, template)

-**Description:**

-Replaces values within a string in a case-sensitive manner. The function behaves differently depending on the parameters provided:

-* When **oldValue** and **replacementValue** are provided:

-

- * Replaces all occurrences of **oldValue** in the **source** with **replacementValue**

-* When **oldValue** and **template** are provided:

-

- * Replaces all occurrences of the **oldValue** in the **template** with the **source** value

-* When **regexPattern** and **replacementValue** are provided:

- * The function applies the **regexPattern** to the **source** string and you can use the regex group names to construct the string for **replacementValue**

-> [!NOTE]

-> To learn more about regex grouping constructs and named sub-expressions, see [Grouping Constructs in Regular Expressions](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions).

-* When **regexPattern**, **regexGroupName**, **replacementValue** are provided:

-

- * The function applies the **regexPattern** to the **source** string and replaces all values matching **regexGroupName** with **replacementValue**

-* When **regexPattern**, **regexGroupName**, **replacementAttributeName** are provided:

-

- * If **source** has a value, **source** is returned

- * If **source** has no value, the function applies the **regexPattern** to the **replacementAttributeName** and returns the value matching **regexGroupName**

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source** |Required |String |Usually name of the attribute from the **source** object. |

-| **oldValue** |Optional |String |Value to be replaced in **source** or **template**. |

-| **regexPattern** |Optional |String |Regex pattern for the value to be replaced in **source**. When **replacementAttributeName** is used, the **regexPattern** is applied to extract a value from **replacementAttributeName**. |

-| **regexGroupName** |Optional |String |Name of the group inside **regexPattern**. When named **replacementAttributeName** is used, we will extract the value of the named regex group from the **replacementAttributeName** and return it as the replacement value. |

-| **replacementValue** |Optional |String |New value to replace old one with. |

-| **replacementAttributeName** |Optional |String |Name of the attribute to be used for replacement value |

-| **template** |Optional |String |When **template** value is provided, we will look for **oldValue** inside the template and replace it with **source** value. |

-#### Replace characters using a regular expression

-**Example 1:** Using **oldValue** and **replacementValue** to replace the entire source string with another string.

-Let's say your HR system has an attribute `BusinessTitle`. As part of recent job title changes, your company wants to update anyone with the business title "Product Developer" to "Software Engineer".

-Then in this case, you can use the following expression in your attribute mapping.

-`Replace([BusinessTitle],"Product Developer", , , "Software Engineer", , )`

-* **source**: `[BusinessTitle]`

-* **oldValue**: "Product Developer"

-* **replacementValue**: "Software Engineer"

-* **Expression output**: Software Engineer

-**Example 2:** Using **oldValue** and **template** to insert the source string into another *templatized* string.

-The parameter **oldValue** is a misnomer in this scenario. It is actually the value that will get replaced.

-Let's say you want to always generate login ID in the format `<username>@contoso.com`. There is a source attribute called **UserID** and you want that value to be used for the `<username>` portion of the login ID.

-Then in this case, you can use the following expression in your attribute mapping.

-`Replace([UserID],"<username>", , , , , "<username>@contoso.com")`

-* **source:** `[UserID]` = "jsmith"

-* **oldValue:** "`<username>`"

-* **template:** "`<username>@contoso.com`"

-* **Expression output:** "jsmith@contoso.com"

-**Example 3:** Using **regexPattern** and **replacementValue** to extract a portion of the source string and replace it with an empty string or a custom value built using regex patterns or regex group names.

-

-Let's say you have a source attribute `telephoneNumber` that has components `country code` and `phone number` separated by a space character. For example, `+91 9998887777`

-Then in this case, you can use the following expression in your attribute mapping to extract the 10 digit phone number.

-`Replace([telephoneNumber], , "\\+(?<isdCode>\\d* )(?<phoneNumber>\\d{10})", , "${phoneNumber}", , )`

-* **source:** `[telephoneNumber]` = "+91 9998887777"

-* **regexPattern:** "`\\+(?<isdCode>\\d* )(?<phoneNumber>\\d{10})`"

-* **replacementValue:** "`${phoneNumber}`"

-* **Expression output:** 9998887777

-You can also use this pattern to remove characters and collapse a string.

-For example, the expression below removes parenthesis, dashes and space characters in the mobile number string and returns only digits.

-`Replace([mobile], , "[()\\s-]+", , "", , )`

-* **source:** `[mobile] = "+1 (999) 888-7777"`

-* **regexPattern:** "`[()\\s-]+`"

-* **replacementValue:** "" (empty string)

-* **Expression output:** 19998887777

-**Example 4:** Using **regexPattern**, **regexGroupName** and **replacementValue** to extract a portion of the source string and replace it with another literal value or empty string.

-Let's say your source system has an attribute AddressLineData with two components street number and street name. As part of a recent move, let's say the street number of the address changed, and you want to update only the street number portion of the address line.

-Then in this case, you can use the following expression in your attribute mapping to extract the street number.

-`Replace([AddressLineData], ,"(?<streetNumber>^\\d*)","streetNumber", "888", , )`

-* **source:** `[AddressLineData]` = "545 Tremont Street"

-* **regexPattern:** "`(?<streetNumber>^\\d*)`"

-* **regexGroupName:** "streetNumber"

-* **replacementValue:** "888"

-* **Expression output:** 888 Tremont Street

-Here is another example where the domain suffix from a UPN is replaced with an empty string to generate login ID without domain suffix.

-`Replace([userPrincipalName], , "(?<Suffix>@(.)*)", "Suffix", "", , )`

-* **source:** `[userPrincipalName]` = "jsmith@contoso.com"

-* **regexPattern:** "`(?<Suffix>@(.)*)`"

-* **regexGroupName:** "Suffix"

-* **replacementValue:** "" (empty string)

-* **Expression output:** jsmith

-**Example 5:** Using **regexPattern**, **regexGroupName** and **replacementAttributeName** to handle scenarios when the source attribute is empty or doesn't have a value.

-Let's say your source system has an attribute telephoneNumber. If telephoneNumber is empty, you want to extract the 10 digits of the mobile number attribute.

-Then in this case, you can use the following expression in your attribute mapping.

-`Replace([telephoneNumber], , "\\+(?<isdCode>\\d* )(?<phoneNumber>\\d{10})", "phoneNumber" , , [mobile], )`

-* **source:** `[telephoneNumber]` = "" (empty string)

-* **regexPattern:** "`\\+(?<isdCode>\\d* )(?<phoneNumber>\\d{10})`"

-* **regexGroupName:** "phoneNumber"

-* **replacementAttributeName:** `[mobile]` = "+91 8887779999"

-* **Expression output:** 8887779999

-**Example 6:** You need to find characters that match a regular expression value and remove them.

-`Replace([mailNickname], , "[a-zA-Z_]*", , "", , )`

-* **source** \[mailNickname\]

-* **oldValue**: "john_doe72"

-* **replaceValue**: ""

-* **Expression output**: 72

-### SelectUniqueValue

-**Function:**

-SelectUniqueValue(uniqueValueRule1, uniqueValueRule2, uniqueValueRule3, …)

-**Description:**

-Requires a minimum of two arguments, which are unique value generation rules defined using expressions. The function evaluates each rule and then checks the value generated for uniqueness in the target app/directory. The first unique value found will be the one returned. If all of the values already exist in the target, the entry will get escrowed, and the reason gets logged in the audit logs. There is no upper bound to the number of arguments that can be provided.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **uniqueValueRule1 … uniqueValueRuleN** |At least 2 are required, no upper bound |String | List of unique value generation rules to evaluate. |

-#### Generate unique value for userPrincipalName (UPN) attribute

-Example: Based on the user's first name, middle name and last name, you need to generate a value for the UPN attribute and check for its uniqueness in the target AD directory before assigning the value to the UPN attribute.

-**Expression:**

-```ad-attr-mapping-expr

- SelectUniqueValue(

- Join("@", NormalizeDiacritics(StripSpaces(Join(".", [PreferredFirstName], [PreferredLastName]))), "contoso.com"),

- Join("@", NormalizeDiacritics(StripSpaces(Join(".", Mid([PreferredFirstName], 1, 1), [PreferredLastName]))), "contoso.com"),

- Join("@", NormalizeDiacritics(StripSpaces(Join(".", Mid([PreferredFirstName], 1, 2), [PreferredLastName]))), "contoso.com")

- )

-```

-**Sample input/output:**

-* **INPUT** (PreferredFirstName): "John"

-* **INPUT** (PreferredLastName): "Smith"

-* **OUTPUT**: "John.Smith@contoso.com" if UPN value of John.Smith@contoso.com doesn't already exist in the directory

-* **OUTPUT**: "J.Smith@contoso.com" if UPN value of John.Smith@contoso.com already exists in the directory

-* **OUTPUT**: "Jo.Smith@contoso.com" if the above two UPN values already exist in the directory

-### SingleAppRoleAssignment

-**Function:**

-SingleAppRoleAssignment([appRoleAssignments])

-**Description:**

-Returns a single appRoleAssignment from the list of all appRoleAssignments assigned to a user for a given application. This function is required to convert the appRoleAssignments object into a single role name string. The best practice is to ensure only one appRoleAssignment is assigned to one user at a time. This function isn't supported in scenarios where users have multiple app role assignments.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **[appRoleAssignments]** |Required |String |**[appRoleAssignments]** object. |

-### Split

-**Function:**

-Split(source, delimiter)

-**Description:**

-Splits a string into a multi-valued array, using the specified delimiter character.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source** |Required |String |**source** value to update. |

-| **delimiter** |Required |String |Specifies the character that will be used to split the string (example: ",") |

-#### Split a string into a multi-valued array

-Example: You need to take a comma-delimited list of strings, and split them into an array that can be plugged into a multi-value attribute like Salesforce's PermissionSets attribute. In this example, a list of permission sets has been populated in extensionAttribute5 in Microsoft Entra ID.

-**Expression:**

-Split([extensionAttribute5], ",")

-**Sample input/output:**

-* **INPUT** (extensionAttribute5): "PermissionSetOne, PermissionSetTwo"

-* **OUTPUT**: ["PermissionSetOne", "PermissionSetTwo"]

-### StripSpaces

-**Function:**

-StripSpaces(source)

-**Description:**

-Removes all space (" ") characters from the source string.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source** |Required |String |**source** value to update. |

-### Switch

-**Function:**

-Switch(source, defaultValue, key1, value1, key2, value2, …)

-**Description:**

-When **source** value matches a **key**, returns **value** for that **key**. If **source** value doesn't match any keys, returns **defaultValue**. **Key** and **value** parameters must always come in pairs. The function always expects an even number of parameters. The function shouldn't be used for referential attributes such as manager.

-> [!NOTE]

-> Switch function performs a case-sensitive string comparison of the **source** and **key** values. If you'd like to perform a case-insensitive comparison, normalize the **source** string before comparison using a nested ToLower function and ensure that all **key** strings use lowercase.

-> Example: `Switch(ToLower([statusFlag]), "0", "true", "1", "false", "0")`. In this example, the **source** attribute `statusFlag` may have values ("True" / "true" / "TRUE"). However, the Switch function will always convert it to lowercase string "true" before comparison with **key** parameters.

-> [!CAUTION]

-> For the **source** parameter, do not use the nested functions IsPresent, IsNull or IsNullOrEmpty. Instead use a literal empty string as one of the key values.

-> Example: `Switch([statusFlag], "Default Value", "true", "1", "", "0")`. In this example, if the **source** attribute `statusFlag` is empty, the Switch function will return the value 0.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source** |Required |String |**Source** value to update. |

-| **defaultValue** |Optional |String |Default value to be used when source doesn't match any keys. Can be empty string (""). |

-| **key** |Required |String |**Key** to compare **source** value with. |

-| **value** |Required |String |Replacement value for the **source** matching the key. |

-#### Replace a value based on predefined set of options

-Example: Define the time zone of the user based on the state code stored in Microsoft Entra ID.

-If the state code doesn't match any of the predefined options, use default value of "Australia/Sydney".

-**Expression:**

-`Switch([state], "Australia/Sydney", "NSW", "Australia/Sydney","QLD", "Australia/Brisbane", "SA", "Australia/Adelaide")`

-**Sample input/output:**

-* **INPUT** (state): "QLD"

-* **OUTPUT**: "Australia/Brisbane"

-### ToLower

-**Function:**

-ToLower(source, culture)

-**Description:**

-Takes a *source* string value and converts it to lower case using the culture rules that are specified. If there is no *culture* info specified, then it will use Invariant culture.

-If you would like to set existing values in the target system to lower case, [update the schema for your target application](./customize-application-attributes.md#editing-the-list-of-supported-attributes) and set the property caseExact to 'true' for the attribute that you're interested in.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source** |Required |String |Usually name of the attribute from the source object |

-| **culture** |Optional |String |The format for the culture name based on RFC 4646 is *languagecode2-country/regioncode2*, where *languagecode2* is the two-letter language code and *country/regioncode2* is the two-letter subculture code. Examples include ja-JP for Japanese (Japan) and en-US for English (United States). In cases where a two-letter language code isn't available, a three-letter code derived from ISO 639-2 is used.|

-#### Convert generated userPrincipalName (UPN) value to lower case

-Example: You would like to generate the UPN value by concatenating the PreferredFirstName and PreferredLastName source fields and converting all characters to lower case.

-`ToLower(Join("@", NormalizeDiacritics(StripSpaces(Join(".", [PreferredFirstName], [PreferredLastName]))), "contoso.com"))`

-**Sample input/output:**

-* **INPUT** (PreferredFirstName): "John"

-* **INPUT** (PreferredLastName): "Smith"

-* **OUTPUT**: "john.smith@contoso.com"

-### ToUpper

-**Function:**

-ToUpper(source, culture)

-**Description:**

-Takes a *source* string value and converts it to upper case using the culture rules that are specified. If there is no *culture* info specified, then it will use Invariant culture.

-If you would like to set existing values in the target system to upper case, [update the schema for your target application](./customize-application-attributes.md#editing-the-list-of-supported-attributes) and set the property caseExact to 'true' for the attribute that you're interested in.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **source** |Required |String |Usually name of the attribute from the source object. |

-| **culture** |Optional |String |The format for the culture name based on RFC 4646 is *languagecode2-country/regioncode2*, where *languagecode2* is the two-letter language code and *country/regioncode2* is the two-letter subculture code. Examples include ja-JP for Japanese (Japan) and en-US for English (United States). In cases where a two-letter language code isn't available, a three-letter code derived from ISO 639-2 is used.|

-### Word

-**Function:**

-Word(String,WordNumber,Delimiters)

-**Description:**

-The Word function returns a word contained within a string, based on parameters describing the delimiters to use and the word number to return. Each string of characters in string separated by the one of the characters in delimiters are identified as words:

-If number < 1, returns empty string.

-If string is null, returns empty string.

-If string contains less than number words, or string doesn't contain any words identified by delimiters, an empty string is returned.

-**Parameters:**

-| Name | Required/ Repeating | Type | Notes |

-| | | | |

-| **String** |Required |Multi-valued Attribute |String to return a word from.|

-| **WordNumber** |Required | Integer | Number identifying which word number should return|

-| **delimiters** |Required |String| A string representing the delimiter(s) that should be used to identify words|

-**Example:**

-`Word("The quick brown fox",3," ")`

-Returns "brown".

-`Word("This,string!has&many separators",3,",!&#")`

-Returns "has".

-## Examples

-This section provides more expression function usage examples.

-### Strip known domain name

-Strip a known domain name from a user's email to obtain a user name.

-For example, if the domain is "contoso.com", then you could use the following expression:

-**Expression:**

-`Replace([mail], "@contoso.com", , ,"", ,)`

-**Sample input / output:**

-* **INPUT** (mail): "john.doe@contoso.com"

-* **OUTPUT**: "john.doe"

-### Generate user alias by concatenating parts of first and last name

-Generate a user alias by taking first three letters of user's first name and first five letters of user's last name.

-**Expression:**

-`Append(Mid([givenName], 1, 3), Mid([surname], 1, 5))`

-**Sample input/output:**

-* **INPUT** (givenName): "John"

-* **INPUT** (surname): "Doe"

-* **OUTPUT**: "JohDoe"

-### Add a comma between last name and first name.

-Add a comma between last name and first name.

-**Expression:**

-`Join(", ", "", [surname], [givenName])`

-**Sample input/output:**

-* **INPUT** (givenName): "John"

-* **INPUT** (surname): "Doe"

-* **OUTPUT**: "Doe, John"

-## Related Articles

-* [Automate User Provisioning/Deprovisioning to SaaS Apps](../app-provisioning/user-provisioning.md)

-* [Customizing Attribute Mappings for User Provisioning](../app-provisioning/customize-application-attributes.md)

-* [Scoping Filters for User Provisioning](define-conditional-rules-for-provisioning-user-accounts.md)

-* [Using SCIM to enable automatic provisioning of users and groups from Microsoft Entra ID to applications](../app-provisioning/use-scim-to-provision-users-and-groups.md)

-* [Account Provisioning Notifications](../app-provisioning/user-provisioning.md)

-* [List of Tutorials on How to Integrate SaaS Apps](../saas-apps/tutorial-list.md)

-description: Understand how Application Provisioning works in Microsoft Entra ID.

-# How Application Provisioning works in Microsoft Entra ID

-Automatic provisioning refers to creating user identities and roles in the cloud applications that users need to access. In addition to creating user identities, automatic provisioning includes the maintenance and removal of user identities as status or roles change. Before you start a deployment, you can review this article to learn how Microsoft Entra provisioning works and get configuration recommendations.

-The **Microsoft Entra provisioning service** provisions users to SaaS apps and other systems by connecting to a System for Cross-Domain Identity Management (SCIM) 2.0 user management API endpoint provided by the application vendor. This SCIM endpoint allows Microsoft Entra ID to programmatically create, update, and remove users. For selected applications, the provisioning service can also create, update, and remove extra identity-related objects, such as groups and roles. The channel used for provisioning between Microsoft Entra ID and the application is encrypted using HTTPS TLS 1.2 encryption.

-

-*Figure 1: The Microsoft Entra provisioning service*

-

-*Figure 2: "Outbound" user provisioning workflow from Microsoft Entra ID to popular SaaS applications*

-

-*Figure 3: "Inbound" user provisioning workflow from popular Human Capital Management (HCM) applications to Microsoft Entra ID and Windows Server Active Directory*

-## Provisioning using SCIM 2.0

-The Microsoft Entra provisioning service uses the [SCIM 2.0 protocol](https://techcommunity.microsoft.com/t5/Identity-Standards-Blog/bg-p/IdentityStandards) for automatic provisioning. The service connects to the SCIM endpoint for the application, and uses SCIM user object schema and REST APIs to automate the provisioning and deprovisioning of users and groups. A SCIM-based provisioning connector is provided for most applications in the Microsoft Entra gallery. Developers use the SCIM 2.0 user management API in Microsoft Entra ID to build endpoints for their apps that integrate with the provisioning service. For details, see [Build a SCIM endpoint and configure user provisioning](../app-provisioning/use-scim-to-provision-users-and-groups.md).

-To request an automatic Microsoft Entra provisioning connector for an app that doesn't currently have one, see [Microsoft Entra Application Request](../manage-apps/v2-howto-app-gallery-listing.md).

-## Authorization

-Credentials are required for Microsoft Entra ID to connect to the application's user management API. While you're configuring automatic user provisioning for an application, you need to enter valid credentials. For gallery applications, you can find credential types and requirements for the application by referring to the app tutorial. For non-gallery applications, you can refer to the [SCIM](./use-scim-to-provision-users-and-groups.md#authorization-to-provisioning-connectors-in-the-application-gallery) documentation to understand the credential types and requirements. In the Microsoft Entra admin center, you're able to test the credentials by having Microsoft Entra ID attempt to connect to the app's provisioning app using the supplied credentials.

-## Mapping attributes

-When you enable user provisioning for a third-party SaaS application, the Microsoft Entra admin center controls its attribute values through attribute mappings. Mappings determine the user attributes that flow between Microsoft Entra ID and the target application when user accounts are provisioned or updated.

-There's a preconfigured set of attributes and attribute mappings between Microsoft Entra user objects and each SaaS appΓÇÖs user objects. Some apps manage other types of objects along with Users, such as Groups.

-When setting up provisioning, it's important to review and configure the attribute mappings and workflows that define which user (or group) properties flow from Microsoft Entra ID to the application. Review and configure the matching property (**Match objects using this attribute**) that is used to uniquely identify and match users/groups between the two systems.

-You can customize the default attribute-mappings according to your business needs. So, you can change or delete existing attribute-mappings, or create new attribute-mappings. For details, see [Customizing user provisioning attribute-mappings for SaaS applications](./customize-application-attributes.md).

-When you configure provisioning to a SaaS application, one of the types of attribute mappings that you can specify is an expression mapping. For these mappings, you must write a script-like expression that allows you to transform your usersΓÇÖ data into formats that are more acceptable for the SaaS application. For details, see [Writing expressions for attribute mappings](functions-for-customizing-application-data.md).

-## Scoping

-### Assignment-based scoping

-For outbound provisioning from Microsoft Entra ID to a SaaS application, relying on [user or group assignments](../manage-apps/assign-user-or-group-access-portal.md) is the most common way to determine which users are in scope for provisioning. Because user assignments are also used for enabling single sign-on, the same method can be used for managing both access and provisioning. Assignment-based scoping doesn't apply to inbound provisioning scenarios such as Workday and Successfactors.

-* **Groups.** With a Microsoft Entra ID P1 or P2 license plan, you can use groups to assign access to a SaaS application. Then, when the provisioning scope is set to **Sync only assigned users and groups**, the Microsoft Entra provisioning service provisions or deprovisions users based on whether they're members of a group that's assigned to the application. The group object itself isn't provisioned unless the application supports group objects. Ensure that groups assigned to your application have the property "SecurityEnabled" set to "True".

-* **Dynamic groups.** The Microsoft Entra user provisioning service can read and provision users in [dynamic groups](../enterprise-users/groups-create-rule.md). Keep these caveats and recommendations in mind:

- * Dynamic groups can impact the performance of end-to-end provisioning from Microsoft Entra ID to SaaS applications.

- * How fast a user in a dynamic group is provisioned or deprovisioned in a SaaS application depends on how fast the dynamic group can evaluate membership changes. For information about how to check the processing status of a dynamic group, see [Check processing status for a membership rule](../enterprise-users/groups-create-rule.md).

- * When a user loses membership in the dynamic group, it's considered a deprovisioning event. Consider this scenario when creating rules for dynamic groups.

-* **Nested groups.** The Microsoft Entra user provisioning service can't read or provision users in nested groups. The service can only read and provision users that are immediate members of an explicitly assigned group. This limitation of "group-based assignments to applications" also affects single sign-on (see [Using a group to manage access to SaaS applications](../enterprise-users/groups-saasapps.md)). Instead, directly assign or otherwise [scope in](define-conditional-rules-for-provisioning-user-accounts.md) the groups that contain the users who need to be provisioned.

-### Attribute-based scoping

-You can use scoping filters to define attribute-based rules that determine which users are provisioned to an application. This method is commonly used for inbound provisioning from HCM applications to Microsoft Entra ID and Active Directory. Scoping filters are configured as part of the attribute mappings for each Microsoft Entra user provisioning connector. For details about configuring attribute-based scoping filters, see [Attribute-based application provisioning with scoping filters](define-conditional-rules-for-provisioning-user-accounts.md).

-### B2B (guest) users

-It's possible to use the Microsoft Entra user provisioning service to provision B2B (guest) users in Microsoft Entra ID to SaaS applications. However, for B2B users to sign in to the SaaS application using Microsoft Entra ID, you must manually configure the SaaS application to use Microsoft Entra ID as a Security Assertion Markup Language (SAML) identity provider.

-Follow these general guidelines when configuring SaaS apps for B2B (guest) users:

-> [!NOTE]

-> The userPrincipalName for a B2B user represents the external user's email address alias@theirdomain as "alias_theirdomain#EXT#@yourdomain". When the userPrincipalName attribute is included in your attribute mappings as a source attribute, and a B2B user is being provisioned, the #EXT# and your domain is stripped from the userPrincipalName, so only their original alias@theirdomain is used for matching or provisioning. If you require the full user principal name including #EXT# and your domain to be present, replace userPrincipalName with originalUserPrincipalName as the source attribute. <br />

-userPrincipalName = alias@theirdomain<br />

-originalUserPrincipalName = alias_theirdomain#EXT#@yourdomain

-## Provisioning cycles: Initial and incremental

-When Microsoft Entra ID is the source system, the provisioning service uses the [delta query to track changes in Microsoft Graph data](/graph/delta-query-overview) to monitor users and groups. The provisioning service runs an initial cycle against the source system and target system, followed by periodic incremental cycles.

-### Initial cycle

-When the provisioning service is started, the first cycle will:

-1. Query all users and groups from the source system, retrieving all attributes defined in the [attribute mappings](customize-application-attributes.md).

-2. Filter the users and groups returned, using any configured [assignments](../manage-apps/assign-user-or-group-access-portal.md) or [attribute-based scoping filters](define-conditional-rules-for-provisioning-user-accounts.md).

-3. When a user is assigned or in scope for provisioning, the service queries the target system for a matching user using the specified [matching attributes](customize-application-attributes.md#understanding-attribute-mapping-properties). Example: If the userPrincipal name in the source system is the matching attribute and maps to userName in the target system, then the provisioning service queries the target system for userNames that match the userPrincipal name values in the source system.

-4. If a matching user isn't found in the target system, it's created using the attributes returned from the source system. After the user account is created, the provisioning service detects and caches the target system's ID for the new user. This ID is used to run all future operations on that user.

-5. If a matching user is found, it's updated using the attributes provided by the source system. After the user account is matched, the provisioning service detects and caches the target system's ID for the new user. This ID is used to run all future operations on that user.

-6. If the attribute mappings contain "reference" attributes, the service does more updates on the target system to create and link the referenced objects. For example, a user may have a "Manager" attribute in the target system, which is linked to another user created in the target system.

-7. Persist a watermark at the end of the initial cycle, which provides the starting point for the later incremental cycles.

-Some applications such as ServiceNow, G Suite, and Box support not only provisioning users, but also provisioning groups and their members. In those cases, if group provisioning is enabled in the [mappings](customize-application-attributes.md), the provisioning service synchronizes the users and the groups, and then later synchronizes the group memberships.

-### Incremental cycles

-After the initial cycle, all other cycles will:

-1. Query the source system for any users and groups that were updated since the last watermark was stored.

-2. Filter the users and groups returned, using any configured [assignments](../manage-apps/assign-user-or-group-access-portal.md) or [attribute-based scoping filters](define-conditional-rules-for-provisioning-user-accounts.md).

-3. When a user is assigned or in scope for provisioning, the service queries the target system for a matching user using the specified [matching attributes](customize-application-attributes.md#understanding-attribute-mapping-properties).

-4. If a matching user isn't found in the target system, it's created using the attributes returned from the source system. After the user account is created, the provisioning service detects and caches the target system's ID for the new user. This ID is used to run all future operations on that user.

-5. If a matching user is found, it's updated using the attributes provided by the source system. If it's a newly assigned account that is matched, the provisioning service detects and caches the target system's ID for the new user. This ID is used to run all future operations on that user.

-6. If the attribute mappings contain "reference" attributes, the service does more updates on the target system to create and link the referenced objects. For example, a user may have a "Manager" attribute in the target system, which is linked to another user created in the target system.

-7. If a user that was previously in scope for provisioning is removed from scope, including being unassigned, the service disables the user in the target system via an update.

-8. If a user that was previously in scope for provisioning is disabled or soft-deleted in the source system, the service disables the user in the target system via an update.

-9. If a user that was previously in scope for provisioning is hard-deleted in the source system, the service deletes the user in the target system. In Microsoft Entra ID, users are hard-deleted 30 days after they're soft-deleted.

-10. Persist a new watermark at the end of the incremental cycle, which provides the starting point for the later incremental cycles.

-> [!NOTE]

-> You can optionally disable the **Create**, **Update**, or **Delete** operations by using the **Target object actions** check boxes in the [Mappings](customize-application-attributes.md) section. The logic to disable a user during an update is also controlled via an attribute mapping from a field such as *accountEnabled*.

-The provisioning service continues running back-to-back incremental cycles indefinitely, at intervals defined in the [tutorial specific to each application](../saas-apps/tutorial-list.md). Incremental cycles continue until one of the events occurs:

-<!-- {

- "blockType": "request",

- "name": "synchronizationjob_restart"

-}-->

-```http

-POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/restart

-Authorization: Bearer <token>

-Content-type: application/json

-{

- "criteria": {

- "resetScope": "Full"

- }

-}

-```

-### Errors and retries

-If an error in the target system prevents an individual user from being added, updated, or deleted in the target system, the operation is retried in the next sync cycle. The errors are continually retried, gradually scaling back the frequency of retries. To resolve the failure, administrators must check the [provisioning logs](../reports-monitoring/concept-provisioning-logs.md?context=azure/active-directory/manage-apps/context/manage-apps-context) to determine the root cause and take the appropriate action. Common failures can include:

-Resolve these failures by adjusting the attribute values for the affected user in the source system, or by adjusting the attribute mappings so they don't cause conflicts.

-### Quarantine

-If most or all of the calls that are made against the target system consistently fail because of an error (for example invalid admin credentials) the provisioning job goes into a "quarantine" state. This state is indicated in the [provisioning summary report](./check-status-user-account-provisioning.md) and via email if email notifications were configured in the Microsoft Entra admin center.

-When in quarantine, the frequency of incremental cycles is gradually reduced to once per day.

-The provisioning job exits quarantine after all of the offending errors are fixed and the next sync cycle starts. If the provisioning job stays in quarantine for more than four weeks, the provisioning job is disabled. Learn more here about quarantine status [here](./application-provisioning-quarantine-status.md).

-### How long provisioning takes

-Performance depends on whether your provisioning job is running an initial provisioning cycle or an incremental cycle. For details about how long provisioning takes and how to monitor the status of the provisioning service, see [Check the status of user provisioning](application-provisioning-when-will-provisioning-finish-specific-user.md).

-### How to tell if users are being provisioned properly

-All operations run by the user provisioning service are recorded in the Microsoft Entra [Provisioning logs (preview)](../reports-monitoring/concept-provisioning-logs.md?context=azure/active-directory/manage-apps/context/manage-apps-context). The logs include all read and write operations made to the source and target systems, and the user data that was read or written during each operation. For information on how to read the provisioning logs in the Microsoft Entra admin center, see the [provisioning reporting guide](./check-status-user-account-provisioning.md).

-## Deprovisioning

-The Microsoft Entra provisioning service keeps source and target systems in sync by deprovisioning accounts when user access is removed.

-The provisioning service supports both deleting and disabling (sometimes referred to as soft-deleting) users. The exact definition of disable and delete varies based on the target app's implementation, but generally a disable indicates that the user can't sign in. A delete indicates that the user has been removed completely from the application. For SCIM applications, a disable is a request to set the *active* property to false on a user.

-**Configure your application to disable a user**

-Confirm the checkbox for updates is selected.

-Confirm the mapping for *active* for your application. If you're using an application from the app gallery, the mapping may be slightly different. In this case, use the default mapping for gallery applications.

-**Configure your application to delete a user**

-The scenario triggers a disable or a delete:

-* A user is soft-deleted in Microsoft Entra ID (sent to the recycle bin / AccountEnabled property set to false). Thirty days after a user is deleted in Microsoft Entra ID, they're permanently deleted from the tenant. At this point, the provisioning service sends a DELETE request to permanently delete the user in the application. At any time during the 30-day window, you can [manually delete a user permanently](../fundamentals/users-restore.md), which sends a delete request to the application.

-* A user is permanently deleted / removed from the recycle bin in Microsoft Entra ID.

-* A user is unassigned from an app.

-* A user goes from in scope to out of scope (doesn't pass a scoping filter anymore).

-By default, the Microsoft Entra provisioning service soft-deletes or disables users that go out of scope. If you want to override this default behavior, you can set a flag to [skip out-of-scope deletions.](skip-out-of-scope-deletions.md)

-When one of the four events occurs and the target application doesn't support soft-deletes, the provisioning service sends a DELETE request to permanently delete the user from the app.

-If you see `IsSoftDeleted` in your attribute mappings, it's used to determine the state of the user and whether to send an update request with `active = false` to soft-delete the user.

-**Deprovisioning events**

-The table describes how you can configure deprovisioning actions with the Microsoft Entra provisioning service. These rules are written with the non-gallery / custom application in mind, but generally apply to applications in the gallery. However, the behavior for gallery applications can differ as they've been optimized to meet the needs of the application. For example, if the target application doesn't support soft-deleting then the Microsoft Entra provisioning service might send a hard-delete request to delete users rather than send a soft-delete.

-|Scenario|How to configure in Microsoft Entra ID|

-|--|--|

-|A user is unassigned from an app, soft-deleted in Microsoft Entra ID, or blocked from sign-in. You don't want anything to be done.|Remove `isSoftDeleted` from the attribute mappings and / or set the [skip out of scope deletions](skip-out-of-scope-deletions.md) property to true.|

-|A user is unassigned from an app, soft-deleted in Microsoft Entra ID, or blocked from sign-in. You want to set a specific attribute to `true` or `false`.|Map `isSoftDeleted` to the attribute that you would like to set to false.|

-|A user is disabled in Microsoft Entra ID, unassigned from an app, soft-deleted in Microsoft Entra ID, or blocked from sign-in. You want to send a DELETE request to the target application.|This is currently supported for a limited set of gallery applications where the functionality is required. It's not configurable by customers.|

-|A user is deleted in Microsoft Entra ID. You don't want anything done in the target application.|Ensure that "Delete" isn't selected as one of the target object actions in the [attribute configuration experience](skip-out-of-scope-deletions.md).|

-|A user is deleted in Microsoft Entra ID. You want to set the value of an attribute in the target application.|Not supported.|

-|A user is deleted in Microsoft Entra ID. You want to delete the user in the target application|Ensure that Delete is selected as one of the target object actions in the [attribute configuration experience](skip-out-of-scope-deletions.md).|

-**Known limitations**

-* When a user or group is unassigned from an app and no longer managed with the provisioning service, a disable request is sent. At that point, the service doesn't manage the user and a delete request isn't sent when the user is deleted from the directory.

-* Provisioning a user that is disabled in Microsoft Entra ID isn't supported. They must be active in Microsoft Entra ID before they're provisioned.

-* When a user goes from soft-deleted to active, the Microsoft Entra provisioning service activates the user in the target app, but doesn't automatically restore the group memberships. The target application should maintain the group memberships for the user in inactive state. If the target application doesn't support maintaining the inactive state, you can restart provisioning to update the group memberships.

-**Recommendation**

-When developing an application, always support both soft-deletes and hard-deletes. It allows customers to recover when a user is accidentally disabled.

-## Next Steps

-[Plan an automatic user provisioning deployment](../app-provisioning/plan-auto-user-provisioning.md)

-[Configure provisioning for a gallery app](./configure-automatic-user-provisioning-portal.md)

-[Build a SCIM endpoint and configure provisioning when creating your own app](../app-provisioning/use-scim-to-provision-users-and-groups.md)

-[Troubleshoot problems with configuring and provisioning users to an application](./application-provisioning-config-problem.md).

-description: Learn how to troubleshoot attribute retrieval issues with HR provisioning

-# Troubleshoot HR attribute retrieval issues

-## Issue fetching Workday attributes

-| **Applies to** |

-|--|

-| * Workday to on-premises Active Directory user provisioning <br> * Workday to Microsoft Entra user provisioning |

-| **Issue Description** |

-| You have just configured the Workday inbound provisioning app and successfully connected to the Workday tenant URL. You ran a test sync and you observed that the provisioning app is not retrieving certain attributes from Workday. Only some attributes are read and provisioned to the target. |

-| **Probable Cause** |

-| By default, the Workday provisioning app ships with attribute mapping and XPATH definitions that work with Workday Web Services (WWS) v21.1. When configuring connectivity to Workday in the provisioning app, if you explicitly specified the WWS API version (example: `https://wd3-impl-services1.workday.com/ccx/service/contoso4/Human_Resources/v34.0`), then you may run into this issue, because of the mismatch between WWS API version and the XPATH definitions. |

-| **Resolution Options** |

-| * *Option 1*: Remove the WWS API version information from the URL and use the default WWS API version v21.1 <br> * *Option 2*: Manually update the XPATH API expressions so it is compatible with your preferred WWS API version. Update the **XPATH API expressions** under **Attribute Mapping -> Advanced Options -> Edit attribute list for Workday** referring to the section [Workday attribute reference](../app-provisioning/workday-attribute-reference.md#xpath-values-for-workday-web-services-wws-api-v30) |

-## Issue fetching Workday calculated fields

-| **Applies to** |

-|--|

-| * Workday to on-premises Active Directory user provisioning <br> * Workday to Microsoft Entra user provisioning |

-| **Issue Description** |

-| You have just configured the Workday inbound provisioning app and successfully connected to the Workday tenant URL. You have an integration system configured in Workday and you have configured XPATHs that point to attributes in the Workday Integration System. However, the Microsoft Entra provisioning app isn't fetching values associated with these integration system attributes or calculated fields. |

-| **Cause** |

-| This is a known limitation. The Workday provisioning app currently doesn't support fetching calculated fields/integration system attributes using the *Field_And_Parameter_Criteria_Data* Get_Workers request filter. |

-| **Resolution Options** |

-| You could consider a workaround of either using Workday Provisioning groups or Workday Custom ID field. See details below. |

-**Suggested workarounds**

- * **Option 1: Using Workday Provisioning Groups**: Check if the calculated field value can be represented as a provisioning group in Workday. Using the same logic that is used for the calculated field, your Workday Admin may be able to assign a Provisioning Group to the user. Reference Workday doc that requires Workday login: [Set Up Account Provisioning Groups](https://doc.workday.com/reader/3DMnG~27o049IYFWETFtTQ/keT9jI30zCzj4Nu9pJfGeQ). Once configured, this Provisioning Group assignment can be [retrieved in the provisioning job](../app-provisioning/workday-integration-reference.md#example-3-retrieving-provisioning-group-assignments) and used in attribute mappings and scoping filter.

-* **Option 2: Using Workday Custom IDs**: Check if the calculated field value can be represented as a Custom ID on the Worker Profile. Use `Maintain Custom ID Type` task in Workday to define a new type and populate values in this custom ID. Make sure the [Workday ISU account used for the integration](../saas-apps/workday-inbound-tutorial.md#configuring-domain-security-policy-permissions) has domain security permission for `Person Data: ID Information`.

- * Example 1: Let's say you have a calculated field called Payroll ID. You can define "External_Payroll_ID" as a custom ID in Workday and retrieve it using an XPATH that uses "Custom_ID_Type_ID" as the selecting mechanism: `wd:Worker/wd:Worker_Data/wd:Personal_Data/wd:Identification_Data/wd:Custom_ID/wd:Custom_ID_Data[string(wd:ID_Type_Reference/wd:ID[@wd:type='Custom_ID_Type_ID']='External_Payroll_ID']/wd:ID/text()`

- * Example 2: Let's say you have a calculated field called Badge ID. You can define "Badge ID" as a custom ID in Workday and retrieve the "Descriptor" attribute corresponding to it with an XPATH that uses "wd:ID_Type_Reference/@wd:Descriptor" as the selecting mechanism: `wd:Worker/wd:Worker_Data/wd:Personal_Data/wd:Identification_Data/wd:Custom_ID[string(wd:Custom_ID_Data/wd:ID_Type_Reference/@wd:Descriptor)='BADGE ID']/wd:Custom_ID_Reference/@wd:Descriptor`

-## Next steps

-* [Learn more about Microsoft Entra ID and Workday integration scenarios and web service calls](workday-integration-reference.md)

-* [Learn how to review logs and get reports on provisioning activity](check-status-user-account-provisioning.md)

-description: Learn how to troubleshoot manager update issues with HR provisioning

-# Troubleshoot HR manager update issues

-**Applies to:**

-* Workday to on-premises Active Directory user provisioning

-* Workday to Microsoft Entra user provisioning

-* SAP SuccessFactors to on-premises Active Directory user provisioning

-* SAP SuccessFactors to Microsoft Entra user provisioning

-## Understanding how manager reference resolution works

-The Microsoft Entra provisioning service automatically updates manager information so that the user-manager relationship in Microsoft Entra ID is always in sync with your HR data. It uses a process called *manager reference resolution* to accurately update the *manager* attribute. Before going into the process details, it is important to understand how manager information is stored in Microsoft Entra ID and on-premises Active Directory.

-* In **on-premises Active Directory**, the *manager* attribute stores the *distinguishedName (dn)* of the manager's account in AD.

-* In **Microsoft Entra ID**, the *manager* attribute is a DirectoryObject navigation property in Microsoft Entra ID. When you view the user record in the Microsoft Entra admin center, it shows the *displayName* of the manager record in Microsoft Entra ID.

-The *manager reference resolution* is a two step-process:

-* Step 1: Link the manager's HR source record with the manager's target account record using a pair of attributes referred to as *source anchor* and *target anchor*.

-* Step 2: Use the manager reference attributes defined in the schema to update the manager attribute in the target in the required format.

-The default anchor attributes and reference attributes for each app is listed below.

-| App Name | Anchor attribute | Reference attribute in user profile |

-|--|--|--|

-| Workday | WID | ManagerReference (which points to the WID of the manager record) |

-| SAP SuccessFactors | personIdExternal | manager (which points to the personIdExternal of the manager record) |

-| On-premises Active Directory | objectGUID | manager (which points to DN of the manager record) |

-| Microsoft Entra ID | objectId | manager (which points to the manager's Microsoft Entra ID record) |

-## Prerequisites for successful manager update

-In order for *manager reference resolution* to work successfully, the following pre-requisites should be met:

-* Your provisioning app should be configured to use the default source and target anchors as listed above. Do not change the metadata properties (data type, API expression) associated with these anchor and reference attributes.

-* The API expressions (XPATH for Workday and JSONPath for SuccessFactors) associated with the manager attribute resolve to a valid non-null value.

- * Workday ManagerReference default XPATH API expression: `wd:Worker/wd:Worker_Data/wd:Management_Chain_Data/wd:Worker_Supervisory_Management_Chain_Data[position()=1]/wd:Management_Chain_Data[last()=position()]/wd:Manager_Reference/wd:ID[@wd:type='WID']/text()`

- * SuccessFactors manager default JSONPath API expression: `$.employmentNav.results[0].userNav.manager.empInfo.personIdExternal`

-* The manager record must also be in scope of the provisioning job.

-* The provisioning app should have processed the manager record prior to processing the user record.

-## Provision-on-demand does not update manager attribute

-| Troubleshooting | Details |

-|--|--|

-| **Issue** | You have successfully configured the inbound provisioning app. You are testing sync with provision-on-demand. It does not update the manager attribute and you get an error message *"Invalid value"*. |

-| **Cause** | Your provisioning job is not meeting one of the [prerequisites for successful manager update](#prerequisites-for-successful-manager-update) |

-| **Resolution** | * If you have changed the default manager attribute mapping, restore the default mapping. <br> * Ensure that the manager record is in scope and the manager API expression resolves to a valid value. <br> * Run provision-on-demand for the manager's record first and then run provision-on-demand for the user's record. |

-## Full sync does not update manager attribute

-| Troubleshooting | Details |

-|--|--|

-| **Issue** | You have successfully configured the inbound provisioning app. You are using a scoping filter to process only certain HR records. You observe that the manager resolution is not happening for some users. |

-| **Cause** | If you are using scoping filters, most likely the manager record is not in scope. |

-| **Resolution** | Update the scoping filter to add the manager record in scope |

-## Next steps

-* [Learn more about Microsoft Entra ID and Workday integration scenarios and web service calls](workday-integration-reference.md)

-* [Learn how to review logs and get reports on provisioning activity](check-status-user-account-provisioning.md)

-description: Learn how to troubleshoot user creation issues with HR provisioning

-# Troubleshoot HR user creation issues

-## Creation fails due to null / empty values

-**Applies to:**

-* Workday to on-premises Active Directory user provisioning

-* Workday to Microsoft Entra user provisioning

-* SAP SuccessFactors to on-premises Active Directory user provisioning

-* SAP SuccessFactors to Microsoft Entra user provisioning

-| Troubleshooting | Details |

-|-- | -- |

-| **Issue** | You have successfully configured the inbound provisioning app. You are getting null or empty value from the HR app. The create operation fails with the error message: `InvalidAttributeSyntax-LdapErr: The syntax is invalid. The parameter is incorrect. Error in attribute conversion operation, data 0, v3839` |

-| **Cause** | The provisioning service does not have a default logic for null value processing. When the provisioning service gets an empty string from the source app, it tries to flow the value "as-is" to the target app. In this case, on-premises Active Directory does not support setting empty string values and hence you see the above error. |

-| **Resolution** | Check the provisioning logs. Identify attributes in the target Active Directory that are receiving null or empty string values. Update the attribute mapping for such attributes to use an expression mapping. See recommended resolutions below. |

-**Recommended resolutions**

- Let's say the attribute `BusinessTitle` mapped to AD attribute `jobTitle` may be null or empty in Workday.

- * Option 1: Define an expression to check for empty or null values using functions like [IIF](functions-for-customizing-application-data.md#iif), [IsNullOrEmpty](functions-for-customizing-application-data.md#isnullorempty), [Coalesce](functions-for-customizing-application-data.md#coalesce) or [IsPresent](functions-for-customizing-application-data.md#ispresent) and pass a non-blank literal value.

-

- `IIF(IsNullOrEmpty([BusinessTitle]),"N/A",[BusinessTitle])`

- * Option 2: Use the function [IgnoreFlowIfNullOrEmpty](functions-for-customizing-application-data.md#ignoreflowifnullorempty) to drop empty or null attributes in the payload sent to on-premises Active Directory / Microsoft Entra ID.

-

- `IgnoreFlowIfNullOrEmpty([BusinessTitle])`

-## Next steps

-* [Learn more about Microsoft Entra ID and Workday integration scenarios and web service calls](workday-integration-reference.md)

-* [Learn how to review logs and get reports on provisioning activity](check-status-user-account-provisioning.md)

-description: Learn how to troubleshoot user update issues with HR provisioning

-# Troubleshoot HR user update issues

-## Null and empty values not processed as expected

-**Applies to:**

-* Workday to on-premises Active Directory user provisioning

-* Workday to Microsoft Entra user provisioning

-* SAP SuccessFactors to on-premises Active Directory user provisioning

-* SAP SuccessFactors to Microsoft Entra user provisioning

-| Troubleshooting | Details |

-|-- | -- |

-| **Issue** | You have successfully configured the inbound provisioning app. You are getting null or empty value from the HR app. You expect the provisioning service to clear the corresponding target attribute value in on-premises Active Directory / Microsoft Entra ID. But the operation fails with the error message: `InvalidAttributeSyntax-LdapErr: The syntax is invalid. The parameter is incorrect. Error in attribute conversion operation, data 0, v3839` |

-| **Cause** | The provisioning service does not have a default logic for null value processing. When the provisioning service gets an empty string from the source app, it tries to flow the value "as-is" to the target app. In this case, on-premises Active Directory does not support setting empty string values and hence you see the above error. |

-| **Resolution** | Check the provisioning logs. Identify attributes in the target Active Directory that are receiving null or empty string values. Update the attribute mapping for such attributes to use an expression mapping. See recommended resolutions below. |

-**Recommended resolutions**

- Let's say the attribute `BusinessTitle` mapped to AD attribute `jobTitle` may be null or empty in Workday.

- * Option 1: Define an expression to check for empty or null values using functions like [IIF](functions-for-customizing-application-data.md#iif), [IsNullOrEmpty](functions-for-customizing-application-data.md#isnullorempty), [Coalesce](functions-for-customizing-application-data.md#coalesce) or [IsPresent](functions-for-customizing-application-data.md#ispresent) and pass a non-blank literal value.

-

- `IIF(IsNullOrEmpty([BusinessTitle]),"N/A",[BusinessTitle])`

- * Option 2: Use the function [IgnoreFlowIfNullOrEmpty](functions-for-customizing-application-data.md#ignoreflowifnullorempty) to drop empty or null attributes in the payload sent to on-premises Active Directory / Microsoft Entra ID.

-

- `IgnoreFlowIfNullOrEmpty([BusinessTitle])`

-## Some Workday attribute updates are missing

-**Applies to:**

-* Workday to on-premises Active Directory user provisioning

-* Workday to Microsoft Entra user provisioning

-| Troubleshooting | Details |

-|-- | -- |

-| **Issue** | You have successfully configured the Workday inbound provisioning app and successfully connected to the Workday tenant URL. You are observing that there is a delay in the flow of certain attribute updates from Workday or in some cases, the attributes changes from Workday are not flowing through as expected during incremental sync. |

-| **Cause** | During incremental sync, the provisioning app queries Workday transaction log for changes to the primary Worker entity and only changes tracked by Workday's transaction log are processed. <br> If changes to a Workday attribute in your setup is not tracked by Workday's transaction log, then Microsoft Entra ID will not be able to fetch that change. For example: the *LocalReference* Workday attribute is part of the default attribute mapping and it has XPATH `wd:Worker/wd:Worker_Data/wd:Employment_Data/wd:Position_Data/wd:Business_Site_Summary_Data/wd:Local_Reference/wd:ID[@wd:type='Locale_ID']/text()`. Note that this attribute is part of the entity *Business_Site_Summary_Data*. A change in the value of this attribute in Workday will not show up in the Workday transaction log. Thus during incremental sync, the new value of this attribute will show up only if an attribute associated with the primary Worker entity also changes during the sync interval. |

-| **Resolution** | If you notice this behavior frequently, where changes to certain Workday attributes are not flowing through, we recommend periodically running a weekly or monthly full sync. |

-## User match with extensionAttribute not working

-**Applies to:**

-* Workday to Microsoft Entra user provisioning

-* SAP SuccessFactors to Microsoft Entra user provisioning

-| Troubleshooting | Details |

-|-- | -- |

-| **Issue** | Let's say you are using *extensionAttribute3* in Microsoft Entra ID to store the employee ID and you have mapped it to Workday *WorkerID* or SuccessFactors *personIdExternal* attribute for user matching. With this configuration, the matching step in provisioning process fails. This issue impacts both user creation and updates. |

-| **Cause** | The Microsoft Entra ID *OnPremisesExtensionAttributes* (`extensionAttributes1-15`) cannot be used as a matching attribute because the `$filter` parameter of **Azure AD Graph API** does not [support filtering by extensionAttributes](/previous-versions/azure/ad/graph/howto/azure-ad-graph-api-supported-queries-filters-and-paging-options#filter). |

-| **Resolution** | Don't use Microsoft Entra ID *OnPremisesExtensionAttributes* (`extensionAttributes1-15`) in the matching attribute pair. Use employeeID. |

-## Next steps

-* [Learn more about Microsoft Entra ID and Workday integration scenarios and web service calls](workday-integration-reference.md)

-* [Learn how to review logs and get reports on provisioning activity](check-status-user-account-provisioning.md)

-description: Learn how to troubleshoot write back issues with HR provisioning

-# Troubleshoot HR write back issues

-## Null and empty values not processed as expected

-**Applies to:**

-* Workday Writeback

-* SAP SuccessFactors Writeback

-| Troubleshooting | Details |

-|-- | -- |

-| **Issue** | You have successfully configured the Writeback app. You are getting null or empty value from Microsoft Entra ID. You expect the provisioning service to clear the corresponding email or phone number value in the HR app. But the operation fails. |

-| **Cause** | The provisioning service does not have a default logic for null value processing. When the provisioning service gets an empty string from the source app, it tries to flow the value "as-is" to the target app. If Workday or SuccessFactors cannot process empty values, then an error is returned. |

-| **Resolution** | Update the attribute mapping to use expression mappings as recommended below. |

-**Recommended resolutions**

- Let's say the attribute `telephoneNumber` mapped to SAP SuccessFactors attribute `businessPhoneNumber` may be null or empty in Microsoft Entra ID.

- * Option 1: Define an expression to check for empty or null values using functions like [IIF](functions-for-customizing-application-data.md#iif), [IsNullOrEmpty](functions-for-customizing-application-data.md#isnullorempty), [Coalesce](functions-for-customizing-application-data.md#coalesce) or [IsPresent](functions-for-customizing-application-data.md#ispresent) and pass a non-blank literal value (example: 000-000-0000 in this case).

-

- `IIF(IsNullOrEmpty([telephoneNumber]),"000-000-0000",[telephoneNumber])`

- * Option 2: Use the function [IgnoreFlowIfNullOrEmpty](functions-for-customizing-application-data.md#ignoreflowifnullorempty) to drop empty or null attributes in the payload sent to SuccessFactors.

-

- `IgnoreFlowIfNullOrEmpty([telephoneNumber])`

-## Next steps

-* [Learn more about Microsoft Entra ID and Workday integration scenarios and web service calls](workday-integration-reference.md)

-* [Learn how to review logs and get reports on provisioning activity](check-status-user-account-provisioning.md)

-description: An overview of API-driven inbound provisioning.

-# API-driven inbound provisioning concepts (Public preview)

-This document provides a conceptual overview of the Microsoft Entra API-driven inbound user provisioning.

-> [!IMPORTANT]

-> API-driven inbound provisioning is currently in public preview. For more information about previews, see [Universal License Terms For Online Services](https://www.microsoft.com/licensing/terms/product/ForOnlineServices/all).

-## Introduction

-Today enterprises have a variety of authoritative systems of record. To establish end-to-end identity lifecycle, strengthen security posture and stay compliant with regulations, identity data in Microsoft Entra ID must be kept in sync with workforce data managed in these systems of record. The *system of record* could be an HR app, a payroll app, a spreadsheet or SQL tables in a database hosted either on-premises or in the cloud.

-With API-driven inbound provisioning, the Microsoft Entra provisioning service now supports integration with *any* system of record. Customers and partners can use *any* automation tool of their choice to retrieve workforce data from the system of record and ingest it into Microsoft Entra ID. The IT admin has full control on how the data is processed and transformed with attribute mappings. Once the workforce data is available in Microsoft Entra ID, the IT admin can configure appropriate joiner-mover-leaver business processes using [Lifecycle Workflows](../governance/what-are-lifecycle-workflows.md).

-## Supported scenarios

-Several inbound user provisioning scenarios are enabled using API-driven inbound provisioning. This diagram demonstrates the most common scenarios.

-### Scenario 1: Enable IT teams to import HR data extracts using any automation tool

-Flat files, CSV files and SQL staging tables are commonly used in enterprise integration scenarios. Employee, contractor and vendor information are periodically exported into one of these formats and an automation tool is used to sync this data with enterprise identity directories. With API-driven inbound provisioning, IT teams can use any automation tool of their choice (example: PowerShell scripts or Azure Logic Apps) to modernize and simplify this integration.

-<a name='scenario-2-enable-isvs-to-build-direct-integration-with-azure-ad'></a>

-### Scenario 2: Enable ISVs to build direct integration with Microsoft Entra ID

-With API-driven inbound provisioning, HR ISVs can ship native synchronization experiences so that changes in the HR system automatically flow into Microsoft Entra ID and connected on-premises Active Directory domains. For example, an HR app or student information systems app can send data to Microsoft Entra ID as soon as a transaction is complete or as end-of-day bulk update.

-### Scenario 3: Enable system integrators to build more connectors to systems of record

-Partners can build custom HR connectors to meet different integration requirements around data flow from systems of record to Microsoft Entra ID.

-In all the above scenarios, the integration is greatly simplified as Microsoft Entra provisioning service takes over the responsibility of performing identity profile comparison, restricting the data sync to scoping logic configured by the IT admin and executing rule-based attribute flow and transformation managed in the Microsoft Entra admin center.

-## End-to-end flow

-### Steps of the workflow

-1. IT Admin configures [an API-driven inbound user provisioning app](inbound-provisioning-api-configure-app.md) from the Microsoft Entra Enterprise App gallery.

-1. IT Admin [grants access permissions](inbound-provisioning-api-grant-access.md) and provides endpoint access details to the API developer/partner/system integrator.

-1. The API developer/partner/system integrator builds an API client to send authoritative identity data to Microsoft Entra ID.

-1. The API client reads identity data from the authoritative source.

-1. The API client sends a POST request to provisioning [/bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API endpoint associated with the provisioning app.

- >[!NOTE]

- > The API client doesn't need to perform any comparisons between the source attributes and the target attribute values to determine what operation (create/update/enable/disable) to invoke. This is automatically handled by the provisioning service. The API client simply uploads the identity data read from the source system by packaging it as bulk request using SCIM schema constructs.

-1. If successful, an ```Accepted 202 Status``` is returned.

-1. The Microsoft Entra provisioning service processes the data received, applies the attribute mapping rules and completes user provisioning.

-1. Depending on the provisioning app configured, the user is provisioned either into on-premises Active Directory (for hybrid users) or Microsoft Entra ID (for cloud-only users).

-1. The API Client then queries the provisioning logs API endpoint for the status of each record sent.

-1. If the processing of any record fails, the API client can check the error details and include records corresponding to the failed operations in the next bulk request (step 5).

-1. At any time, the IT Admin can check the status of the provisioning job and view events in the provisioning logs.

-### Key features of API-driven inbound user provisioning

-### Recommended learning path

-| # | Learning objective | Guidance |

-|-|-|-|

-| 1. | You want to learn more about the inbound provisioning API specs. | Refer to [/bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API spec document. |

-| 2. | You want to get more familiar with the API-driven provisioning concepts, scenarios and limitations. | Refer to [Frequently asked questions about API-driven inbound provisioning](inbound-provisioning-api-faqs.md). |

-| 3. | As an *Admin user*, you want to quickly test the inbound provisioning API. | * Create [API-driven inbound provisioning app](inbound-provisioning-api-configure-app.md) <br> * [Test API using Graph Explorer](inbound-provisioning-api-graph-explorer.md) |

-| 4. | With a service account or managed identity, you want to quickly test the inbound provisioning API. | * Create [API-driven inbound provisioning app](inbound-provisioning-api-configure-app.md) <br> * Grant [API permissions](inbound-provisioning-api-grant-access.md) <br> * [Test API using cURL](inbound-provisioning-api-curl-tutorial.md) or [Postman](inbound-provisioning-api-postman.md) |

-| 5. | You want to extend the API-driven provisioning app to process more custom attributes. | Refer to the tutorial [Extend API-driven provisioning to sync custom attributes](inbound-provisioning-api-custom-attributes.md) |

-| 6. | You want to automate data upload from your system of record to the inbound provisioning API endpoint. | Refer to the tutorials <br> * [Quick start with PowerShell](inbound-provisioning-api-powershell.md) <br> * [Quick start with Azure Logic Apps](inbound-provisioning-api-logic-apps.md) |

-| 7. | You want to troubleshoot inbound provisioning API issues | Refer to the [troubleshooting guide](inbound-provisioning-api-issues.md). |

-## Next steps

-description: Learn how to configure API-driven inbound provisioning app.

-# Configure API-driven inbound provisioning app (Public preview)

-## Introduction

-This tutorial describes how to configure [API-driven inbound user provisioning](inbound-provisioning-api-concepts.md).

-> [!IMPORTANT]

-> API-driven inbound provisioning is currently in public preview. For more information about previews, see [Universal License Terms For Online Services](https://www.microsoft.com/licensing/terms/product/ForOnlineServices/all).

-This feature is available only when you configure the following Enterprise Gallery apps:

-* API-driven inbound user provisioning to Microsoft Entra ID

-* API-driven inbound user provisioning to on-premises AD

-## Prerequisites

-To complete the steps in this tutorial, you need access to Microsoft Entra admin center with the following roles:

-* [Application Administrator](../roles/permissions-reference.md#application-administrator) (if you're configuring inbound user provisioning to Microsoft Entra ID) OR

-* [Application Administrator](../roles/permissions-reference.md#application-administrator) + [Hybrid Identity Administrator](../roles/permissions-reference.md#hybrid-identity-administrator) (if you're configuring inbound user provisioning to on-premises Active Directory)

-If you're configuring inbound user provisioning to on-premises Active Directory, you need access to a Windows Server where you can install the provisioning agent for connecting to your Active Directory domain controller.

-## Create your API-driven provisioning app

-1. Log in to the [Microsoft Entra admin center](<https://entra.microsoft.com>) as at least an [Application Administrator](https://go.microsoft.com/fwlink/?linkid=2247823).

-2. Browse to **Identity** > **Applications** > **Enterprise applications**.

-3. Click on **New application** to create a new provisioning application.

- [](media/inbound-provisioning-api-configure-app/provisioning-entra-admin-center.png#lightbox)

-4. Enter **API-driven** in the search field, then select the application for your setup:

- * **API-driven Inbound User Provisioning to On-Premises AD**: Select this app if you're provisioning hybrid identities (identities that need both on-premises AD and Microsoft Entra account) from your system of record. Once these accounts are provisioned in on-premises AD, they are automatically synchronized to your Microsoft Entra tenant using Microsoft Entra Connect Sync or Microsoft Entra Connect cloud sync.

- * **API-driven Inbound User Provisioning to Microsoft Entra ID**: Select this app if you're provisioning cloud-only identities (identities that don't require on-premises AD accounts and only need Microsoft Entra account) from your system of record.

-

- [](media/inbound-provisioning-api-configure-app/api-driven-inbound-provisioning-apps.png#lightbox)

-5. In the **Name** field, rename the application to meet your naming requirements, then click **Create**.

- [](media/inbound-provisioning-api-configure-app/provisioning-create-inbound-provisioning-app.png#lightbox)

- > [!NOTE]

- > If you plan to ingest data from multiple sources, each with their own sync rules, you can create multiple apps and give each app a descriptive name; for example, Provision-Employees-From-CSV-to-AD or Provision-Contractors-From-SQL-to-AD.

-6. Once the application creation is successful, go to the Provisioning blade and click on **Get started**.

- [](media/inbound-provisioning-api-configure-app/provisioning-overview-get-started.png#lightbox)

-7. Switch the Provisioning Mode from Manual to **Automatic**.

-Depending on the app you selected, use one of the following sections to complete your setup:

-* [Configure API-driven inbound provisioning to on-premises AD](#configure-api-driven-inbound-provisioning-to-on-premises-ad)

-* [Configure API-driven inbound provisioning to Microsoft Entra ID](#configure-api-driven-inbound-provisioning-to-azure-ad)

-## Configure API-driven inbound provisioning to on-premises AD

-1. After setting the Provisioning Mode to **Automatic**, click on **Save** to create the initial configuration of the provisioning job.

-1. Click on the information banner about the Microsoft Entra provisioning Agent.

- [](media/inbound-provisioning-api-configure-app/provisioning-agent-banner.png#lightbox)

-1. Click **Accept terms & download** to download the Microsoft Entra provisioning Agent.

-1. Refer to the steps documented here to [install and configure the provisioning agent.](https://go.microsoft.com/fwlink/?linkid=2241216). This step registers your on-premises Active Directory domains with your Microsoft Entra tenant.

-1. Once the agent registration is successful, select your domain in the drop-down **Active Directory domain** and specify the distinguished name of the OU where new user accounts are created by default.

- [](media/inbound-provisioning-api-configure-app/provisioning-select-active-directory-domain.png#lightbox)

- > [!NOTE]

- > If your AD domain is not visible in the **Active Directory Domain** dropdown list, reload the provisioning app in the browser. Click on **View on-premises agents for your domain** to ensure that your agent status is healthy.

-1. Click on **Test connection** to ensure that Microsoft Entra ID can connect to the provisioning agent.

-1. Click on **Save** to save your changes.

-1. Once the save operation is successful, you'll see two more expansion panels ΓÇô one for **Mappings** and one for **Settings**. Before proceeding to the next step, provide a valid notification email ID and save the configuration again.

- [](media/inbound-provisioning-api-configure-app/provisioning-notification-email.png#lightbox)

- > [!NOTE]

- > Providing the **Notification Email** in **Settings** is mandatory. If the Notification Email is left empty, then the provisioning goes into quarantine when you start the execution.

-1. Click on hyperlink in the **Mappings** expansion panel to view the default attribute mappings.

- > [!NOTE]

- > The default configuration in the **Attribute Mappings** page maps SCIM Core User and Enterprise User attributes to on-premises AD attributes. We recommend using the default mappings to get started and customizing these mappings later as you get more familiar with the overall data flow.

-1. Complete the configuration by following steps in the section [Start accepting provisioning requests](#start-accepting-provisioning-requests).

-<a name='configure-api-driven-inbound-provisioning-to-azure-ad'></a>

-## Configure API-driven inbound provisioning to Microsoft Entra ID

-

-1. After setting the Provisioning Mode to **Automatic**, click on **Save** to create the initial configuration of the provisioning job.

-1. Once the save operation is successful, you will see two more expansion panels ΓÇô one for **Mappings** and one for **Settings**. Before proceeding to the next step, make sure you provide a valid notification email id and Save the configuration once more.

- [](media/inbound-provisioning-api-configure-app/provisioning-notification-email.png#lightbox)

- > [!NOTE]

- > Providing the **Notification Email** in **Settings** is mandatory. If the Notification Email is left empty, then the provisioning goes into quarantine when you start the execution.

-1. Click on hyperlink in the **Mappings** expansion panel to view the default attribute mappings.

- > [!NOTE]

- > The default configuration in the **Attribute Mappings** page maps SCIM Core User and Enterprise User attributes to on-premises AD attributes. We recommend using the default mappings to get started and customizing these mappings later as you get more familiar with the overall data flow.

-1. Complete the configuration by following steps in the section [Start accepting provisioning requests](#start-accepting-provisioning-requests).

-## Start accepting provisioning requests

-1. Open the provisioning application's **Provisioning** > **Overview** page.

- :::image type="content" source="media/inbound-provisioning-api-configure-app/provisioning-api-endpoint.png" alt-text="Screenshot of Provisioning API endpoint." lightbox="media/inbound-provisioning-api-configure-app/provisioning-api-endpoint.png":::

-1. On this page, you can take the following actions:

- - **Start provisioning** control button ΓÇô Click on this button to place the provisioning job in **listen mode** to process inbound bulk upload request payloads.

- - **Stop provisioning** control button ΓÇô Use this option to pause/stop the provisioning job.

- - **Restart provisioning** control button ΓÇô Use this option to purge any existing request payloads pending processing and start a new provisioning cycle.

- - **Edit provisioning** control button ΓÇô Use this option to edit the job settings, attribute mappings and to customize the provisioning schema.

- - **Provision on demand** control button ΓÇô This feature is not supported for API-driven inbound provisioning.

- - **Provisioning API Endpoint** URL text ΓÇô Copy the HTTPS URL value shown and save it in a Notepad or OneNote for use later with the API client.

-1. Expand the **Statistics to date** > **View technical information** panel and copy the **Provisioning API Endpoint** URL. Share this URL with your API developer after [granting access permission](inbound-provisioning-api-grant-access.md) to invoke the API.

-## Next steps

-description: Learn how to get started with API-driven inbound provisioning using cURL.

-# Quickstart API-driven inbound provisioning with cURL (Public preview)

-## Introduction

-[cURL](https://curl.se/) is a popular, free, open-source, command-line tool used by API developers, and it's [available by default on Windows 10/11](https://curl.se/windows/microsoft.html). This tutorial describes how you can quickly test [API-driven inbound provisioning](inbound-provisioning-api-concepts.md) with cURL.

-## Pre-requisites

-* You have configured [API-driven inbound provisioning app](inbound-provisioning-api-configure-app.md).

-* You have [configured a service principal and it has access](inbound-provisioning-api-grant-access.md) to the inbound provisioning API. Make note of the `ClientId` and `ClientSecret` of your service principal app for use in this tutorial.

-## Upload user data to the inbound provisioning API

-1. Retrieve the **client_id** and **client_secret** of the service principal that has access to the inbound provisioning API.

-1. Use OAuth **client_credentials** grant flow to get an access token. Replace the variables `[yourClientId]`, `[yourClientSecret]` and `[yourTenantId]` with values applicable to your setup and run the following cURL command. Copy the access token value generated

- ```

- curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "client_id=[yourClientId]&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=[yourClientSecret]&grant_type=client_credentials" "https://login.microsoftonline.com/[yourTenantId]/oauth2/v2.0/token"

- ```

-1. Copy the [bulk request with SCIM Enterprise User Schema](#bulk-request-with-scim-enterprise-user-schema) and save the contents in a file called `scim-bulk-upload-users.json`.

-1. Replace the variable `[InboundProvisioningAPIEndpoint]` with the provisioning API endpoint associated with your provisioning app. Use the `[AccessToken]` value from the previous step and run the following curl command to upload the bulk request to the provisioning API endpoint.

- ```

- curl -v "[InboundProvisioningAPIEndpoint]" -d @scim-bulk-upload-users.json -H "Authorization: Bearer [AccessToken]" -H "Content-Type: application/scim+json"

- ```

-1. Upon successful upload, you'll receive HTTP 202 Accepted response code.

-1. The provisioning service starts processing the bulk request payload immediately and you can see the provisioning details by accessing the provisioning logs of the inbound provisioning app.

-## Verify processing of the bulk request payload

-1. Log in to [Microsoft Entra admin center](https://entra.microsoft.com) as at least an [Application Administrator](https://go.microsoft.com/fwlink/?linkid=2247823).

-1. Browse to **Microsoft Entra ID -> Applications -> Enterprise applications**.

-1. Under all applications, use the search filter text box to find and open your API-driven provisioning application.

-1. Open the Provisioning blade. The landing page displays the status of the last run.

-1. Click on **View provisioning logs** to open the provisioning logs blade. Alternatively, you can click on the menu option **Monitor -> Provisioning logs**.

- [](media/inbound-provisioning-api-curl-tutorial/access-provisioning-logs.png#lightbox)

-1. Click on any record in the provisioning logs to view more processing details.

-1. The provisioning log details screen displays all the steps executed for a specific user.

- [](media/inbound-provisioning-api-curl-tutorial/provisioning-log-details.png#lightbox)

- * Under the **Import from API** step, see details of user data extracted from the bulk request.

- * The **Match user** step shows details of any user match based on the matching identifier. If a user match happens, then the provisioning service performs an update operation. If there is no user match, then the provisioning service performs a create operation.

- * The **Determine if User is in scope** step shows details of scoping filter evaluation. By default, all users are processed. If you have set a scoping filter (example, process only users belonging to the Sales department), the evaluation details of the scoping filter displays in this step.

- * The **Provision User** step calls out the final processing step and changes applied to the user account.

- * Use the **Modified properties** tab to view attribute updates.

-## Appendix

-### Bulk request with SCIM Enterprise User Schema

-The bulk request shown below uses the SCIM standard Core User and Enterprise User schema.

-**Request body**

-```http

-{

- "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],

- "Operations": [

- {

- "method": "POST",

- "bulkId": "897401c2-2de4-4b87-a97f-c02de3bcfc61",

- "path": "/Users",

- "data": {

- "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],

- "externalId": "701984",

- "userName": "bjensen@example.com",

- "name": {

- "formatted": "Ms. Barbara J Jensen, III",

- "familyName": "Jensen",

- "givenName": "Barbara",

- "middleName": "Jane",

- "honorificPrefix": "Ms.",

- "honorificSuffix": "III"

- },

- "displayName": "Babs Jensen",

- "nickName": "Babs",

- "emails": [

- {

- "value": "bjensen@example.com",

- "type": "work",

- "primary": true

- }

- ],

- "addresses": [

- {

- "type": "work",

- "streetAddress": "100 Universal City Plaza",

- "locality": "Hollywood",

- "region": "CA",

- "postalCode": "91608",

- "country": "USA",

- "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",

- "primary": true

- }

- ],

- "phoneNumbers": [

- {

- "value": "555-555-5555",

- "type": "work"

- }

- ],

- "userType": "Employee",

- "title": "Tour Guide",

- "preferredLanguage": "en-US",

- "locale": "en-US",

- "timezone": "America/Los_Angeles",

- "active":true,

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

- "employeeNumber": "701984",

- "costCenter": "4130",

- "organization": "Universal Studios",

- "division": "Theme Park",

- "department": "Tour Operations",

- "manager": {

- "value": "89607",

- "displayName": "John Smith"

- }

- }

- }

- },

- {

- "method": "POST",

- "bulkId": "897401c2-2de4-4b87-a97f-c02de3bcfc61",

- "path": "/Users",

- "data": {

- "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],

- "externalId": "701985",

- "userName": "Kjensen@example.com",

- "name": {

- "formatted": "Ms. Kathy J Jensen, III",

- "familyName": "Jensen",

- "givenName": "Kathy",

- "middleName": "Jane",

- "honorificPrefix": "Ms.",

- "honorificSuffix": "III"

- },

- "displayName": "Kathy Jensen",

- "nickName": "Kathy",

- "emails": [

- {

- "value": "kjensen@example.com",

- "type": "work",

- "primary": true

- }

- ],

- "addresses": [

- {

- "type": "work",

- "streetAddress": "100 Oracle City Plaza",

- "locality": "Hollywood",

- "region": "CA",

- "postalCode": "91618",

- "country": "USA",

- "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",

- "primary": true

- }

- ],

- "phoneNumbers": [

- {

- "value": "555-555-5545",

- "type": "work"

- }

- ],

- "userType": "Employee",

- "title": "Tour Lead",

- "preferredLanguage": "en-US",

- "locale": "en-US",

- "timezone": "America/Los_Angeles",

- "active":true,

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

- "employeeNumber": "701985",

- "costCenter": "4130",

- "organization": "Universal Studios",

- "division": "Theme Park",

- "department": "Tour Operations",

- "manager": {

- "value": "701984",

- "displayName": "Barbara Jensen"

- }

- }

- }

- }

-],

- "failOnErrors": null

-}

-```

-## Next steps

-description: Learn how to extend API-driven inbound provisioning to sync custom attributes.

-# Extend API-driven provisioning to sync custom attributes (Public preview)

-By default, API-driven provisioning apps support processing attributes that are part of the standard SCIM Core User and Enterprise User schema. Your system of record may have custom attributes that you may want to include as part of API-driven provisioning. This advanced tutorial describes how to extend your API-driven provisioning app to process additional custom attributes.

-> [!NOTE]

-> Before trying this advanced scenario, we recommend verifying that your out-of-the-box provisioning app configuration works as expected using one of the following API clients [Graph Explorer](inbound-provisioning-api-graph-explorer.md), [cURL](inbound-provisioning-api-curl-tutorial.md) or [Postman](inbound-provisioning-api-postman.md).

-## Example scenario

-You have configured API-driven provisioning app. You're provisioning app is successfully consuming the attributes that are part of the standard SCIM Core User and Enterprise User schema and provisioning users in Microsoft Entra ID. You now want to send two custom attributes `HireDate` and `JobCode` from your HR system to the inbound provisioning API endpoint. You'd like to map these two custom attributes to Microsoft Entra attributes `employeeHireDate` and `jobTitle`.

-## Step 1 - Extend the provisioning app schema

-In this step, we'll add the two attributes "HireDate" and "JobCode" that are not part of the standard SCIM schema to the provisioning app and use them in the provisioning data flow.

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least an [Application Administrator](https://go.microsoft.com/fwlink/?linkid=2247823).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. Open your API-driven provisioning app.

-1. Open the **Provisioning** blade.

-1. Click on the **Edit Provisioning** button.

-1. Expand the **Mappings** section and click on the attribute mapping link. <br>

- :::image type="content" border="true" source="./media/inbound-provisioning-api-custom-attributes/edit-attribute-mapping.png" alt-text="Screenshot of edit attribute mapping." lightbox="./media/inbound-provisioning-api-custom-attributes/edit-attribute-mapping.png":::

-1. Scroll down the **Attribute Mappings** page. Select **Show advanced options** and click on the **Edit attribute list for API** link.

- :::image type="content" border="true" source="./media/inbound-provisioning-api-custom-attributes/edit-api-attribute-list.png" alt-text="Screenshot of edit API attribute list." lightbox="./media/inbound-provisioning-api-custom-attributes/edit-api-attribute-list.png":::

-1. Scroll down to the end of the **Edit Attribute List** page.

-1. Add the following two attributes to the list as SCIM schema extensions. You can use your own SCIM schema namespace. <br>

- `urn:ietf:params:scim:schemas:extension:contoso:1.0:User:HireDate` <br>

- `urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode` <br>

- :::image type="content" border="true" source="./media/inbound-provisioning-api-custom-attributes/add-custom-attributes.png" alt-text="Screenshot of adding custom attributes." lightbox="./media/inbound-provisioning-api-custom-attributes/add-custom-attributes.png":::

-1. **Save** your changes

-> [!NOTE]

-> If you'd like to add only a few additional attributes to the provisioning app, use Microsoft Entra admin center to extend the schema. If you'd like to add more custom attributes (let's say 20+ attributes), then we recommend using the [`UpdateSchema` mode of the CSV2SCIM PowerShell script](inbound-provisioning-api-powershell.md#extending-provisioning-job-schema) which automates the above manual process.

-## Step 2 - Map the custom attributes

-Let's now add these extensions to the provisioning app attribute mapping.

-1. Click on the **Add New Mapping** link on the **Attribute mapping** page.

- :::image type="content" border="true" source="./media/inbound-provisioning-api-custom-attributes/add-new-mapping.png" alt-text="Screenshot of add new mapping." lightbox="./media/inbound-provisioning-api-custom-attributes/add-new-mapping.png":::

-1. Map the `urn:ietf:params:scim:schemas:extension:contoso:1.0:User:HireDate` attribute to `employeeHireDate`. Click **OK**. <br>

- :::image type="content" border="true" source="./media/inbound-provisioning-api-custom-attributes/hire-date-mapping.png" alt-text="Screenshot of hire date mapping." lightbox="./media/inbound-provisioning-api-custom-attributes/hire-date-mapping.png":::

-1. Next, select the existing mapping for `title` and click on it to edit the mapping.

-1. Edit the attribute mapping to an expression that will include the `urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode` as part of the `jobTitle` Microsoft Entra attribute.

- ```

- Join("", [title], "(", [urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode], ")")

- ```

- :::image type="content" border="true" source="./media/inbound-provisioning-api-custom-attributes/job-title-mapping.png" alt-text="Screenshot of job title mapping." lightbox="./media/inbound-provisioning-api-custom-attributes/job-title-mapping.png":::

- With this expression mapping, if the `title` is "Tour Lead" and `JobCode`is "TL-1001", then the Microsoft Entra attribute `jobTitle` will be set to "Tour Lead (TL-1001)".

-1. Save the attribute mappings.

-## Step 3 - Upload bulk request with custom attributes

-1. Open your API client (Graph Explorer / Postman / cURL).

-1. Copy-paste the [bulk request with custom attributes](#bulk-request-with-custom-attributes).

-1. Send the bulk request to your provisioning API endpoint URL. <br>

- :::image type="content" border="true" source="./media/inbound-provisioning-api-custom-attributes/upload-bulk-request.png" alt-text="Screenshot of bulk upload request." lightbox="./media/inbound-provisioning-api-custom-attributes/upload-bulk-request.png":::

-1. After some time, you can check the provisioning logs to verify the attribute change. <br>

- :::image type="content" border="true" source="./media/inbound-provisioning-api-custom-attributes/verify-provisioning-logs.png" alt-text="Screenshot of provisioning logs." lightbox="./media/inbound-provisioning-api-custom-attributes/verify-provisioning-logs.png":::

-1. You can also verify the change in the Microsoft Entra user profile. The value for `Employee hire date` reflects your tenant time zone. <br>

- :::image type="content" border="true" source="./media/inbound-provisioning-api-custom-attributes/verify-user-profile.png" alt-text="Screenshot of user profile." lightbox="./media/inbound-provisioning-api-custom-attributes/verify-user-profile.png":::

-## Appendix

-### Bulk request with custom attributes

-The bulk request includes the custom attributes configured in the steps above.

-**Request body**

-```http

-{

- "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],

- "Operations": [

- {

- "method": "POST",

- "bulkId": "701984",

- "path": "/Users",

- "data": {

- "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",

- "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"],

- "externalId": "701984",

- "userName": "bjensen@example.com",

- "name": {

- "formatted": "Ms. Barbara J Jensen, III",

- "familyName": "Jensen",

- "givenName": "Barbara",

- "middleName": "Jane",

- "honorificPrefix": "Ms.",

- "honorificSuffix": "III"

- },

- "displayName": "Babs Jensen",

- "nickName": "Babs",

- "emails": [

- {

- "value": "bjensen@example.com",

- "type": "work",

- "primary": true

- }

- ],

- "addresses": [

- {

- "type": "work",

- "streetAddress": "234300 Universal City Plaza",

- "locality": "Hollywood",

- "region": "CA",

- "postalCode": "91608",

- "country": "USA",

- "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",

- "primary": true

- }

- ],

- "phoneNumbers": [

- {

- "value": "555-555-5555",

- "type": "work"

- }

- ],

- "userType": "Employee",

- "title": "Tour Guide",

- "preferredLanguage": "en-US",

- "locale": "en-US",

- "timezone": "America/Los_Angeles",

- "active":true,

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

- "employeeNumber": "701984",

- "costCenter": "4130",

- "organization": "Universal Studios",

- "division": "Theme Park",

- "department": "Tour Operations",

- "manager": {

- "value": "89607",

- "displayName": "John Smith"

- }

- },

- "urn:ietf:params:scim:schemas:extension:contoso:1.0:User": {

- "HireDate": "2021-05-01T00:00:00-05:00",

- "JobCode": "TG-1001"

- }

- }

- },

- {

- "method": "POST",

- "bulkId": "701985",

- "path": "/Users",

- "data": {

- "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",

- "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"],

- "externalId": "701985",

- "userName": "Kjensen@example.com",

- "name": {

- "formatted": "Ms. Kathy J Jensen, III",

- "familyName": "Jensen",

- "givenName": "Kathy",

- "middleName": "Jane",

- "honorificPrefix": "Ms.",

- "honorificSuffix": "III"

- },

- "displayName": "Kathy Jensen",

- "nickName": "Kathy",

- "emails": [

- {

- "value": "kjensen@example.com",

- "type": "work",

- "primary": true

- }

- ],

- "addresses": [

- {

- "type": "work",

- "streetAddress": "100 Oracle City Plaza",

- "locality": "Hollywood",

- "region": "CA",

- "postalCode": "91618",

- "country": "USA",

- "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",

- "primary": true

- }

- ],

- "phoneNumbers": [

- {

- "value": "555-555-5545",

- "type": "work"

- }

- ],

- "userType": "Employee",

- "title": "Tour Lead",

- "preferredLanguage": "en-US",

- "locale": "en-US",

- "timezone": "America/Los_Angeles",

- "active":true,

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

- "employeeNumber": "701984",

- "costCenter": "4130",

- "organization": "Universal Studios",

- "division": "Theme Park",

- "department": "Tour Operations",

- "manager": {

- "value": "701984",

- "displayName": "Barbara Jensen"

- }

- },

- "urn:ietf:params:scim:schemas:extension:contoso:1.0:User": {

- "HireDate": "2022-07-15T00:00:00-05:00",

- "JobCode": "TL-1003"

- }

- }

- }

-],

- "failOnErrors": null

-}

-```

-## Next steps

-description: Learn more about the capabilities and integration scenarios supported by API-driven inbound provisioning.

-# Frequently asked questions about API-driven inbound provisioning (Public preview)

-This article answers frequently asked questions (FAQs) about API-driven inbound provisioning.

-## How is the new inbound provisioning /bulkUpload API different from MS Graph Users API?

-There are significant differences between the provisioning /bulkUpload API and the MS Graph Users API endpoint.

- - When identity data is sent to the MS Graph Users API endpoint, it's immediately processed, and a Create/Update/Delete operation takes place on the Microsoft Entra user profile.

- - Request data sent to the provisioning /bulkUpload API is processed *asynchronously* by the Microsoft Entra provisioning service. The provisioning job applies scoping rules, attribute mapping and transformation configured by the IT admin. This initiates a ```Create/Update/Delete``` operation on the Microsoft Entra user profile or the on-premises AD user profile.

-## Is the inbound provisioning /bulkUpload API a standard SCIM endpoint?

-The MS Graph inbound provisioning /bulkUpload API uses SCIM schema in the request payload, but it's *not* a standardized SCIM API endpoint. Here's why.

-Typically, a SCIM service endpoint processes HTTP requests (POST, PUT, GET) with SCIM payload and translates them to respective operations of (Create, Update, Lookup) on the identity store. The SCIM service endpoint places the onus of specifying the operation semantics, whether to Create/Update/Delete an identity, on the SCIM API client. This mechanism works well for scenarios where the API client is aware what operation it would like to perform for users in the identity store.

-The MS Graph inbound provisioning /bulkUpload is designed to handle a different enterprise identity integration scenario shaped by three unique requirements:

-1. Ability to asynchronously process records in bulk (for example, processing 50K+ records)

-2. Ability to include any identity attribute in the payload (for example, costCenter, pay grade, badgeId)

-3. Support API clients unaware of operation semantics. These clients are non-SCIM API clients that only have access to raw *source data* (for example, records in CSV file, SQL table or HR records). These clients don't have the processing capability to read each record and determine the operation semantics of ```Create/Update/Delete``` on the identity store.

-The primary goal of MS Graph inbound provisioning /bulkUpload API is to enable customers to send *any* identity data (for example, costCenter, pay grade, badgeId) from *any* identity data source (for example, CSV/SQL/HR) for eventual processing by Microsoft Entra provisioning service. The Microsoft Entra provisioning service consumes the bulk payload data received at this endpoint, applies attribute mapping rules configured by the IT admin and determines whether the data payload leads to (Create, Update, Enable, Disable) operation in the target identity store (Microsoft Entra ID / on-premises AD).

-## Does the provisioning /bulkUpload API support on-premises Active Directory domains as a target?

-Yes, the provisioning API supports on-premises AD domains as a target.

-## How do we get the /bulkUpload API endpoint for our provisioning app?

-The /bulkUpload API is available only for apps of the type: "API-driven inbound provisioning to Microsoft Entra ID" and "API-driven inbound provisioning to on-premises Active Directory". You can retrieve the unique API endpoint for each provisioning app from the Provisioning blade home page. In **Statistics to date** > **View technical information**,copy the **Provisioning API Endpoint** URL.

- :::image type="content" source="media/inbound-provisioning-api-configure-app/provisioning-api-endpoint.png" alt-text="Screenshot of Provisioning API endpoint." lightbox="media/inbound-provisioning-api-configure-app/provisioning-api-endpoint.png":::

-It has the format:

-```http

-https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

-```

-## How do we perform a full sync using the provisioning /bulkUpload API?

-To perform a full sync, use your API client to send the data of all users from your trusted source to the API endpoint as bulk request. Once you send all the data to the API endpoint, the next sync cycle processes all user records and allows you to track the progress using the provisioning logs API endpoint.

-## How do we perform delta sync using the provisioning /bulkUpload API?

-To perform a delta sync, use your API client to only send information about users whose data has changed in the trusted source. Once you send all the data to the API endpoint, the next sync cycle processes all user records and allows you to track the progress using the provisioning logs API endpoint.

-## How does restart provisioning work?

-Use the **Restart provisioning** option only if required. Here's how it works:

-**Scenario 1:** When you click the **Restart provisioning** button and the job is currently running, the job continues processing the existing data that is already staged. The**Restart provisioning** operation doesn't interrupt an existing cycle. In the subsequent cycle, the provisioning service clears any escrows and picks the new bulk request for processing.

-**Scenario 2:** When you click the **Restart provisioning** button and the job is *not* running, then before running subsequent cycle, the provisioning engine purges the data uploaded prior to the restart, clears any escrows, and only processes new incoming data.

-## How do we create users using the provisioning /bulkUpload API endpoint?

-Here's how the provisioning job associated with the /bulkUpload API endpoint processes incoming user payloads:

-1. The job retrieves the attribute mapping for the provisioning job and makes note of the matching attribute pair (by default ```externalId``` API attribute is used to match with ```employeeId``` in Microsoft Entra ID).

-1. You can change this default attribute matching pair.

-1. The job extracts each operation present in the bulk request payload.

-1. The job checks the value matching identifier in the request (by default the attribute `externalId`) and uses it to check if there's a user in Microsoft Entra ID with matching `employeeId` value.

-1. If the job doesn't find a matching user, then the job applies the sync rules and creates a new user in the target directory.

-To make sure that the right users get created in Microsoft Entra ID, define the right matching attribute pair in your mapping which uniquely identifies users in your source and Microsoft Entra ID.

-## How do we generate unique values for UPN?

-The provisioning service doesn't provide the ability to check for duplicate ```userPrincipalName``` (UPN) and handle conflicts. If the default sync rule for UPN attribute generates an existing UPN value, then the user create operation fails.

-Here are some options that you can consider for generating unique UPNs:

-1. Add the logic for unique UPN generation in your API client.

-2. Update the sync rule for the UPN attribute to use the [RandomString](functions-for-customizing-application-data.md) function and set the apply mapping parameter to ```On object creation only```. Example:

-```Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())```

-3. If you are provisioning to on-premises Active Directory, you can use the [SelectUniqueValue](functions-for-customizing-application-data.md) function and set the apply mapping parameter to ```On object creation only```.

-## How do we send more HR attributes to the provisioning /bulkUpload API endpoint?

-By default, the API endpoint supports processing any attribute that is part of the SCIM Core User and Enterprise User schema. If you'd like to send more attributes, you can extend the provisioning app schema, map the new attributes to Microsoft Entra attributes and update the bulk request to send those attributes.

-Refer to the tutorial [Extend API-driven provisioning to sync custom attributes](inbound-provisioning-api-custom-attributes.md).

-## How do we exclude certain users from the provisioning flow?

-You may have a scenario where you want to send all users to the API endpoint, but only include certain users in the provisioning flow and exclude the rest.

-You can achieve this using the **Scoping filter**. In the provisioning app configuration, you can define a source object scope and exclude certain users from processing either using an "inclusion rule" (for example, only process users where department EQUALS **Sales**) or an "exclusion rule" (for example, exclude users belonging to Sales, department NOT EQUALS **Sales**).

-

- See [Scoping users or groups to be provisioned with scoping filters](define-conditional-rules-for-provisioning-user-accounts.md).

-## How do we update users using the provisioning /bulkUpload API endpoint?

-Here's how the provisioning job associated with the /bulkUpload API endpoint processes incoming user payloads:

-1. The provisioning job retrieves the attribute mapping for the provisioning job and makes note of the matching attribute pair (by default ```externalId``` API attribute is used to match with ```employeeId``` in Microsoft Entra ID). You can change this default attribute matching pair.

-1. The job extracts the operations from the bulk request payload.

-1. The job checks the value matching identifier in the SCIM request (by default: API attribute ```externalId```) and uses it to check if there's a user in Microsoft Entra ID with matching ```employeeId``` value.

-1. If the job finds a matching user, then it applies the sync rules and compares the source and target profiles.

-1. If the job determines that some values have changed, then it updates the corresponding user record in the directory.

-To make sure that the right users get updated in Microsoft Entra ID, make sure you define the right matching attribute pair in your mapping which uniquely identifies users in your source and Microsoft Entra ID.

-## Can we create more than one app that supports API-driven inbound provisioning?

-Yes, you can. Here are some scenarios that may require more than one provisioning app:

-**Scenario 1:** Let's say you have three trusted data sources: one for employees, one for contractors and one for vendors. You can create three separate provisioning apps ΓÇô one for each identity type with its own distinct attribute mapping. Each provisioning app has a unique API endpoint, and you can send the respective payloads to each endpoint.

-You can retrieve the unique API endpoint for each job from the Provisioning blade home page. Navigate to **Statistics to date** > **View technical information**, then copy the **Provisioning API Endpoint** URL.

-**Scenario 2:** Let's say you have multiple sources of truth, each with its own attribute set. For example, HR provides job info attributes (for example jobTitle, employeeType), and the Badging System provides badge information attributes (for example ```badgeId``` that is represented using an extension attribute). In this scenario, you can configure two provisioning apps:

-## How do we process terminations using the /bulkUpload API endpoint?

-To process terminations, identify an attribute in your source that will be used to set the ```accountEnabled``` flag in Microsoft Entra ID. If you are provisioning to on-premises Active Directory, then map that source attribute to the `accountDisabled` attribute.

-By default, the value associated with the SCIM Core User schema attribute ```active``` determines the status of the user's account in the target directory.

-If the attribute is set to **true**, the default mapping rule enables the account. If the attribute is set to **false**, then the default mapping rule disables the account.

-<a name='can-we-soft-delete-a-user-in-azure-ad-using-bulkupload-provisioning-api'></a>

-## Can we soft-delete a user in Microsoft Entra ID using /bulkUpload provisioning API?

-Yes, you can soft-delete a user by using the **DELETE** method in the bulk request operation. Refer to the [bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API spec doc for an example request.

-## How can we prevent accidental disabling/deletion of users?

-To prevent and recover from accidental deletions, we recommend [configuring accidental deletion threshold](accidental-deletions.md) in the provisioning app and [enabling the on-premises Active Directory recycle bin](../hybrid/connect/how-to-connect-sync-recycle-bin.md). In your provisioning app's **Attribute Mapping** blade, under **Target object actions** disable the **Delete** operation.

-**Recovering deleted accounts**

-* If the target directory for the operation is Microsoft Entra ID, then the matched user is soft-deleted. The user can be seen on the Microsoft Entra admin center **Deleted users** page for the next 30 days and can be restored during that time.

-* If the target directory for the operation is on-premises Active Directory, then the matched user is hard-deleted. If the **Active Directory Recycle Bin** is enabled, you can restore the deleted on-premises AD user object.

-## Do we need to send all users from the HR system in every request?

-No, you don't need to send all users from the HR system / "source of truth" in every request. Just send the users that you'd like create or update.

-## Does the API support all HTTP actions (GET/POST/PUT/PATCH)?

-No, the /bulkUpload provisioning API endpoint only supports the POST HTTP action.

-## If I want to update a user, do I need to send a PUT/PATCH request?

-No, the API endpoint doesn't support PUT/PATCH request. To update a user, send the data associated with the user in the POST bulk request payload.

-The provisioning job that processes data received by the API endpoint automatically detects whether the user received in the POST request payload needs to be create/updated/enable/disabled based on the configured sync rules. As an API client, you don't need to take any more steps if you want a user profile to be updated.

-## How is writeback supported?

-The current API only supports inbound data. Here are some options to consider for implementing writeback of attributes like email / username / phone generated by Microsoft Entra ID, that you can flow back to the HR system:

- - If the system of record provides a SCIM endpoint for user updates (for example Oracle HCM provides an [API endpoint for SCIM updates](https://docs.oracle.com/en/cloud/saas/applications-common/23b/farc#integrate-your-scim-endpoint-with-the-azure-ad-provisioning-service).

- - If the system of record doesn't provide a SCIM endpoint, explore the possibility of setting up a proxy SCIM service, which receives the update and propagate the change to the HR system.

- - Depending on the customer requirement, explore if one of the ECMA connectors could be used (PowerShell / SQL / Web Services).

- - In Lifecycle Workflows, define a Joiner workflow and define a [custom extension task that invokes a Logic Apps process](https://go.microsoft.com/fwlink/?linkid=2239990), which updates the HR system or generates a CSV file consumed by the HR system.

-## Next steps

-description: Learn how to grant access to the inbound provisioning API.

-# Grant access to the inbound provisioning API (Public preview)

-## Introduction

-After you've configured [API-driven inbound provisioning app](inbound-provisioning-api-configure-app.md), you need to grant access permissions so that API clients can send requests to the provisioning [/bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API and query the [provisioning logs API](/graph/api/resources/provisioningobjectsummary). This tutorial walks you through the steps to configure these permissions.

-Depending on how your API client authenticates with Microsoft Entra ID, you can select between two configuration options:

-* [Configure a service principal](#configure-a-service-principal): Follow these instructions if your API client plans to use a service principal of an [Microsoft Entra registered app](../develop/howto-create-service-principal-portal.md) and authenticate using OAuth client credentials grant flow.

-* [Configure a managed identity](#configure-a-managed-identity): Follow these instructions if your API client plans to use a Microsoft Entra [managed identity](../managed-identities-azure-resources/overview.md).

-## Configure a service principal

-This configuration registers an app in Microsoft Entra ID that represents the external API client and grants it permission to invoke the inbound provisioning API. The service principal client id and client secret can be used in the OAuth client credentials grant flow.

-1. Log in to Microsoft Entra admin center (https://entra.microsoft.com) with at least [Application Administrator](https://go.microsoft.com/fwlink/?linkid=2247823) login credentials.

-1. Browse to **Microsoft Entra ID** -> **Applications** -> **App registrations**.

-1. Click on the option **New registration**.

-1. Provide an app name, select the default options, and click on **Register**.

- [](media/inbound-provisioning-api-grant-access/register-app.png#lightbox)

-1. Copy the **Application (client) ID** and **Directory (tenant) ID** values from the Overview blade and save it for later use in your API client.

- [](media/inbound-provisioning-api-grant-access/app-client-id.png#lightbox)

-1. In the context menu of the app, select **Certificates & secrets** option.

-1. Create a new client secret. Provide a description for the secret and expiry date.

-1. Copy the generated value of the client secret and save it for later use in your API client.

-1. From the context menu **API permissions**, select the option **Add a permission**.

-1. Under **Request API permissions**, select **Microsoft Graph**.

-1. Select **Application permissions**.

-1. Search and select permission **AuditLog.Read.All** and **SynchronizationData-User.Upload**.

-1. Click on **Grant admin consent** on the next screen to complete the permission assignment. Click Yes on the confirmation dialog. Your app should have the following permission sets.

- [](media/inbound-provisioning-api-grant-access/api-client-permissions.png#lightbox)

-1. You're now ready to use the service principal with your API client.

-1. For production workloads, we recommend using [client certificate-based authentication](../develop/howto-authenticate-service-principal-powershell.md) with the service principal or managed identities.

-## Configure a managed identity

-This section describes how you can assign the necessary permissions to a managed identity.

-1. Configure a [managed identity](../managed-identities-azure-resources/overview.md) for use with your Azure resource.

-1. Copy the name of your managed identity from the Microsoft Entra admin center. For example: The screenshot below shows the name of a system assigned managed identity associated with an Azure Logic Apps workflow called "CSV2SCIMBulkUpload".

- [](media/inbound-provisioning-api-grant-access/managed-identity-name.png#lightbox)

-1. Run the following PowerShell script to assign permissions to your managed identity.

- ```powershell

- Install-Module Microsoft.Graph -Scope CurrentUser

- Connect-MgGraph -Scopes "Application.Read.All","AppRoleAssignment.ReadWrite.All,RoleManagement.ReadWrite.Directory"

- Select-MgProfile Beta

- $graphApp = Get-MgServicePrincipal -Filter "AppId eq '00000003-0000-0000-c000-000000000000'"

-

- $PermissionName = "SynchronizationData-User.Upload"

- $AppRole = $graphApp.AppRoles | `

- Where-Object {$_.Value -eq $PermissionName -and $_.AllowedMemberTypes -contains "Application"}

- $managedID = Get-MgServicePrincipal -Filter "DisplayName eq 'CSV2SCIMBulkUpload'"

- New-MgServicePrincipalAppRoleAssignment -PrincipalId $managedID.Id -ServicePrincipalId $managedID.Id -ResourceId $graphApp.Id -AppRoleId $AppRole.Id

- $PermissionName = "AuditLog.Read.All"

- $AppRole = $graphApp.AppRoles | `

- Where-Object {$_.Value -eq $PermissionName -and $_.AllowedMemberTypes -contains "Application"}

- $managedID = Get-MgServicePrincipal -Filter "DisplayName eq 'CSV2SCIMBulkUpload'"

- New-MgServicePrincipalAppRoleAssignment -PrincipalId $managedID.Id -ServicePrincipalId $managedID.Id -ResourceId $graphApp.Id -AppRoleId $AppRole.Id

- ```

-1. To confirm that the permission was applied, find the managed identity service principal under **Enterprise Applications** in Microsoft Entra ID. Remove the **Application type** filter to see all service principals.

- [](media/inbound-provisioning-api-grant-access/managed-identity-principal.png#lightbox)

-1. Click on the **Permissions** blade under **Security**. Ensure the permission is set.

- [](media/inbound-provisioning-api-grant-access/managed-identity-permissions.png#lightbox)

-1. You're now ready to use the managed identity with your API client.

-## Next steps

-description: Learn how to get started quickly with API-driven inbound provisioning using Graph Explorer

-# Quickstart API-driven inbound provisioning with Graph Explorer (Public preview)

-This tutorial describes how you can quickly test [API-driven inbound provisioning](inbound-provisioning-api-concepts.md) with Microsoft Graph Explorer.

-## Pre-requisites

-* You have configured [API-driven inbound provisioning app](inbound-provisioning-api-configure-app.md).

-> [!NOTE]

-> This provisioning API is primarily meant for use within an application or service. Tenant admins can either configure a service principal or managed identity to grant permission to perform the upload. There is no separate user-assignable Microsoft Entra built-in directory role for this API. Outside of applications that have acquired `SynchronizationData-User.Upload` permission with admin consent, only admin users with Global Administrator role can invoke the API. This tutorial shows how you can test the API with a global administrator role in your test setup.

-## Upload user data to the inbound provisioning API

-1. Open a new browser tab or browser window.

-1. Launch the URL https://aka.ms/ge to access Microsoft Graph Explorer.

-1. Click on the user profile icon to sign in.

- [](media/inbound-provisioning-api-graph-explorer/provisioning-user-profile-icon.png#lightbox)

-1. Complete the login process with a user account that has *Global Administrator* role.

-1. Upon successful login, the Tenant information shows your tenant name.

- [](media/inbound-provisioning-api-graph-explorer/provisioning-tenant-name.png#lightbox)

- You're now ready to invoke the API.

-1. In the API request panel, set the HTTP request type to **POST**.

-1. Copy and paste the provisioning API endpoint retrieved from the provisioning app overview page.

-1. Under the Request headers panel, add a new key value pair of **Content-Type = application/scim+json**.

- [](media/inbound-provisioning-api-graph-explorer/provisioning-request-header-panel.png#lightbox)

-1. Under the **Request body** panel, copy-paste the [bulk request with SCIM Enterprise User Schema](#bulk-request-with-scim-enterprise-user-schema)

-1. Click on the **Run query** button to send the request to the provisioning API endpoint.

-1. If the request is sent successfully, you'll get an `Accepted 202` response from the API endpoint.

-1. Open the **Response headers** panel and copy the URL value of the location attribute. This points to the provisioning logs API endpoint that you can query to check the provisioning status of users present in the bulk request.

-## Verify processing of bulk request payload

-You can verify the processing either from the Microsoft Entra admin center or using Graph Explorer.

-### Verify processing from Microsoft Entra admin center

-1. Log in to [Microsoft Entra admin center](https://entra.microsoft.com) with at least [Application Administrator](https://go.microsoft.com/fwlink/?linkid=2247823) login credentials.

-1. Browse to **Microsoft Entra ID -> Applications -> Enterprise applications**.

-1. Under all applications, use the search filter text box to find and open your API-driven provisioning application.

-1. Open the Provisioning blade. The landing page displays the status of the last run.

-1. Click on **View provisioning logs** to open the provisioning logs blade. Alternatively, you can click on the menu option **Monitor -> Provisioning logs**.

- [](media/inbound-provisioning-api-curl-tutorial/access-provisioning-logs.png#lightbox)

-1. Click on any record in the provisioning logs to view additional processing details.

-1. The provisioning log details screen displays all the steps executed for a specific user.

- [](media/inbound-provisioning-api-curl-tutorial/provisioning-log-details.png#lightbox)

- * Under the **Import from API** step, see details of user data extracted from the bulk request.

- * The **Match user** step shows details of any user match based on the matching identifier. If a user match happens, then the provisioning service performs an update operation. If there is no user match, then the provisioning service performs a create operation.

- * The **Determine if User is in scope** step shows details of scoping filter evaluation. By default, all users are processed. If you have set a scoping filter (example, process only users belonging to the Sales department), the evaluation details of the scoping filter displays in this step.

- * The **Provision User** step calls out the final processing step and changes applied to the user account.

- * Use the **Modified properties** tab to view attribute updates.

-### Verify processing using provisioning logs API in Graph Explorer

-You can inspect the processing using the provisioning logs API URL returned as part of the location response header in the provisioning API call.

-1. In the Graph Explorer, **Request URL** text box copy-paste the location URL returned by the provisioning API endpoint or you can construct it using the format: `https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid eq '<jobId>'` where you can retrieve the ```jobId``` from the provisioning app overview page.

-1. Use the method **GET** and click **Run query** to retrieve the provisioning logs. By default, the response returned contains all log records.

-1. You can set more filters to only retrieve data after a certain time frame or with a specific status value.

- `https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid eq '<jobId> and statusInfo/status eq 'failure' and activityDateTime ge 2022-10-10T09:47:34Z`

- You can also check the status of the user by the ```externalId``` value used in your source system that is used as the source anchor / joining property.

- `https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid eq '<jobId>' and sourceIdentity/id eq '701984'`

-## Appendix

-### Bulk request with SCIM Enterprise User Schema

-The bulk request shown below uses the SCIM standard Core User and Enterprise User schema.

-**Request body**

-```http

-{

- "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],

- "Operations": [

- {

- "method": "POST",

- "bulkId": "897401c2-2de4-4b87-a97f-c02de3bcfc61",

- "path": "/Users",

- "data": {

- "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],

- "externalId": "701984",

- "userName": "bjensen@example.com",

- "name": {

- "formatted": "Ms. Barbara J Jensen, III",

- "familyName": "Jensen",

- "givenName": "Barbara",

- "middleName": "Jane",

- "honorificPrefix": "Ms.",

- "honorificSuffix": "III"

- },

- "displayName": "Babs Jensen",

- "nickName": "Babs",

- "emails": [

- {

- "value": "bjensen@example.com",

- "type": "work",

- "primary": true

- }

- ],

- "addresses": [

- {

- "type": "work",

- "streetAddress": "100 Universal City Plaza",

- "locality": "Hollywood",

- "region": "CA",

- "postalCode": "91608",

- "country": "USA",

- "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",

- "primary": true

- }

- ],

- "phoneNumbers": [

- {

- "value": "555-555-5555",

- "type": "work"

- }

- ],

- "userType": "Employee",

- "title": "Tour Guide",

- "preferredLanguage": "en-US",

- "locale": "en-US",

- "timezone": "America/Los_Angeles",

- "active":true,

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

- "employeeNumber": "701984",

- "costCenter": "4130",

- "organization": "Universal Studios",

- "division": "Theme Park",

- "department": "Tour Operations",

- "manager": {

- "value": "89607",

- "displayName": "John Smith"

- }

- }

- }

- },

- {

- "method": "POST",

- "bulkId": "897401c2-2de4-4b87-a97f-c02de3bcfc61",

- "path": "/Users",

- "data": {

- "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],

- "externalId": "701985",

- "userName": "Kjensen@example.com",

- "name": {

- "formatted": "Ms. Kathy J Jensen, III",

- "familyName": "Jensen",

- "givenName": "Kathy",

- "middleName": "Jane",

- "honorificPrefix": "Ms.",

- "honorificSuffix": "III"

- },

- "displayName": "Kathy Jensen",

- "nickName": "Kathy",

- "emails": [

- {

- "value": "kjensen@example.com",

- "type": "work",

- "primary": true

- }

- ],

- "addresses": [

- {

- "type": "work",

- "streetAddress": "100 Oracle City Plaza",

- "locality": "Hollywood",

- "region": "CA",

- "postalCode": "91618",

- "country": "USA",

- "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",

- "primary": true

- }

- ],

- "phoneNumbers": [

- {

- "value": "555-555-5545",

- "type": "work"

- }

- ],

- "userType": "Employee",

- "title": "Tour Lead",

- "preferredLanguage": "en-US",

- "locale": "en-US",

- "timezone": "America/Los_Angeles",

- "active":true,

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

- "employeeNumber": "701985",

- "costCenter": "4130",

- "organization": "Universal Studios",

- "division": "Theme Park",

- "department": "Tour Operations",

- "manager": {

- "value": "701984",

- "displayName": "Barbara Jensen"

- }

- }

- }

- }

-],

- "failOnErrors": null

-}

-```

-## Next steps

-description: Learn how to troubleshoot issues with the inbound provisioning API.

-# Troubleshoot inbound provisioning API issues (Public preview)

-## Introduction

-This document covers commonly encountered errors and issues with inbound provisioning API and how to troubleshoot them.

-## Troubleshooting scenarios

-### Invalid data format

-**Issue description**

-* You're getting the error message 'Invalid Data Format" with HTTP 400 (Bad Request) response code.

-**Probable causes**

-1. You're sending a valid bulk request as per the provisioning [/bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API specs, but you have not set the HTTP Request Header 'Content-Type' to `application/scim+json`.

-2. You're sending a bulk request that doesn't comply to the provisioning [/bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API specs.

-**Resolution:**

-1. Ensure the HTTP Request has the `Content-Type` header set to the value ```application/scim+json```.

-1. Ensure that the bulk request payload complies to the provisioning [/bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API specs.

-### There's nothing in the provisioning logs

-**Issue description**

-* You sent a request to the provisioning /bulkUpload API endpoint and you got HTTP 202 response code, but there's no data in the provisioning logs corresponding to your request.

-**Probable causes**

-1. Your API-driven provisioning app is paused.

-1. The provisioning service is yet to update the provisioning logs with the bulk request processing details.

-2. Your On-premises provisioning agent status is inactive (If you are running the [/API-driven inbound user provisioning to on-premises Active Directory](https://go.microsoft.com/fwlink/?linkid=2245182)).

-**Resolution:**

-1. Verify that your provisioning app is running. If it isn't running, select the menu option **Start provisioning** to process the data.

-2. Turn your On-premises provisioning agent status to active by restarting the On-premise agent.

-1. Expect 5 to 10-minute delay between processing the request and writing to the provisioning logs. If your API client is sending data to the provisioning /bulkUpload API endpoint, then introduce a time delay between the request invocation and provisioning logs query.

-### Forbidden 403 response code

-**Issue description**

-* You sent a request to the provisioning /bulkUpload API endpoint and you got HTTP 403 (Forbidden) response code.

-**Probable causes**

-* The Graph permission `SynchronizationData-User.Upload` is not assigned to your API client.

-**Resolution:**

-* Assign your API client the Graph permission `SynchronizationData-User.Upload` and retry the operation.

-### Unauthorized 401 response code

-**Issue description**

-* You sent a request to the provisioning /bulkUpload API endpoint and you got HTTP 401 (Unauthorized) response code. The error code displays "InvalidAuthenticationToken" with a message that the "Access token has expired or is not yet valid."

-**Probable causes**

-* Your access token has expired.

-**Resolution:**

-* Generate a new access token for your API client.

-### The job enters quarantine state

-**Issue description**

-* You just started the provisioning app and it is in quarantine state.

-**Probable causes**

-* You have not set the notification email prior to starting the job.

-**Resolution:**

-Go to the **Edit Provisioning** menu item. Under **Settings** there's a checkbox next to **Send an email notification when a failure occurs** and a field to input your **Notification Email**. Make sure to check the box, provide an email, and save the change. Click on **Restart provisioning** to get the job out of quarantine.

-### User creation - Invalid UPN

-**Issue description**

-There's a user provisioning failure. The provisioning logs displays the error code: ```AzureActiveDirectoryInvalidUserPrincipalName```.

-**Resolution:**

-1. Got to the **Edit Attribute Mappings** page.

-2. Select the ```UserPrincipalName``` mapping and update it to use the ```RandomString``` function.

-3. Copy and paste this expression into the expression box:

-```Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())```

-This expression fixes the issue by appending a random number to the UPN value accepted by Microsoft Entra ID.

-### User creation failed - Invalid domain

-**Issue description**

-There's a user provisioning failure. The provisioning logs displays an error message that states ```domain does not exist```.

-**Resolution:**

-1. Go to the **Edit Attribute Mappings** page.

-2. Select the ```UserPrincipalName``` mapping and copy and paste this expression into the expression input box:

-```Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())```

-This expression fixes the issue by appending a default domain to the UPN value accepted by Microsoft Entra ID.

-## Next steps

-* [Learn more about API-driven inbound provisioning](inbound-provisioning-api-concepts.md)

-description: Learn how to implement API-driven inbound provisioning with Azure Logic Apps.

-# API-driven inbound provisioning with Azure Logic Apps (Public preview)

-This tutorial describes how to use Azure Logic Apps workflow to implement Microsoft Entra ID [API-driven inbound provisioning](inbound-provisioning-api-concepts.md). Using the steps in this tutorial, you can convert a CSV file containing HR data into a bulk request payload and send it to the Microsoft Entra provisioning [/bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API endpoint. The article also provides guidance on how the same integration pattern can be used with any system of record.

-## Integration scenario

-### Business requirement

-Your system of record periodically generates CSV file exports containing worker data. You want to implement an integration that reads data from the CSV file and automatically provisions user accounts in your target directory (on-premises Active Directory for hybrid users and Microsoft Entra ID for cloud-only users).

-### Implementation requirement

-From an implementation perspective:

-* You want to use an Azure Logic Apps workflow to read data from the CSV file exports available in an Azure File Share and send it to the inbound provisioning API endpoint.

-* In your Azure Logic Apps workflow, you don't want to implement the complex logic of comparing identity data between your system of record and target directory.

-* You want to use Microsoft Entra provisioning service to apply your IT managed provisioning rules to automatically create/update/enable/disable accounts in the target directory (on-premises Active Directory or Microsoft Entra ID).

-### Integration scenario variations

-While this tutorial uses a CSV file as a system of record, you can customize the sample Azure Logic Apps workflow to read data from any system of record. Azure Logic Apps provides a wide range of [built-in connectors](/azure/logic-apps/connectors/built-in/reference/) and [managed connectors](/connectors/connector-reference/connector-reference-logicapps-connectors) with pre-built triggers and actions that you can use in your integration workflow.

-Here's a list of enterprise integration scenario variations, where API-driven inbound provisioning can be implemented with a Logic Apps workflow.

-|# |System of record |Integration guidance on using Logic Apps to read source data |

-||||

-| 1 | Files stored on SFTP server | Use either the [built-in SFTP connector](/azure/logic-apps/connectors/built-in/reference/sftp/) or [managed SFTP SSH connector](/azure/connectors/connectors-sftp-ssh) to read data from files stored on the SFTP server. |

-| 2 | Database table | If you're using an Azure SQL server or on-premises SQL Server, use the [SQL Server](/azure/connectors/connectors-create-api-sqlazure) connector to read your table data. <br> If you're using an Oracle database, use the [Oracle database](/azure/connectors/connectors-create-api-oracledatabase) connector to read your table data. |

-| 3 | On-premises and cloud-hosted SAP S/4 HANA or <br> Classic on-premises SAP systems, such as R/3 and ECC | Use the [SAP connector](/azure/logic-apps/logic-apps-using-sap-connector) to retrieve identity data from your SAP system. For examples on how to configure this connector, refer to [common SAP integration scenarios](/azure/logic-apps/sap-create-example-scenario-workflows) using Azure Logic Apps and the SAP connector. |

-| 4 | IBM MQ | Use the [IBM MQ connector](/azure/connectors/connectors-create-api-mq) to receive provisioning messages from the queue. |

-| 5 | Dynamics 365 Human Resources | Use the [Dataverse connector](/azure/connectors/connect-common-data-service) to read data from [Dataverse tables](/dynamics365/human-resources/hr-developer-entities) used by Microsoft Dynamics 365 Human Resources. |

-| 6 | Any system that exposes REST APIs | If you don't find a connector for your system of record in the Logic Apps connector library, You can create your own [custom connector](/azure/logic-apps/logic-apps-create-api-app) to read data from your system of record. |

-After reading the source data, apply your pre-processing rules and convert the output from your system of record into a bulk request that can be sent to the Microsoft Entra provisioning [bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API endpoint.

-> [!IMPORTANT]

-> If you'd like to share your API-driven inbound provisioning + Logic Apps integration workflow with the community, create a [Logic app template](/azure/logic-apps/logic-apps-create-azure-resource-manager-templates), document steps on how to use it and submit a pull request for inclusion in the GitHub repository [`entra-id-inbound-provisioning`](https://github.com/AzureAD/entra-id-inbound-provisioning).

-## How to use this tutorial

-The Logic Apps deployment template published in the [Microsoft Entra inbound provisioning GitHub repository](https://github.com/AzureAD/entra-id-inbound-provisioning/tree/main/LogicApps/CSV2SCIMBulkUpload) automates several tasks. It also has logic for handling large CSV files and chunking the bulk request to send 50 records in each request. Here's how you can test it and customize it per your integration requirements.

-> [!NOTE]

-> The sample Azure Logic Apps workflow is provided "as-is" for implementation reference. If you have questions related to it or if you'd like to enhance it, please use the [GitHub project repository](https://github.com/AzureAD/entra-id-inbound-provisioning).

-|# | Automation task | Implementation guidance | Advanced customization |

-|||||

-|1 | Read worker data from the CSV file. | The Logic Apps workflow uses an Azure Function to read the CSV file stored in an Azure File Share. The Azure Function converts CSV data into JSON format. If your CSV file format is different, update the workflow step "Parse JSON" and "Construct SCIMUser". | If your system of record is different, check guidance provided in the section [Integration scenario variations](#integration-scenario-variations) on how to customize the Logic Apps workflow by using an appropriate connector. |

-|2 | Pre-process and convert data to SCIM format. | By default, the Logic Apps workflow converts each record in the CSV file to a SCIM Core User + Enterprise User representation. If you plan to use custom SCIM schema extensions, update the step "Construct SCIMUser" to include your custom SCIM schema extensions. | If you want to run C# code for advanced formatting and data validation, use [custom Azure Functions](/azure/logic-apps/logic-apps-azure-functions).|

-|3 | Use the right authentication method | You can either [use a service principal](inbound-provisioning-api-grant-access.md#configure-a-service-principal) or [use managed identity](inbound-provisioning-api-grant-access.md#configure-a-managed-identity) to access the inbound provisioning API. Update the step "Send SCIMBulkPayload to API endpoint" with the right authentication method. | - |

-|4 | Provision accounts in on-premises Active Directory or Microsoft Entra ID. | Configure [API-driven inbound provisioning app](inbound-provisioning-api-configure-app.md). This generates a unique [/bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API endpoint. Update the step "Send SCIMBulkPayload to API endpoint" to use the right bulkUpload API endpoint. | If you plan to use bulk request with custom SCIM schema, then extend the provisioning app schema to include your custom SCIM schema attributes. |

-|5 | Scan the provisioning logs and retry provisioning for failed records. | This automation is not yet implemented in the sample Logic Apps workflow. To implement it, refer to the [provisioning logs Graph API](/graph/api/resources/provisioningobjectsummary). | - |

-|6 | Deploy your Logic Apps based automation to production. | Once you have verified your API-driven provisioning flow and customized the Logic Apps workflow to meet your requirements, deploy the automation in your environment. | - |

-## Step 1: Create an Azure Storage account to host the CSV file

-The steps documented in this section are optional. If you already have an existing storage account or would like to read the CSV file from another source like SharePoint site or Blob storage, update the Logic App to use your connector of choice.

-1. Sign in to the [Azure portal](https://portal.azure.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Search for "Storage accounts" and create a new storage account.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/storage-accounts.png" alt-text="Screenshot of creating new storage account." lightbox="media/inbound-provisioning-api-logic-apps/storage-accounts.png":::

-1. Assign a resource group and give it a name.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/assign-resource-group.png" alt-text="Screenshot of resource group assignment." lightbox="media/inbound-provisioning-api-logic-apps/assign-resource-group.png":::

-1. After the storage account is created, go to the resource.

-1. Click on "File share" menu option and create a new file share.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/create-new-file-share.png" alt-text="Screenshot of creating new file share." lightbox="media/inbound-provisioning-api-logic-apps/create-new-file-share.png":::

-1. Verify that the file share creation is successful.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/verify-file-share-creation.png" alt-text="Screenshot of file share created." lightbox="media/inbound-provisioning-api-logic-apps/verify-file-share-creation.png":::

-1. Upload a sample CSV file to the file share using the upload option.

-1. Here is a screenshot of the columns in the CSV file.

- :::image type="content" border="true" source="./media/inbound-provisioning-api-powershell/columns.png" alt-text="Screenshot of columns in Excel." lightbox="./media/inbound-provisioning-api-powershell/columns.png":::

-## Step 2: Configure Azure Function CSV2JSON converter

-1. In the browser associated with your Azure portal, open the GitHub repository URL - https://github.com/joelbyford/CSVtoJSONcore.

-1. Click on the link "Deploy to Azure" to deploy this Azure Function to your Azure tenant.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/deploy-azure-function.png" alt-text="Screenshot of deploying Azure Function." lightbox="media/inbound-provisioning-api-logic-apps/deploy-azure-function.png":::

-1. Specify the resource group under which to deploy this Azure function.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/azure-function-resource-group.png" alt-text="Screenshot of configuring Azure Function resource group." lightbox="media/inbound-provisioning-api-logic-apps/azure-function-resource-group.png":::

- If you get the error "[This region has quota of 0 instances](/answers/questions/751909/azure-function-app-region-has-quota-of-0-instances)", try selecting a different region.

-1. Ensure that the deployment of the Azure Function as an App Service is successful.

-1. Go to the resource group and open the WebApp configuration. Ensure it is in "Running" state. Copy the default domain name associated with the Web App.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/web-app-domain-name.png" alt-text="Screenshot of Azure Function Web App domain name." lightbox="media/inbound-provisioning-api-logic-apps/web-app-domain-name.png":::

-1. Open Postman client to test if the CSVtoJSON endpoint works as expected. Paste the domain name copied from the previous step. Use Content-Type of "text/csv" and post a sample CSV file in the request body to the endpoint: `https://[your-domain-name]/csvtojson`

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/postman-call-to-azure-function.png" alt-text="Screenshot of Postman client calling the Azure Function." lightbox="media/inbound-provisioning-api-logic-apps/postman-call-to-azure-function.png":::

-1. If the Azure Function deployment is successful, then in the response you'll get a JSON version of the CSV file with status 200 OK.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/azure-function-response.png" alt-text="Screenshot of Azure Function response." lightbox="media/inbound-provisioning-api-logic-apps/azure-function-response.png":::

-1. To allow Logic Apps to invoke this Azure Function, in the CORS setting for the WebApp enter asterisk (*) and "Save" the configuration.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/azure-function-cors-setting.png" alt-text="Screenshot of Azure Function CORS setting." lightbox="media/inbound-provisioning-api-logic-apps/azure-function-cors-setting.png":::

-## Step 3: Configure API-driven inbound user provisioning

-* Configure [API-driven inbound user provisioning](inbound-provisioning-api-configure-app.md).

-## Step 4: Configure your Azure Logic Apps workflow

-1. Click on the button below to deploy the Azure Resource Manager template for the CSV2SCIMBulkUpload Logic Apps workflow.

- [](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzureAD%2Fentra-id-inbound-provisioning%2Fmain%2FLogicApps%2FCSV2SCIMBulkUpload%2Fcsv2scimbulkupload-template.json)

-1. Under instance details, update the highlighted items, copy-pasting values from the previous steps.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/logic-apps-instance-details.png" alt-text="Screenshot of Azure Logic Apps instance details." lightbox="media/inbound-provisioning-api-logic-apps/logic-apps-instance-details.png":::

-1. For the `Azurefile_access Key` parameter, open your Azure file storage account and copy the access key present under "Security and Networking".

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/azure-file-access-keys.png" alt-text="Screenshot of Azure File access keys." lightbox="media/inbound-provisioning-api-logic-apps/azure-file-access-keys.png":::

-1. Click on "Review and Create" option to start the deployment.

-1. Once the deployment is complete, you'll see the following message.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/logic-apps-deployment-complete.png" alt-text="Screenshot of Azure Logic Apps deployment complete." lightbox="media/inbound-provisioning-api-logic-apps/logic-apps-deployment-complete.png":::

-## Step 5: Configure system assigned managed identity

-1. Visit the Settings -> Identity blade of your Logic Apps workflow.

-1. Enable **System assigned managed identity**.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/enable-managed-identity.png" alt-text="Screenshot of enabling managed identity." lightbox="media/inbound-provisioning-api-logic-apps/enable-managed-identity.png":::

-1. You'll get a prompt to confirm the use of the managed identity. Click on **Yes**.

-1. Grant the managed identity [permissions to perform bulk upload](inbound-provisioning-api-grant-access.md#configure-a-managed-identity).

-## Step 6: Review and adjust the workflow steps

-1. Open the Logic App in the designer view.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/designer-view.png" alt-text="Screenshot of Azure Logic Apps designer view." lightbox="media/inbound-provisioning-api-logic-apps/designer-view.png":::

-1. Review the configuration of each step in the workflow to make sure it is correct.

-1. Open the "Get file content using path" step and correct it to browse to the Azure File Storage in your tenant.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/get-file-content.png" alt-text="Screenshot of get file content." lightbox="media/inbound-provisioning-api-logic-apps/get-file-content.png":::

-1. Update the connection if required.

-1. Make sure your "Convert CSV to JSON" step is pointing to the right Azure Function Web App instance.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/convert-file-format.png" alt-text="Screenshot of Azure Function call invocation to convert from CSV to JSON." lightbox="media/inbound-provisioning-api-logic-apps/convert-file-format.png":::

-1. If your CSV file content / headers is different, then update the "Parse JSON" step with the JSON output that you can retrieve from your API call to the Azure Function. Use Postman output from Step 2.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/parse-json-step.png" alt-text="Screenshot of Parse JSON step." lightbox="media/inbound-provisioning-api-logic-apps/parse-json-step.png":::

-1. In the step "Construct SCIMUser", ensure that the CSV fields map correctly to the SCIM attributes that will be used for processing.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/construct-scim-user.png" alt-text="Screenshot of Construct SCIM user step." lightbox="media/inbound-provisioning-api-logic-apps/construct-scim-user.png":::

-1. In the step "Send SCIMBulkPayload to API endpoint" ensure you are using the right API endpoint and authentication mechanism.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/invoke-bulk-upload-api.png" alt-text="Screenshot of invoking bulk upload API with managed identity." lightbox="media/inbound-provisioning-api-logic-apps/invoke-bulk-upload-api.png":::

-## Step 7: Run trigger and test your Logic Apps workflow

-1. In the "Generally Available" version of the Logic Apps designer, click on Run Trigger to manually execute the workflow.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/run-logic-app.png" alt-text="Screenshot of running the Logic App." lightbox="media/inbound-provisioning-api-logic-apps/run-logic-app.png":::

-1. After the execution is complete, review what action Logic Apps performed in each iteration.

-1. In the final iteration, you should see the Logic Apps upload data to the inbound provisioning API endpoint. Look for `202 Accept` status code. You can copy-paste and verify the bulk upload request.

- :::image type="content" source="media/inbound-provisioning-api-logic-apps/execution-results.png" alt-text="Screenshot of the Logic Apps execution result." lightbox="media/inbound-provisioning-api-logic-apps/execution-results.png":::

-## Next steps

-description: Learn how to get started quickly with API-driven inbound provisioning using Postman

-# Quickstart API-driven inbound provisioning with Postman (Public preview)

-This tutorial describes how you can quickly test [API-driven inbound provisioning](inbound-provisioning-api-concepts.md) with Postman.

-## Pre-requisites

-* You have configured [API-driven inbound provisioning app](inbound-provisioning-api-configure-app.md).

-* You have [configured a service principal and it has access](inbound-provisioning-api-grant-access.md) to the inbound provisioning API. Make note of the `TenantId`, `ClientId` and `ClientSecret` of your service principal app for use in this tutorial.

-### Upload user data to the inbound provisioning API

-In this step, you'll configure the Postman app and invoke the API using the configured service account.

-1. Download and install the [Postman app](https://www.postman.com/downloads/).

-1. Open the Postman desktop app.

-1. From the **Workspaces** menu, select **Create Workspace** to create a new Workspace called **Microsoft Entra provisioning API**.

-1. Download the following Postman collections and save it in your local directory.

- - [Microsoft Entra Inbound Provisioning.postman_collection.json](https://github.com/AzureAD/entra-id-inbound-provisioning/blob/main/Postman/Entra%20ID%20Inbound%20Provisioning.postman_collection.json) (Request collection)

- - [Test-API2AAD.postman_environment.json](https://github.com/AzureAD/entra-id-inbound-provisioning/blob/main/Postman/Test-API2AAD.postman_environment.json) (Environment collection for API-driven provisioning to Microsoft Entra ID)-

- - [Test-API2AD.postman_environment.json](https://github.com/AzureAD/entra-id-inbound-provisioning/blob/main/Postman/Test-API2AD.postman_environment.json) (Environment collection for API-driven provisioning to on-premises AD)

-1. Use the **Import** option in Postman to import both of these files into your Workspace.

- :::image type="content" source="media/inbound-provisioning-api-postman/postman-import-elements.png" alt-text="Screenshot of Postman Import elements." lightbox="media/inbound-provisioning-api-postman/postman-import-elements.png":::

-1. Click the **Environments** menu and open the **Test-API2AAD** environment.

-1. Retrieve the values of **client_id**, **client_secret**, and **token_endpoint** from your registered app.

- :::image type="content" source="media/inbound-provisioning-api-postman/retrieve-authentication-details.png" alt-text="Screenshot of registered app." lightbox="media/inbound-provisioning-api-postman/retrieve-authentication-details.png":::

-1. Paste the values in the table for each variable under the column **Initial value** and **Current value**.

- :::image type="content" source="media/inbound-provisioning-api-postman/postman-authentication-variables.png" alt-text="Screenshot of authentication variables" lightbox="media/inbound-provisioning-api-postman/postman-authentication-variables.png":::

-1. Open your provisioning app landing page and copy-paste the value of **Job ID** for the `jobId` variable and the value of **Provisioning API endpoint** for the `bulk_upload_endpoint` variable

- :::image type="content" source="media/inbound-provisioning-api-configure-app/provisioning-api-endpoint.png" alt-text="Screenshot of Provisioning API endpoint." lightbox="media/inbound-provisioning-api-configure-app/provisioning-api-endpoint.png":::

-1. Leave the value of **ms_graph_resource_id** unchanged and save the environment collection. Make sure that both **Initial value** and **Current value** columns are populated.

-1. Next, open the collection **Microsoft Entra Inbound Provisioning**.

-1. From the **Environment** dropdown, select **Test-API2AAD**.

-1. Select the **Authorization** tab associated with the collection.

-1. Make sure that authorization is configured to use OAuth settings.

- :::image type="content" source="media/inbound-provisioning-api-postman/provisioning-oauth-configuration.png" alt-text="Screenshot of Provisioning OAuth configuration." lightbox="media/inbound-provisioning-api-postman/provisioning-oauth-configuration.png":::

-1. The **Advanced options** section should show the following configuration:

- :::image type="content" source="media/inbound-provisioning-api-postman/provisioning-advanced-options.png" alt-text="Screenshot of Provisioning Advanced options." lightbox="media/inbound-provisioning-api-postman/provisioning-advanced-options.png":::

-1. Click on **Get New Access Token** to initiate the process to procure an access token.

-1. Select the option **Use Token** to use the access token with all requests in this collection.

- >[!NOTE]

- >The OAuth access token generated using `client_credentials` grant type is valid for one hour. You can decode the token using [https://jwt.ms](https://jwt.ms) and check when it expires. Requests fail after the token expires. If your access token has expired, click **Get New Access Token** in Postman to get a new access token.

- The token is automatically copied into the **Current token** section of the Authorization tab. You can now use the token to make API calls. Let's start with the first call in this collection.

-1. Open the request **SCIM bulk request upload**.

-1. Under the **Authorization tab**, make sure that type is set to **Inherit auth from parent**.

-1. Change to the **Request body** tab, to view and edit the sample SCIM bulk request. When you're done editing, click **Send**.

-If the API invocation is successful, you see the message `202 Accepted.` Under Headers, the **Location** attribute points to the provisioning logs API endpoint.

-## Verify processing of bulk request payload

-You can verify the processing either from the Microsoft Entra admin center or using Postman.

-### Verify processing from Microsoft Entra admin center

-1. Log in to [Microsoft Entra admin center](https://entra.microsoft.com) with at least [Application Administrator](https://go.microsoft.com/fwlink/?linkid=2247823) level credentials.

-1. Browse to **Microsoft Entra ID -> Applications -> Enterprise applications**.

-1. Under all applications, use the search filter text box to find and open your API-driven provisioning application.

-1. Open the Provisioning blade. The landing page displays the status of the last run.

-1. Click on **View provisioning logs** to open the provisioning logs blade. Alternatively, you can click on the menu option **Monitor -> Provisioning logs**.

- [](media/inbound-provisioning-api-curl-tutorial/access-provisioning-logs.png#lightbox)

-1. Click on any record in the provisioning logs to view additional processing details.

-1. The provisioning log details screen displays all the steps executed for a specific user.

- [](media/inbound-provisioning-api-curl-tutorial/provisioning-log-details.png#lightbox)

- * Under the **Import from API** step, see details of user data extracted from the bulk request.

- * The **Match user** step shows details of any user match based on the matching identifier. If a user match happens, then the provisioning service performs an update operation. If there is no user match, then the provisioning service performs a create operation.

- * The **Determine if User is in scope** step shows details of scoping filter evaluation. By default, all users are processed. If you have set a scoping filter (example, process only users belonging to the Sales department), the evaluation details of the scoping filter displays in this step.

- * The **Provision User** step calls out the final processing step and changes applied to the user account.

- * Use the **Modified properties** tab to view attribute updates.

-### Verify processing using provisioning logs API in Postman

-This section shows how you can query provisioning logs in Postman using the same service account (service principal) that you configured.

-1. Open the workspace **Microsoft Entra provisioning API** in your Postman desktop app.

-2. The collection **Microsoft Entra Inbound Provisioning** contains three sample requests that enable you to query the provisioning logs.

-3. You can open any of these predefined requests.

-4. If you don't have a valid access token or you're not sure if the access token is still valid, go to the collection object's root Authorization tab and use the option **Get New Access Token** to get a fresh token.

-5. Click **Send** to get provisioning log records.

-Upon successful execution, you'll get a `200 HTTP` response from the server along with the provisioning log records.

-## Appendix

-### Bulk request with SCIM Enterprise User Schema

-The bulk request shown below uses the SCIM standard Core User and Enterprise User schema.

-**Request body**

-```http

-{

- "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],

- "Operations": [

- {

- "method": "POST",

- "bulkId": "897401c2-2de4-4b87-a97f-c02de3bcfc61",

- "path": "/Users",

- "data": {

- "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],

- "externalId": "701984",

- "userName": "bjensen@example.com",

- "name": {

- "formatted": "Ms. Barbara J Jensen, III",

- "familyName": "Jensen",

- "givenName": "Barbara",

- "middleName": "Jane",

- "honorificPrefix": "Ms.",

- "honorificSuffix": "III"

- },

- "displayName": "Babs Jensen",

- "nickName": "Babs",

- "emails": [

- {

- "value": "bjensen@example.com",

- "type": "work",

- "primary": true

- }

- ],

- "addresses": [

- {

- "type": "work",

- "streetAddress": "100 Universal City Plaza",

- "locality": "Hollywood",

- "region": "CA",

- "postalCode": "91608",

- "country": "USA",

- "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",

- "primary": true

- }

- ],

- "phoneNumbers": [

- {

- "value": "555-555-5555",

- "type": "work"

- }

- ],

- "userType": "Employee",

- "title": "Tour Guide",

- "preferredLanguage": "en-US",

- "locale": "en-US",

- "timezone": "America/Los_Angeles",

- "active":true,

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

- "employeeNumber": "701984",

- "costCenter": "4130",

- "organization": "Universal Studios",

- "division": "Theme Park",

- "department": "Tour Operations",

- "manager": {

- "value": "89607",

- "displayName": "John Smith"

- }

- }

- }

- },

- {

- "method": "POST",

- "bulkId": "897401c2-2de4-4b87-a97f-c02de3bcfc61",

- "path": "/Users",

- "data": {

- "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],

- "externalId": "701985",

- "userName": "Kjensen@example.com",

- "name": {

- "formatted": "Ms. Kathy J Jensen, III",

- "familyName": "Jensen",

- "givenName": "Kathy",

- "middleName": "Jane",

- "honorificPrefix": "Ms.",

- "honorificSuffix": "III"

- },

- "displayName": "Kathy Jensen",

- "nickName": "Kathy",

- "emails": [

- {

- "value": "kjensen@example.com",

- "type": "work",

- "primary": true

- }

- ],

- "addresses": [

- {

- "type": "work",

- "streetAddress": "100 Oracle City Plaza",

- "locality": "Hollywood",

- "region": "CA",

- "postalCode": "91618",

- "country": "USA",

- "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",

- "primary": true

- }

- ],

- "phoneNumbers": [

- {

- "value": "555-555-5545",

- "type": "work"

- }

- ],

- "userType": "Employee",

- "title": "Tour Lead",

- "preferredLanguage": "en-US",

- "locale": "en-US",

- "timezone": "America/Los_Angeles",

- "active":true,

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

- "employeeNumber": "701985",

- "costCenter": "4130",

- "organization": "Universal Studios",

- "division": "Theme Park",

- "department": "Tour Operations",

- "manager": {

- "value": "701984",

- "displayName": "Barbara Jensen"

- }

- }

- }

- }

-],

- "failOnErrors": null

-}

-```

-## Next steps

-description: Learn how to implement API-driven inbound provisioning with a PowerShell script.

-# API-driven inbound provisioning with PowerShell script (Public preview)

-This tutorial describes how to use a PowerShell script to implement Microsoft Entra ID [API-driven inbound provisioning](inbound-provisioning-api-concepts.md). Using the steps in this tutorial, you can convert a CSV file containing HR data into a bulk request payload and send it to the Microsoft Entra provisioning [/bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API endpoint. The article also provides guidance on how the same integration pattern can be used with any system of record.

-## Integration scenario

-### Business requirement

-Your system of record periodically generates CSV file exports containing worker data. You want to implement an integration that reads data from the CSV file and automatically provisions user accounts in your target directory (on-premises Active Directory for hybrid users and Microsoft Entra ID for cloud-only users).

-### Implementation requirement

-From an implementation perspective:

-* You want to use an unattended PowerShell script to read data from the CSV file exports and send it to the inbound provisioning API endpoint.

-* In your PowerShell script, you don't want to implement the complex logic of comparing identity data between your system of record and target directory.

-* You want to use Microsoft Entra provisioning service to apply your IT managed provisioning rules to automatically create/update/enable/disable accounts in the target directory (on-premises Active Directory or Microsoft Entra ID).

-### Integration scenario variations

-While this tutorial uses a CSV file as a system of record, you can customize the sample PowerShell script to read data from any system of record. Here's a list of enterprise integration scenario variations, where API-driven inbound provisioning can be implemented with a PowerShell script.

-|# |System of record |Integration guidance on using PowerShell to read source data |

-||||

-|1 | Database table | If you're using an Azure SQL database or an on-premises SQL Server, you can use the [Read-SqlTableData](/powershell/module/sqlserver/read-sqltabledata) cmdlet to read data stored in a table of a SQL database. You can use the [Invoke-SqlCmd](/powershell/module/sqlserver/invoke-sqlcmd) cmdlet to run Transact-SQL or XQuery scripts. <br> If you're using an Oracle / MySQL / Postgres database, you can find a PowerShell module either published by the vendor or available in the [PowerShell Gallery](https://www.powershellgallery.com/). Use the module to read data from your database table. |

-|2 | LDAP server | Use the `System.DirectoryServices.Protocols` .NET API or one of the LDAP modules available in the [PowerShell Gallery](https://www.powershellgallery.com/packages?q=ldap) to query your LDAP server. Understand the LDAP schema and hierarchy to retrieve user data from the LDAP server. |

-|3 | Any system that exposes REST APIs | To read data from a REST API endpoint using PowerShell, you can use the [Invoke-RestMethod](/powershell/module/microsoft.powershell.utility/invoke-restmethod) cmdlet from the `Microsoft.PowerShell.Utility` module. Check the documentation of your REST API and find out what parameters and headers it expects, what format it returns, and what authentication method it uses. You can then adjust your `Invoke-RestMethod` command accordingly. |

-|4 | Any system that exposes SOAP APIs | To read data from a SOAP API endpoint using PowerShell, you can use the [New-WebServiceProxy](/powershell/module/microsoft.powershell.management/new-webserviceproxy) cmdlet from the `Microsoft.PowerShell.Management` module. Check the documentation of your SOAP API and find out what parameters and headers it expects, what format it returns, and what authentication method it uses. You can then adjust your `New-WebServiceProxy` command accordingly. |

-After reading the source data, apply your pre-processing rules and convert the output from your system of record into a bulk request that can be sent to the Microsoft Entra provisioning [bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API endpoint.

-> [!IMPORTANT]

-> If you'd like to share your PowerShell integration script with the community, publish it on [PowerShell Gallery](https://www.powershellgallery.com/) and notify us on the GitHub repository [`entra-id-inbound-provisioning`](https://github.com/AzureAD/entra-id-inbound-provisioning), so we can add a reference it.

-## How to use this tutorial

-The PowerShell sample script published in the [Microsoft Entra inbound provisioning GitHub repository](https://github.com/AzureAD/entra-id-inbound-provisioning/tree/main/PowerShell/CSV2SCIM) automates several tasks. It has logic for handling large CSV files and chunking the bulk request to send 50 records in each request. Here's how you can test it and customize it per your integration requirements.

-> [!NOTE]

-> The sample PowerShell script is provided "as-is" for implementation reference. If you have questions related to the script or if you'd like to enhance it, please use the [GitHub project repository](https://github.com/AzureAD/entra-id-inbound-provisioning).

-|# | Automation task | Implementation guidance | Advanced customization |

-||||-|

-|1 | Read worker data from the CSV file. | [Download the PowerShell script](#download-the-powershell-script). It has out-of-the-box logic to read data from any CSV file. Refer to [CSV2SCIM PowerShell usage details](#csv2scim-powershell-usage-details) to get familiar with the different execution modes of this script. | If your system of record is different, check guidance provided in the section [Integration scenario variations](#integration-scenario-variations) on how you can customize the PowerShell script. |

-|2 | Pre-process and convert data to SCIM format. | By default, the PowerShell script converts each record in the CSV file to a SCIM Core User + Enterprise User representation. Follow the steps in the section [Generate bulk request payload with standard schema](#generate-bulk-request-payload-with-standard-schema) to get familiar with this process. | If your CSV file has different fields, tweak the [AttributeMapping.psd file](#attributemappingpsd-file) to generate a valid SCIM user. You can also [generate bulk request with custom SCIM schema](#generate-bulk-request-with-custom-scim-schema). Update the PowerShell script to include any custom CSV data validation logic.|

-|3 | Use a certificate for authentication to Microsoft Entra ID. | [Create a service principal that can access](inbound-provisioning-api-grant-access.md) the inbound provisioning API. Refer to steps in the section [Configure client certificate for service principal authentication](#configure-client-certificate-for-service-principal-authentication) to learn how to use client certificate for authentication. | If you'd like to use managed identity instead of a service principal for authentication, then review the use of `Connect-MgGraph` in the sample script and update it to use [managed identities](/powershell/microsoftgraph/authentication-commands#using-managed-identity). |

-|4 | Provision accounts in on-premises Active Directory or Microsoft Entra ID. | Configure [API-driven inbound provisioning app](inbound-provisioning-api-configure-app.md). This generates a unique [/bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API endpoint. Refer to the steps in the section [Generate and upload bulk request payload as admin user](#generate-and-upload-bulk-request-payload-as-admin-user) to learn how to upload data to this endpoint. Validate the attribute flow and customize the attribute mappings per your integration requirements. To run the script using a service principal with certificate-based authentication, refer to the steps in the section [Upload bulk request payload using client certificate authentication](#upload-bulk-request-payload-using-client-certificate-authentication) | If you plan to [use bulk request with custom SCIM schema](#generate-bulk-request-with-custom-scim-schema), then [extend the provisioning app schema](#extending-provisioning-job-schema) to include your custom SCIM schema elements.|

-|5 | Scan the provisioning logs and retry provisioning for failed records. | Refer to the steps in the section [Get provisioning logs of the latest sync cycles](#get-provisioning-logs-of-the-latest-sync-cycles) to learn how to fetch and analyze provisioning log data. Identify failed user records and include them in the next upload cycle. | - |

-|6 | Deploy your PowerShell based automation to production. | Once you have verified your API-driven provisioning flow and customized the PowerShell script to meet your requirements, you can deploy the automation as a [PowerShell Workflow runbook in Azure Automation](/azure/automation/learn/automation-tutorial-runbook-textual) or as a server process [scheduled to run on a Windows server](/troubleshoot/windows-server/system-management-components/schedule-server-process). | - |

-## Download the PowerShell script

-1. Access the GitHub repository [`entra-id-inbound-provisioning`](https://github.com/AzureAD/entra-id-inbound-provisioning).

-1. Use the **Code** -> **Clone** or **Code** -> **Download ZIP** option to copy contents of this repository into your local folder.

-1. Navigate to the folder **PowerShell/CSV2SCIM**. It has the following directory structure:

- - src

- - CSV2SCIM.ps1 (main script)

- - ScimSchemaRepresentations (folder containing standard SCIM schema definitions for validating AttributeMapping.psd1 files)

- - EnterpriseUser.json, Group.json, Schema.json, User.json

- - Samples

- - AttributeMapping.psd1 (sample mapping of columns in CSV file to standard SCIM attributes)

- - csv-with-2-records.csv (sample CSV file with two records)

- - csv-with-1000-records.csv (sample CSV file with 1000 records)

- - Test-ScriptCommands.ps1 (sample usage commands)

- - UseClientCertificate.ps1 (script to generate self-signed certificate and upload it as service principal credential for use in OAuth flow)

- - `Sample1` (folder with more examples of how CSV file columns can be mapped to SCIM standard attributes. If you get different CSV files for employees, contractors, interns, you can create a separate AttributeMapping.psd1 file for each entity.)

-1. Download and install the latest version of PowerShell.

-1. Run the command to enable execution of remote signed scripts:

- ```powershell

- set-executionpolicy remotesigned

- ```

-1. Install the following prerequisite modules:

- ```powershell

- Install-Module -Name Microsoft.Graph.Applications,Microsoft.Graph.Reports

- ```

-## Generate bulk request payload with standard schema

-This section explains how to generate a bulk request payload with standard SCIM Core User and Enterprise User attributes from a CSV file.

-To illustrate the procedure, let's use the CSV file `Samples/csv-with-2-records.csv`.

-1. Open the CSV file `Samples/csv-with-2-records.csv` in Notepad++ or Excel to check the columns present in the file.

- :::image type="content" border="true" source="./media/inbound-provisioning-api-powershell/columns.png" alt-text="Screenshot of columns in Excel." lightbox="./media/inbound-provisioning-api-powershell/columns.png":::

-1. In Notepad++ or a source code editor like Visual Studio Code, open the PowerShell data file `Samples/AttributeMapping.psd1` that enables mapping of CSV file columns to SCIM standard schema attributes. The file that's shipped out-of-the-box already has pre-configured mapping of CSV file columns to corresponding SCIM schema attributes.

- ```powershell

- @{

- externalId = 'WorkerID'

- name = @{

- familyName = 'LastName'

- givenName = 'FirstName'

- }

- active = { $_.'WorkerStatus' -eq 'Active' }

- userName = 'UserID'

- displayName = 'FullName'

- nickName = 'UserID'

- userType = 'WorkerType'

- title = 'JobTitle'

- addresses = @(

- @{

- type = { 'work' }

- streetAddress = 'StreetAddress'

- locality = 'City'

- postalCode = 'ZipCode'

- country = 'CountryCode'

- }

- )

- phoneNumbers = @(

- @{

- type = { 'work' }

- value = 'OfficePhone'

- }

- )

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" = @{

- employeeNumber = 'WorkerID'

- costCenter = 'CostCenter'

- organization = 'Company'

- division = 'Division'

- department = 'Department'

- manager = @{

- value = 'ManagerID'

- }

- }

- }

- ```

-1. Open PowerShell and change to the directory **CSV2SCIM\src**.

-1. Run the following command to initialize the `AttributeMapping` variable.

- ```powershell

- $AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'

- ```

-1. Run the following command to validate if the `AttributeMapping` file has valid SCIM schema attributes. This command returns **True** if the validation is successful.

- ```powershell

- .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping

- ```

-1. Let's say the `AttributeMapping` file has an invalid SCIM attribute called **userId**, then the `ValidateAttributeMapping` mode displays the following error.

- :::image type="content" border="true" source="./media/inbound-provisioning-api-powershell/mapping-error.png" alt-text="Screenshot of a mapping error." lightbox="./media/inbound-provisioning-api-powershell/mapping-error.png":::

-1. Once you verified that the `AttributeMapping` file is valid, run the following command to generate a bulk request in the file `BulkRequestPayload.json` that includes the two records present in the CSV file.

- ```powershell

- .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping > BulkRequestPayload.json

- ```

-1. You can open the contents of the file `BulkRequestPayload.json` to verify if the SCIM attributes are set as per mapping defined in the file `AttributeMapping.psd1`.

-1. You can post the file generated above as-is to the [/bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API endpoint associated with your provisioning app using Graph Explorer or Postman or cURL. Reference:

- - [Quick start with Graph Explorer](inbound-provisioning-api-graph-explorer.md)

- - [Quick start with Postman](inbound-provisioning-api-postman.md)

- - [Quick start with cURL](inbound-provisioning-api-curl-tutorial.md)

-1. To directly upload the generated payload to the API endpoint using the same PowerShell script refer to the next section.

-## Generate and upload bulk request payload as admin user

-This section explains how to send the generated bulk request payload to your inbound provisioning API endpoint.

-1. Log in to your [Microsoft Entra admin center](https://entra.microsoft.com) as at least an [Application Administrator](https://go.microsoft.com/fwlink/?linkid=2247823).

-1. Browse to **Provisioning App** > **Properties** > **Object ID** and copy the `ServicePrincipalId` associated with your provisioning app.

- :::image type="content" border="true" source="./media/inbound-provisioning-api-powershell/object-id.png" alt-text="Screenshot of the Object ID." lightbox="./media/inbound-provisioning-api-powershell/object-id.png":::

-1. As user with Global Administrator role, run the following command by providing the correct values for `ServicePrincipalId` and `TenantId`. It will prompt you for authentication if an authenticated session doesn't already exist for this tenant. Provide your consent to permissions prompted during authentication.

- ```powershell

- .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com"

- ```

-1. Visit the **Provisioning logs** blade of your provisioning app to verify the processing of the above request.

-## Configure client certificate for service principal authentication

-> [!NOTE]

-> The instructions here show how to generate a self-signed certificate. Self-signed certificates are not trusted by default and they can be difficult to maintain. Also, they may use outdated hash and cipher suites that may not be strong. For better security, purchase a certificate signed by a well-known certificate authority.

-1. Run the following PowerShell script to generate a new self-signed certificate. You can skip this step if you have purchased a certificate signed by a well-known certificate authority.

- ```powershell

- $ClientCertificate = New-SelfSignedCertificate -Subject 'CN=CSV2SCIM' -KeyExportPolicy 'NonExportable' -CertStoreLocation Cert:\CurrentUser\My

- $ThumbPrint = $ClientCertificate.ThumbPrint

- ```

- The generated certificate is stored **Current User\Personal\Certificates**. You can view it using the **Control Panel** -> **Manage user certificates** option.

-1. To associate this certificate with a valid service principal, log in to your Microsoft Entra admin center as Application Administrator.

-1. Open [the service principal you configured](inbound-provisioning-api-grant-access.md#configure-a-service-principal) under **App Registrations**.

-1. Copy the **Object ID** from the **Overview** blade. Use the value to replace the string `<AppObjectId>`. Copy the **Application (client) Id**. We will use it later and it is referenced as `<AppClientId>`.

-1. Run the following command to upload your certificate to the registered service principal.

- ```powershell

- Connect-MgGraph -Scopes "Application.ReadWrite.All"

- Update-MgApplication -ApplicationId '<AppObjectId>' -KeyCredentials @{

- Type = "AsymmetricX509Cert"

- Usage = "Verify"

- Key = $ClientCertificate.RawData

- }

- ```

- You should see the certificate under the **Certificates & secrets** blade of your registered app.

- :::image type="content" source="media/inbound-provisioning-api-powershell/client-certificate.png" alt-text="Screenshot of client certificate." lightbox="media/inbound-provisioning-api-powershell/client-certificate.png":::

-1. Add the following two **Application** permission scopes to the service principal app: **Application.Read.All** and **Synchronization.Read.All**. These are required for the PowerShell script to look up the provisioning app by `ServicePrincipalId` and fetch the provisioning `JobId`.

-## Upload bulk request payload using client certificate authentication

-This section explains how to send the generated bulk request payload to your inbound provisioning API endpoint using a trusted client certificate.

-1. Open the API-driven provisioning app that you [configured](inbound-provisioning-api-configure-app.md). Copy the `ServicePrincipalId` associated with your provisioning app from **Provisioning App** > **Properties** > **Object ID**.

- :::image type="content" border="true" source="./media/inbound-provisioning-api-powershell/object-id.png" alt-text="Screenshot of the Object ID." lightbox="./media/inbound-provisioning-api-powershell/object-id.png":::

-1. Run the following command by providing the correct values for `ServicePrincipalId`, `ClientId` and `TenantId`.

- ```powershell

- $ClientCertificate = Get-ChildItem -Path cert:\CurrentUser\my\ | Where-Object {$_.Subject -eq "CN=CSV2SCIM"}

- $ThumbPrint = $ClientCertificate.ThumbPrint

- .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -TenantId "contoso.onmicrosoft.com" -ServicePrincipalId "<ProvisioningAppObjectId>" -ClientId "<AppClientId>" -ClientCertificate (Get-ChildItem Cert:\CurrentUser\My\$ThumbPrint)

- ```

-1. Visit the **Provisioning logs** blade of your provisioning app to verify the processing of the above request.

-## Generate bulk request with custom SCIM schema

-This section describes how to generate a bulk request with custom SCIM schema namespace consisting of fields in the CSV file.

-1. In Notepad++ or a source code editor like Visual Studio Code, open the PowerShell data file `Samples/AttributeMapping.psd1` that enables mapping of CSV file columns to SCIM standard schema attributes. The file that's shipped out-of-the-box already has pre-configured mapping of CSV file columns to corresponding SCIM schema attributes.

-1. Open PowerShell and change to the directory **CSV2SCIM\src**.

-1. Run the following command to initialize the `AttributeMapping` variable.

- ```powershell

- $AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'

- ```

-1. Run the following command to validate if the `AttributeMapping` file has valid SCIM schema attributes. This command returns **True** if the validation is successful.

- ```powershell

- .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping

- ```

-1. In addition to the SCIM Core User and Enterprise User attributes, to get a flat-list of all CSV fields under a custom SCIM schema namespace `urn:ietf:params:scim:schemas:extension:contoso:1.0:User`, run the following command.

- ```powershell

- .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User" > BulkRequestPayloadWithCustomNamespace.json

- ```

- The CSV fields will show up under the custom SCIM schema namespace.

- :::image type="content" source="media/inbound-provisioning-api-powershell/user-details-under-custom-schema.png" alt-text="Screenshot of user details under custom schema." lightbox="media/inbound-provisioning-api-powershell/user-details-under-custom-schema.png":::

-## Extending provisioning job schema

-Often the data file sent by HR teams contains more attributes that don't have a direct representation in the standard SCIM schema. To represent such attributes, we recommend creating a SCIM extension schema and adding attributes under this namespace.

-The CSV2SCIM script provides an execution mode called `UpdateSchema` which reads all columns in the CSV file, adds them under an extension schema namespace, and updates the provisioning app schema.

-> [!NOTE]

-> If the attribute extensions are already present in the provisioning app schema, then this mode only emits a warning that the attribute extension already exists. So, there is no issue running the CSV2SCIM script in the **UpdateSchema** mode if new fields are added to the CSV file and you want to add them as an extension.

-To illustrate the procedure, we'll use the CSV file ```Samples/csv-with-2-records.csv``` present in the **CSV2SCIM** folder.

-1. Open the CSV file ```Samples/csv-with-2-records.csv``` in a Notepad, Excel, or TextPad to check the columns present in the file.

- :::image type="content" border="true" source="./media/inbound-provisioning-api-powershell/check-columns.png" alt-text="Screenshot of how to check CSV columns." lightbox="./media/inbound-provisioning-api-powershell/check-columns.png":::

-1. Run the following command:

- ```powershell

- .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -UpdateSchema -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"

- ```

-1. You can verify the update to your provisioning app schema by opening the **Attribute Mapping** page and accessing the **Edit attribute list for API** option under **Advanced options**.

- :::image type="content" border="true" source="./media/inbound-provisioning-api-powershell/advanced-options.png" alt-text="Screenshot of Attribute Mapping in Advanced options." lightbox="./media/inbound-provisioning-api-powershell/advanced-options.png":::

-1. The **Attribute List** shows attributes under the new namespace.

- :::image type="content" border="true" source="./media/inbound-provisioning-api-powershell/attribute-list.png" alt-text="Screenshot of the attribute list." lightbox="./media/inbound-provisioning-api-powershell/attribute-list.png":::

-## Get provisioning logs of the latest sync cycles

-After sending the bulk request, you can query the logs of the latest sync cycles processed by Microsoft Entra ID. You can retrieve the sync statistics and processing details with the PowerShell script and save it for analysis.

-1. To view the log details and sync statistics on the console, run the following command:

- ```powershell

- .\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs -NumberOfCycles 1

- ```

- :::image type="content" border="true" source="./media/inbound-provisioning-api-powershell/stats.png" alt-text="Screenshot of sync statistics." lightbox="./media/inbound-provisioning-api-powershell/stats.png":::

- > [!NOTE]

- > NumberOfCycles is 1 by default. Specify a number to retrieve more sync cycles.

-1. To view sync statistics on the console and save the logs details to a variable, run the following command:

- ```powershell

- $logs=.\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs

- ```

-

- To run the command using client certificate authentication, run the command by providing the correct values for `ServicePrincipalId`, `ClientId` and `TenantId`:

- ```powershell

- $ClientCertificate = Get-ChildItem -Path cert:\CurrentUser\my\ | Where-Object {$_.Subject -eq "CN=CSV2SCIM"}

- $ThumbPrint = $ClientCertificate.ThumbPrint

- $logs=.\CSV2SCIM.ps1 -ServicePrincipalId "<ProvisioningAppObjectId>" -TenantId "contoso.onmicrosoft.com" -ClientId "<AppClientId>" -ClientCertificate (Get-ChildItem Cert:\CurrentUser\My\$ThumbPrint) -GetPreviousCycleLogs -NumberOfCycles 1

- ```

- - To see the details of a specific record we can loop into the collection or select a specific index of it, for example: `$logs[0]`

- :::image type="content" border="true" source="./media/inbound-provisioning-api-powershell/index.png" alt-text="Screenshot of a selected index.":::

- - We can also use the `where-object` statement to search for a specific record using the sourceID or DisplayName. In the **ProvisioningLogs** property, we can find all the details of the operation done for that specific record.

- ```powershell

- $user = $logs | where sourceId -eq '1222'

- $user.ProvisioningLogs | fl

- ```

- :::image type="content" border="true" source="./media/inbound-provisioning-api-powershell/logs.png" alt-text="Screenshot of provisioning logs.":::

- - We can see the specific user affected properties on the **ModifiedProperties** attribute. `$user.ProvisioningLogs.ModifiedProperties`

- :::image type="content" border="true" source="./media/inbound-provisioning-api-powershell/properties.png" alt-text="Screenshot of properties.":::

-## Appendix

-### CSV2SCIM PowerShell usage details

-Here is a list of command-line parameters accepted by the CSV2SCIM PowerShell script.

-```powershell

-PS > CSV2SCIM.ps1 -Path <path-to-csv-file>

-[-ScimSchemaNamespace <customSCIMSchemaNamespace>]

-[-AttributeMapping $AttributeMapping]

-[-ServicePrincipalId <spn-guid>]

-[-ValidateAttributeMapping]

-[-UpdateSchema]

-[-ClientId <client-id>]

-[-ClientCertificate <certificate-object>]

-[-RestartService]

-```

-> [!NOTE]

-> The `AttributeMapping` and `ValidateAttributeMapping` command-line parameters refer to the mapping of CSV column attributes to the standard SCIM schema elements.

-It doesn't refer to the attribute mappings that you perform in the Microsoft Entra admin center provisioning app between source SCIM schema elements and target Microsoft Entra / on-premises Active Directory attributes.

-| Parameter | Description | Processing remarks |

-|-|-|--|

-| Path | The full or relative path to the CSV file. For example: `.\Samples\csv-with-1000-records.csv` | Mandatory: Yes |

-|ScimSchemaNamespace | The custom SCIM Schema namespace to use to send all columns in the CSV file as custom SCIM attributes belonging to specific namespace. For example, `urn:ietf:params:scim:schemas:extension:csv:1.0:User` | Mandatory: Only when you want to:</br>- Update the provisioning app schema or </br>When you want to include custom SCIM attributes in the payload. |

-| AttributeMapping | Points to a PowerShell Data (.psd1 extension) file that maps columns in the CSV file to SCIM Core User and Enterprise User attributes. </br>See example: [AttributeMapping.psd file for CSV2SCIM script]().</br> For example: ```powershell $AttributeMapping = Import-PowerShellDataFile '.\Samples\AttributeMapping.psd1'`-AttributeMapping $AttributeMapping``` | Mandatory: Yes </br> The only scenario when you don't need to specify this is when using the `UpdateSchema` switch.|

-| ValidateAttributeMapping |Use this Switch flag to validate that the AttributeMapping file contains attributes that comply with the SCIM Core and Enterprise user schema. | Mandatory: No</br> Recommend using it to ensure compliance. |

-| ServicePrincipalId |The GUID value of your provisioning app's service principal ID that you can retrieve from the **Provisioning App** > **Properties** > **Object ID**| Mandatory: Only when you want to: </br>- Update the provisioning app schema, or</br>- Send the generated bulk request to the API endpoint. |

-| UpdateSchema |Use this switch to instruct the script to read the CSV columns and add them as custom SCIM attributes in your provisioning app schema.|

-| ClientId |The Client ID of a Microsoft Entra registered app to use for OAuth authentication flow. This app must have valid certificate credentials. | Mandatory: Only when performing certificate-based authentication. |

-| ClientCertificate |The Client Authentication Certificate to use during OAuth flow. | Mandatory: Only when performing certificate-based authentication.|

-| GetPreviousCycleLogs |To get the provisioning logs of the latest sync cycles. |

-| NumberOfCycles | To specify how many sync cycles should be retrieved. This value is 1 by default.|

-| RestartService | With this option, the script temporarily pauses the provisioning job before uploading the data, it uploads the data and then starts the job again to ensure immediate processing of the payload. | Use this option only during testing. |

-### AttributeMapping.psd file

-This file is used to map columns in the CSV file to standard SCIM Core User and Enterprise User attribute schema elements. The file also generates an appropriate representation of the CSV file contents as a bulk request payload.

-In the next example, we mapped the following columns in the CSV file to their counterpart SCIM Core User and Enterprise User attributes.

-```powershell

- @{

- externalId = 'WorkerID'

- name = @{

- familyName = 'LastName'

- givenName = 'FirstName'

- }

- active = { $_.'WorkerStatus' -eq 'Active' }

- userName = 'UserID'

- displayName = 'FullName'

- nickName = 'UserID'

- userType = 'WorkerType'

- title = 'JobTitle'

- addresses = @(

- @{

- type = { 'work' }

- streetAddress = 'StreetAddress'

- locality = 'City'

- postalCode = 'ZipCode'

- country = 'CountryCode'

- }

- )

- phoneNumbers = @(

- @{

- type = { 'work' }

- value = 'OfficePhone'

- }

- )

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" = @{

- employeeNumber = 'WorkerID'

- costCenter = 'CostCenter'

- organization = 'Company'

- division = 'Division'

- department = 'Department'

- manager = @{

- value = 'ManagerID'

- }

- }

-}

-```

-## Next steps

-description: Learn how to troubleshoot InsufficientAccessRights error when provisioning to on-premises Active Directory.

-# Troubleshoot insufficient access rights error

-## Issue

-Inbound user provisioning to Active Directory is working as expected for most users. But for some users, the provisioning logs displays the following error:

-```

-ERROR: InsufficientAccessRights-SecErr: The user has insufficient access rights.. Access is denied. \nError Details: Problem 4003 - INSUFF_ACCESS_RIGHTS.

-OR

-ERROR:

-"Message":"The user has insufficient access rights.",

-"ResponseResultCode":"InsufficientAccessRights",

-"ResponseErrorMessage":"00002098: SecErr: DSID-03150F94, problem 4003 (INSUFF_ACCESS_RIGHTS), data 0",

-The user has insufficient access rights.

-```

-The provisioning logs displays the error code: `HybridSynchronizationActiveDirectoryInsufficientAccessRights`.

-## Cause

-The Provisioning Agent GMSA account ```provAgentgMSA$``` by default has read/write permission to all user objects in the domain. There are two possible causes that might lead to the above error.

-## Resolution

-First confirm what is causing the problem.

-To check if Cause-1 is the source of the problem:

-1. Open the **Active Directory Users and Computers Management Console**.

-2. Select the OU associated with the user.

-3. Right click and navigate to **Properties -> Security -> Advanced**.

- If the **Enable Inheritance** button is shown, then it's confirmed that Cause-1 is the source of the problem.

-4. Click on **Enable Inheritance** so that domain level permissions are applicable to this OU.

- >[!NOTE]

- >Please remember to verify the whole hierarchy from domain level down to the OU holding the affected accounts. All Parent OUs/Containers must have inheritance enabled so the permissions applied at the domain level may cascade down to the final object.

-If Cause-1 is not the source of the problem, then potentially Cause-2 is the source of the problem. There are two possible resolution options.

-**Option 1: Remove affected user from protected AD group**

-To find the list of users that are governed by this ```AdminSDHolder``` permission, Cx can invoke the following command:

-```Get-AdObject -filter {AdminCount -gt 0}```

-Reference articles:

-* Here's an [example PowerShell script](https://notesbytom.wordpress.com/2017/12/01/clear-admincount-and-enable-inheritance-on-user/) that can be used to clear the AdminCount flag and re-enable inheritance on impacted users.

-* Use the steps documented in this [article - Find Orphaned Accounts](https://social.technet.microsoft.com/wiki/contents/articles/33307.active-directory-find-orphaned-objects.aspx) to find orphaned accounts (accounts who aren't part of a protected group, but still have AdminCount flag set to 1)

-*Option 1 might not always work*

-There's a process called The Security Descriptor Propagation (SDPROP) process that runs every hour on the domain controller holding the PDC emulator FSMO role. It's this process that sets the ```AdminCount``` attribute to 1. The main function of SDPROP is to protect highly privileged Active Directory accounts, ensuring that they can't be deleted or have rights modified, accidentally or intentionally, by users or processes with less privilege.

-Reference articles that explain the reason in detail:

-**Option 2: Modify the default permissions of the AdminSDHolder container**

-If option 1 is not feasible and doesn't work as expected, then ask Cx to check with their AD admin and security administrators, if they are allowed to modify the default permissions of the ```AdminSDHolder``` container. This [article](https://go.microsoft.com/fwlink/?linkid=2240198) that explains the importance of the ```AdminSDHolder``` container. Once Cx gets internal approval to update the ```AdminSDHolder``` container permissions, there are two ways to update the permissions.

-* Using ```ADSIEdit``` as described in this [article](https://petri.com/active-directory-security-understanding-adminsdholder-object).

-* Using ```DSACLS``` command-line script. Here's an example script that could be used as a starting point and Cx can tweak it as per their requirements.

-```powershell

-$dcFQDN = "<FQDN Of The Nearest RWDC Of Domain>"

-$domainDN = "<Domain Distinguished Name>"

-$domainNBT = "<Domain NetBIOS Name>"

-$dsaclsCMD = "DSACLS '\\$dcFQDN\CN=AdminSDHolder,CN=System,$domainDN' /G '$domainNBT\provAgentgMSA$:RPWP;<Attribute To Write To>'"

-Invoke-

-Expression $dsaclsCMD | Out-Null

-```

-If the Cx needs more help on troubleshooting on-premises AD permissions, engage Windows Server Support team.

-This article on [AdminSDHolder issues with Microsoft Entra Connect](https://c7solutions.com/2017/03/administrators-aadconnect-and-adminsdholder-issues) has more examples on DSACLS usage.

-**Option 3: Assign full control to provAgentgMSA account**

-Assign **Full Control** permissions to the ```provAgentGMSA``` account. We recommend this step if there are failures with a moving a user object from one container OU to another when these users don't belong to a protected user group.

-In this scenario, ask Cx to complete the following steps and retest the move operation.

-1. Log in to AD domain controller as admin.

-2. Open PowerShell command-line with run-as admin

-3. At the PowerShell prompt, run the following [DSACLS](https://go.microsoft.com/fwlink/?linkid=2240600) command that grants **Generic All/Full Control** to the provisioning agent GMSA account.

-```dsacls "dc=contoso,dc=com" /I:T /G "CN=provAgentgMSA,CN=Managed Service Accounts,DC=contoso,DC=com:GA"```

-Replace the ```dc=contoso,dc=com``` with your root node or appropriate OU container. If you're using a custom GMSA, update the DN value for ```provAgentgMSA```.

-**Option 4: Skip GMSA account and use manually created service account**

-This option should only be used as a temporary workaround to unblock until the GMSA permission issue is investigated and resolved. Our recommendation is to use the GMSA account.

-You can set the registry option to [skip GMSA configuration](https://go.microsoft.com/fwlink/?linkid=2239993) and reconfigure the Microsoft Entra Connect provisioning agent to use a manually created service account with the right permissions.

-## Next steps

-* [Learn more about the Inbound Provisioning API](inbound-provisioning-api-concepts.md)

-description: A guide for independent software vendors for enabling automated provisioning in Microsoft Entra ID

-# Enable automatic user provisioning for your multi-tenant application in Microsoft Entra ID

-Automatic user provisioning is the process of automating the creation, maintenance, and removal of user identities in target systems like your software-as-a-service applications.

-## Why enable automatic user provisioning?

-Applications that require that a user record is present in the application before a userΓÇÖs first sign in require user provisioning. There are benefits to you as a service provider, and benefits to your customers.

-### Benefits to you as the service provider

-* Increase the security of your application by using the Microsoft identity platform.

-* Reduce actual and perceived customer effort to adopt your application.

-* Reduce your costs in integrating with multiple identity providers (IdPs) for automatic user provisioning by using System for Cross-Domain Identity Management (SCIM)-based provisioning.

-* Reduce support costs by providing rich logs to help customers troubleshoot user provisioning issues.

-* Increase the visibility of your application in the [Microsoft Entra app gallery](https://azuremarketplace.microsoft.com/marketplace/apps).

-* Get a prioritized listing in the App Tutorials page.

-### Benefits to your customers

-* Increase security by automatically removing access to your application for users who change roles or leave the organization to your application.

-* Simplify user management for your application by avoiding human error and repetitive work associated with manual provisioning.

-* Reduce the costs of hosting and maintaining custom-developed provisioning solutions.

-## Choose a provisioning method

-Microsoft Entra ID provides several integration paths to enable automatic user provisioning for your application.

-* The [Microsoft Entra provisioning service](../app-provisioning/user-provisioning.md) manages the provisioning and deprovisioning of users from Microsoft Entra ID to your application (outbound provisioning) and from your application to Microsoft Entra ID (inbound provisioning). The service connects to the System for Cross-Domain Identity Management (SCIM) user management API endpoints provided by your application.

-* When using the [Microsoft Graph](/graph/), your application manages inbound and outbound provisioning of users and groups from Microsoft Entra ID to your application by querying the Microsoft Graph API.

-* The Security Assertion Markup Language Just in Time (SAML JIT) user provisioning can be enabled if your application is using SAML for federation. It uses claims information sent in the SAML token to provision users.

-To help determine which integration option to use for your application, refer to the high-level comparison table, and then see the more detailed information on each option.

-| Capabilities enabled or enhanced by Automatic Provisioning| Microsoft Entra provisioning service (SCIM 2.0)| Microsoft Graph API (OData v4.0)| SAML JIT |

-|||||

-| User and group management in Microsoft Entra ID| √| √| User only |

-| Manage users and groups synced from on-premises Active Directory| √*| √*| User only* |

-| Access data beyond users and groups during provisioning Access to Microsoft 365 data (Teams, SharePoint, Email, Calendar, Documents, etc.)| X+| √| X |

-| Create, read, and update users based on business rules| √| √| √ |

-| Delete users based on business rules| √| √| X |

-| Manage automatic user provisioning for all applications from the Microsoft Entra admin center| √| X| √ |

-| Support multiple identity providers| √| X| √ |

-| Support guest accounts (B2B)| √| √| √ |

-| Support non-enterprise accounts (B2C)| X| √| √ |

-^* ΓÇô Microsoft Entra Connect setup is required to sync users from AD to Microsoft Entra ID.

-<sup>+</sup >ΓÇô Using SCIM for provisioning does not preclude you from integrating your application with Microsoft Graph for other purposes.

-<a name='azure-ad-provisioning-service-scim'></a>

-## Microsoft Entra provisioning service (SCIM)

-The Microsoft Entra provisioning service uses [SCIM](https://aka.ms/SCIMOverview), an industry standard for provisioning supported by many identity providers (IdPs) as well as applications (e.g. Slack, G Suite, Dropbox). We recommend you use the Microsoft Entra provisioning service if you want to support IdPs in addition to Microsoft Entra ID, as any SCIM-compliant IdP can connect to your SCIM endpoint. Building a simple /User endpoint, you can enable provisioning without having to maintain your own sync engine.

-For more information on how the Microsoft Entra provisioning service users SCIM, see:

-* [Learn more about the SCIM standard](https://aka.ms/SCIMOverview)

-* [Using System for Cross-Domain Identity Management (SCIM) to automatically provision users and groups from Microsoft Entra ID to applications](../app-provisioning/use-scim-to-provision-users-and-groups.md)

-* [Understand the Microsoft Entra SCIM implementation](../app-provisioning/use-scim-to-provision-users-and-groups.md)

-## Microsoft Graph for Provisioning

-When you use Microsoft Graph for provisioning, you have access to all the rich user data available in Graph. In addition to the details of users and groups, you can also fetch additional information like the userΓÇÖs roles, manager and direct reports, owned and registered devices, and hundreds of other data pieces available in the [Microsoft Graph](/graph/api/overview).

-More than 15 million organizations, and 90% of fortune 500 companies use Microsoft Entra ID while subscribing to Microsoft cloud services like Microsoft 365, Microsoft Azure, or Enterprise Mobility Suite. You can use Microsoft Graph to integrate your app with administrative workflows, such as employee onboarding (and termination), profile maintenance, and more.

-Learn more about using Microsoft Graph for provisioning:

-* [Microsoft Graph Home page](https://developer.microsoft.com/graph)

-* [Overview of Microsoft Graph](/graph/overview)

-* [Microsoft Graph Auth Overview](/graph/auth/)

-* [Getting started with Microsoft Graph](https://developer.microsoft.com/graph/rest-api/)

-## Using SAML JIT for provisioning

-If you want to provision users only upon first sign in to your application, and do not need to automatically deprovision users, SAML JIT is an option. Your application must support SAML 2.0 as a federation protocol to use SAML JIT.

-SAML JIT uses the claims information in the SAML token to create and update user information in the application. Customers can configure these required claims in the Microsoft Entra application as needed. Sometimes the JIT provisioning needs to be enabled from the application side so that customer can use this feature. SAML JIT is useful for creating and updating users, but it can't delete or deactivate the users in the application.

-## Next Steps

-* [Enable Single Sign-on for your application](../manage-apps/v2-howto-app-gallery-listing.md)

-* [Submit your application listing](https://microsoft.sharepoint.com/teams/apponboarding/Apps/SitePages/Default.aspx) and partner with Microsoft to create documentation on MicrosoftΓÇÖs site.

-* [Join the Microsoft Partner Network (free) and create your go to market plan](https://partner.microsoft.com/explore/commercial).

-description: Learn about known issues when you work with automated application provisioning or cross-tenant synchronization in Microsoft Entra ID.

-zone_pivot_groups: app-provisioning-cross-tenant-synchronization

-# Known issues for provisioning in Microsoft Entra ID

-This article discusses known issues to be aware of when you work with app provisioning or cross-tenant synchronization. To provide feedback about the application provisioning service on UserVoice, see [Microsoft Entra application provision UserVoice](https://aka.ms/appprovisioningfeaturerequest). We watch UserVoice closely so that we can improve the service.

-> [!NOTE]

-> This article isn't a comprehensive list of known issues. If you know of an issue that isn't listed, provide feedback at the bottom of the page.

-## Cross-tenant synchronization

-### Unsupported synchronization scenarios

-### Microsoft Teams

-External / B2B users of type `member` created by cross-tenant synchronization can be added to a shared channel in Microsoft Teams. However, external member users created outside of cross-tenant sync cannot be added to a Teams shared channel.

- ### Provisioning users

-An external user from the source (home) tenant can't be provisioned into another tenant. Internal guest users from the source tenant can't be provisioned into another tenant. Only internal member users from the source tenant can be provisioned into the target tenant. For more information, see [Properties of a Microsoft Entra B2B collaboration user](../external-identities/user-properties.md).

-In addition, users that are enabled for SMS sign-in cannot be synchronized through cross-tenant synchronization.

-### Provisioning manager attributes

-Provisioning manager attributes isn't supported.

-### Updating the showInAddressList property fails

-For existing B2B collaboration users, the showInAddressList attribute will be updated as long as the B2B collaboration user doesn't have a mailbox enabled in the target tenant. If the mailbox is enabled in the target tenant, use the [Set-MailUser](/powershell/module/exchange/set-mailuser) PowerShell cmdlet to set the HiddenFromAddressListsEnabled property to a value of $false.

-`Set-MailUser [GuestUserUPN] -HiddenFromAddressListsEnabled:$false`

-Where [GuestUserUPN] is the calculated UserPrincipalName. Example:

-`Set-MailUser guestuser1_contoso.com#EXT#@fabricam.onmicrosoft.com -HiddenFromAddressListsEnabled:$false`

-For more information, see [About the Exchange Online PowerShell module](/powershell/exchange/exchange-online-powershell-v2).

-### Configuring synchronization from target tenant

-Configuring synchronization from the target tenant isn't supported. All configurations must be done in the source tenant. Note that the target administrator is able to turn off cross-tenant synchronization at any time.

-### Two users in the source tenant matched with the same user in the target tenant

-When two users in the source tenant have the same mail, and they both need to be created in the target tenant, one user will be created in the target and linked to the two users in the source. Please ensure that the mail attribute is not shared among users in the source tenant. In addition, please ensure that the mail of the user in the source tenant is from a verified domain. The external user will not be created successfully if the mail is from an unverified domain.

-<a name='usage-of-azure-ad-b2b-collaboration-for-cross-tenant-access'></a>

-### Usage of Microsoft Entra B2B collaboration for cross-tenant access

-## Authorization

-#### Unable to save

-The tenant URL, secret token, and notification email must be filled in to save. You can't provide only one of them.

-#### Unable to change provisioning mode back to manual

-After you've configured provisioning for the first time, you'll notice that the provisioning mode has switched from manual to automatic. You can't change it back to manual. But you can turn off provisioning through the UI. Turning off provisioning in the UI effectively does the same as setting the dropdown to manual.

-## Attribute mappings

-#### Attribute SamAccountName or userType not available as a source attribute

-The attributes **SamAccountName** and **userType** aren't available as a source attribute by default. Extend your schema to add the attributes. You can add the attributes to the list of available source attributes by extending your schema. To learn more, see [Missing source attribute](user-provisioning-sync-attributes-for-mapping.md).

-#### Source attribute dropdown missing for schema extension

-Extensions to your schema can sometimes be missing from the source attribute dropdown in the UI. Go into the advanced settings of your attribute mappings and manually add the attributes. To learn more, see [Customize attribute mappings](customize-application-attributes.md).

-#### Null attribute can't be provisioned

-Microsoft Entra ID currently can't provision null attributes. If an attribute is null on the user object, it will be skipped.

-#### Maximum characters for attribute-mapping expressions

-Attribute-mapping expressions can have a maximum of 10,000 characters.

-#### Unsupported scoping filters

-The **appRoleAssignments**, **userType**, and **accountExpires** attributes aren't supported as scoping filters.

-#### Multivalue directory extensions

-Multivalue directory extensions can't be used in attribute mappings or scoping filters.

-## Service issues

-#### Unsupported scenarios

-#### Automatic provisioning isn't available on my OIDC-based application

-If you create an app registration, the corresponding service principal in enterprise apps won't be enabled for automatic user provisioning. You'll need to either request the app be added to the gallery, if intended for use by multiple organizations, or create a second non-gallery app for provisioning.

-#### The provisioning interval is fixed

-The [time](./application-provisioning-when-will-provisioning-finish-specific-user.md#how-long-will-it-take-to-provision-users) between provisioning cycles is currently not configurable.

-<a name='changes-not-moving-from-target-app-to-azure-ad'></a>

-#### Changes not moving from target app to Microsoft Entra ID

-The app provisioning service isn't aware of changes made in external apps. So, no action is taken to roll back. The app provisioning service relies on changes made in Microsoft Entra ID.

-#### Switching from Sync All to Sync Assigned not working

-After you change scope from **Sync All** to **Sync Assigned**, make sure to also perform a restart to ensure that the change takes effect. You can do the restart from the UI.

-#### Provisioning cycle continues until completion

-When you set provisioning to `enabled = off` or select **Stop**, the current provisioning cycle continues running until completion. The service stops executing any future cycles until you turn provisioning on again.

-#### Member of group not provisioned

-When a group is in scope and a member is out of scope, the group will be provisioned. The out-of-scope user won't be provisioned. If the member comes back into scope, the service won't immediately detect the change. Restarting provisioning addresses the issue. Periodically restart the service to ensure that all users are properly provisioned.

-#### Manager isn't provisioned

-If a user and their manager are both in scope for provisioning, the service provisions the user and then updates the manager. If on day one the user is in scope and the manager is out of scope, we'll provision the user without the manager reference. When the manager comes into scope, the manager reference won't be updated until you restart provisioning and cause the service to reevaluate all the users again.

-#### Global Reader

-The Global Reader role is unable to read the provisioning configuration. Create a custom role with the `microsoft.directory/applications/synchronization/standard/read` permission in order to read the provisioning configuration from the Microsoft Entra admin center.

-#### Microsoft Azure Government Cloud

-Credentials, including the secret token, notification email, and SSO certificate notification emails together have a 1KB limit in the Microsoft Azure Government Cloud.

-## On-premises application provisioning

-The following information is a current list of known limitations with the Microsoft Entra ECMA Connector Host and on-premises application provisioning.

-### Application and directories

-The following applications and directories aren't yet supported.

-<a name='active-directory-domain-services-user-or-group-writeback-from-azure-ad-by-using-the-on-premises-provisioning-preview'></a>

-#### Active Directory Domain Services (user or group writeback from Microsoft Entra ID by using the on-premises provisioning preview)

- - When a user is managed by Microsoft Entra Connect, the source of authority is on-premises Active Directory Domain Services. So, user attributes can't be changed in Microsoft Entra ID. This preview doesn't change the source of authority for users managed by Microsoft Entra Connect.

- - Attempting to use Microsoft Entra Connect and the on-premises provisioning to provision groups or users into Active Directory Domain Services can lead to creation of a loop, where Microsoft Entra Connect can overwrite a change that was made by the provisioning service in the cloud. Microsoft is working on a dedicated capability for group or user writeback. Upvote the UserVoice feedback on [this website](https://feedback.azure.com/d365community/forum/22920db1-ad25-ec11-b6e6-000d3a4f0789/) to track the status of the preview. Alternatively, you can use [Microsoft Identity Manager](/microsoft-identity-manager/microsoft-identity-manager-2016) for user or group writeback from Microsoft Entra ID to Active Directory.

-<a name='azure-ad'></a>

-#### Microsoft Entra ID

- By using on-premises provisioning, you can take a user already in Microsoft Entra ID and provision them into a third-party application. *You can't bring a user into the directory from a third-party application.* Customers will need to rely on our native HR integrations, Microsoft Entra Connect, Microsoft Identity Manager, or Microsoft Graph, to bring users into the directory.

-### Attributes and objects

-The following attributes and objects aren't supported:

- - Multivalued attributes.

- - Reference attributes (for example, manager).

- - Groups.

- - Complex anchors (for example, ObjectTypeName+UserName).

- - Binary attributes.

- - On-premises applications are sometimes not federated with Microsoft Entra ID and require local passwords. The on-premises provisioning preview doesn't support password synchronization. Provisioning initial one-time passwords is supported. Ensure that you're using the [Redact](./functions-for-customizing-application-data.md#redact) function to redact the passwords from the logs. In the SQL and LDAP connectors, the passwords aren't exported on the initial call to the application, but rather a second call with set password.

-#### SSL certificates

- The Microsoft Entra ECMA Connector Host currently requires either an SSL certificate to be trusted by Azure or the provisioning agent to be used. The certificate subject must match the host name the Microsoft Entra ECMA Connector Host is installed on.

-#### Anchor attributes

- The Microsoft Entra ECMA Connector Host currently doesn't support anchor attribute changes (renames) or target systems, which require multiple attributes to form an anchor.

-#### Attribute discovery and mapping

- The attributes that the target application supports are discovered and surfaced in the Microsoft Entra admin center in **Attribute Mappings**. Newly added attributes will continue to be discovered. If an attribute type has changed, for example, string to Boolean, and the attribute is part of the mappings, the type won't change automatically in the Microsoft Entra admin center. Customers will need to go into advanced settings in mappings and manually update the attribute type.

-#### Provisioning agent

-## Next steps

-[How provisioning works](how-provisioning-works.md)

-description: Presents an overview of on-premises application provisioning architecture.

-# Microsoft Entra on-premises application identity provisioning architecture

-## Overview

-The following diagram shows an overview of how on-premises application provisioning works.

-

-There are three primary components to provisioning users into an on-premises application:

->[!NOTE]

-> Microsoft Identity Manager Synchronization isn't required. But you can use it to build and test your ECMA connector before you import it into the ECMA host.

-> [!VIDEO https://www.youtube.com/embed/QdfdpaFolys]

-### Firewall requirements

-You don't need to open inbound connections to the corporate network. The provisioning agents only use outbound connections to the provisioning service, which means there's no need to open firewall ports for incoming connections. You also don't need a perimeter (DMZ) network because all connections are outbound and take place over a secure channel.

-The required outbound endpoints for the provisioning agents are detailed [here](../hybrid/cloud-sync/how-to-prerequisites.md#firewall-and-proxy-requirements).

-## ECMA Connector Host architecture

-The ECMA Connector Host has several areas it uses to achieve on-premises provisioning. The diagram below is a conceptual drawing that presents these individual areas. The table below describes the areas in more detail.

-[](./media/on-premises-application-provisioning-architecture/ecma-2.png#lightbox)

-|Area|Description|

-|--|--|

-|Endpoints|Responsible for communication and data-transfer with the Microsoft Entra provisioning service|

-|In-memory cache|Used to store the data imported from the on-premises data source|

-|Autosync|Provides asynchronous data synchronization between the ECMA Connector Host and the on-premises data source|

-|Business logic|Used to coordinate all of the ECMA Connector Host activities. The Autosync time is configurable in the ECMA host. This is in the properties page.|

-### About anchor attributes and distinguished names

-The following information is provided to better explain the anchor attributes and the distinguished names, particularly used by the genericSQL connector.

-The anchor attribute is a unique attribute of an object type that does not change and represents that object in the ECMA Connector Host in-memory cache.

-The distinguished name (DN) is a name that uniquely identifies an object by indicating its current location in the directory hierarchy. Or in the case of SQL, in the partition. The name is formed by concatenating the anchor attribute at the root of the directory partition.

-When we think of traditional DNs in a traditional format, for say, Active Directory or LDAP, we think of something similar to:

- `CN=Lola Jacobson,CN=Users,DC=contoso,DC=com`

-However, for a data source such as SQL, which is flat, not hierarchical, the DN needs to be either already present in one of the tables or created from the information we provide to the ECMA Connector Host.

-This can be achieved by checking **Autogenerated** in the checkbox when configuring the genericSQL connector. When you choose DN to be autogenerated, the ECMA host will generate a DN in an LDAP format: CN=&lt;anchorvalue&gt;,OBJECT=&lt;type&gt;. This also assumes that the DN is Anchor **unchecked** in the Connectivity page.

-

- [](./media/on-premises-application-provisioning-architecture/user-2.png#lightbox)

-The genericSQL connector expects the DN to be populated using an LDAP format. The Generic SQL connector is using the LDAP style with the component name "OBJECT=". This allows it to use partitions (each object type is a partition).

-Since ECMA Connector Host currently only supports the USER object type, the OBJECT=&lt;type&gt; will be OBJECT=USER. So the DN for a user with an anchorvalue of ljacobson would be:

- CN=ljacobson,OBJECT=USER

-### User creation workflow

-1. The Microsoft Entra provisioning service queries the ECMA Connector Host to see if the user exists. It uses the **matching attribute** as the filter. This attribute is defined in the Azure portal under Enterprise applications -> On-premises provisioning -> provisioning -> attribute matching. It is denoted by the 1 for matching precedence.

-You can define one or more matching attribute(s) and prioritize them based on the precedence. Should you want to change the matching attribute you can also do so.

- [](./media/on-premises-application-provisioning-architecture/match-1.png#lightbox)

-2. ECMA Connector Host receives the GET request and queries its internal cache to see if the user exists and has based imported. This is done using the matching attribute(s) above. If you define multiple matching attributes, the Microsoft Entra provisioning service will send a GET request for each attribute and the ECMA host will check its cache for a match until it finds one.

-3. If the user does not exist, Microsoft Entra ID will make a POST request to create the user. The ECMA Connector Host will respond back to Microsoft Entra ID with the HTTP 201 and provide an ID for the user. This ID is derived from the anchor value defined in the object types page. This anchor will be used by Microsoft Entra ID to query the ECMA Connector Host for future and subsequent requests.

-4. If a change happens to the user in Microsoft Entra ID, then Microsoft Entra ID will make a GET request to retrieve the user using the anchor from the previous step, rather than the matching attribute in step 1. This allows, for example, the UPN to change without breaking the link between the user in Microsoft Entra ID and in the app.

-## Agent best practices

- - Reducing the distance between the two ends of the hop.

- - Choosing the right network to traverse. For example, traversing a private network rather than the public internet might be faster because of dedicated links.

-## Provisioning agent questions

-Some common questions are answered here.

-### How do I know the version of my provisioning agent?

- 1. Sign in to the Windows server where the provisioning agent is installed.

- 2. Go to **Control Panel** > **Uninstall or Change a Program**.

- 3. Look for the version that corresponds to the entry for **Microsoft Entra Connect Provisioning Agent**.

-<a name='can-i-install-the-provisioning-agent-on-the-same-server-running-azure-ad-connect-or-microsoft-identity-manager'></a>

-### Can I install the provisioning agent on the same server running Microsoft Entra Connect or Microsoft Identity Manager?

-Yes. You can install the provisioning agent on the same server that runs Microsoft Entra Connect or Microsoft Identity Manager, but they aren't required.

-### How do I configure the provisioning agent to use a proxy server for outbound HTTP communication?

-The provisioning agent supports use of outbound proxy. You can configure it by editing the agent config file **C:\Program Files\Microsoft Azure AD Connect Provisioning Agent\AADConnectProvisioningAgent.exe.config**. Add the following lines into it toward the end of the file just before the closing `</configuration>` tag. Replace the variables `[proxy-server]` and `[proxy-port]` with your proxy server name and port values.

-```

- <system.net>

- <defaultProxy enabled="true" useDefaultCredentials="true">

- <proxy

- usesystemdefault="true"

- proxyaddress="http://[proxy-server]:[proxy-port]"

- bypassonlocal="true"

- />

- </defaultProxy>

- </system.net>

-```

-<a name='how-do-i-ensure-the-provisioning-agent-can-communicate-with-the-azure-ad-tenant-and-no-firewalls-are-blocking-ports-required-by-the-agent'></a>

-### How do I ensure the provisioning agent can communicate with the Microsoft Entra tenant and no firewalls are blocking ports required by the agent?

-You can also check whether all the required ports are open.

-### How do I uninstall the provisioning agent?

- 1. Sign in to the Windows server where the provisioning agent is installed.

- 2. Go to **Control Panel** > **Uninstall or Change a Program**.

- 3. Uninstall the following programs:

- - Microsoft Entra Connect Provisioning Agent

- - Microsoft Entra Connect Agent Updater

- - Microsoft Entra Connect Provisioning Agent Package

-## Provisioning agent history

-This article lists the versions and features of Microsoft Entra Connect Provisioning Agent that have been released. The Microsoft Entra team regularly updates the Provisioning Agent with new features and functionality. Please ensure that you do not use the same agent for on-premises provisioning and cloud sync / HR-driven provisioning.

-Microsoft provides direct support for the latest agent version and one version before.

-### Download link

-On-premises app provisioning has been rolled into the provisioning agent and is available from the portal. See [installing the provisioning agent](../hybrid/cloud-sync/how-to-install.md).

-### 1.1.892.0

-May 20th, 2022 - released for download

-#### Fixed issues

-### 1.1.846.0

-April 11th, 2022 - released for download

-#### Fixed issues

-## Next steps

-description: This document describes how to configure Microsoft Entra ID to provision users with external systems that offer REST and SOAP APIs.

-# Provisioning with the custom connectors

-Microsoft Entra ID supports preintegrated connectors for applications that support the following protocols and standards:

-> [!div class="checklist"]

-> - [SCIM 2.0](on-premises-scim-provisioning.md)

-> - [SQL](tutorial-ecma-sql-connector.md)

-> - [LDAP](on-premises-ldap-connector-configure.md)

-> - [REST](on-premises-ldap-connector-configure.md)

-> - [SOAP](on-premises-ldap-connector-configure.md)

-For connectivity to applications that don't support the aforementioned protocols and standards, customers and [partners](https://social.technet.microsoft.com/wiki/contents/articles/1589.fim-2010-mim-2016-management-agents-from-partners.aspx) have built custom [ECMA 2.0](/previous-versions/windows/desktop/forefront-2010/hh859557(v=vs.100)) connectors for Microsoft Identity Manager (MIM) 2016. You can now use those ECMA 2.0 connectors with the lightweight Microsoft Entra provisioning agent, without needing MIM sync deployed.

-## Exporting and importing a MIM connector

-If you have a custom ECMA 2.0 connector in MIM, you can export it by following the instructions [here](on-premises-migrate-microsoft-identity-manager.md#export-a-connector-configuration-from-mim-sync). You need to save the XML file, the DLL, and related software for your connector.

-To import your connector, you can use the instructions [here](on-premises-migrate-microsoft-identity-manager.md#import-a-connector-configuration). You will need to copy the DLL for your connector, and any of its prerequisite DLLs, to that same ECMA subdirectory of the Service directory. After the xml has been imported, continue through the wizard and ensure that all the required fields are populated.

-## Updating a custom connector dll

-When updating a connector, ensure that the dll is updated in all required locations. Use the steps below to properly update your custom connector dll:

-1. Close the Microsoft ECMA2Host Configuration Wizard.

-2. Stop the Microsoft ECMA2Host service.

-3. Manually update the custom connector dll into the following folders.

- 1. ECMA

- 2. ECMA > Cache > {connector name}

- 3. ECMA > Cache > {connector name} > AutosyncService

-4. Start the Microsoft ECMA2Host service.

-

- > [!NOTE]

- > If multiple connectors are using the same custom dll, you will need to complete step 3.ii and 3.iii for each connector.

-

-## Requirements

-Custom connectors built for MIM rely on the [ECMA framework](/previous-versions/windows/desktop/forefront-2010/hh859557(v=vs.100)). Please ensure that you are following best practices such as:

-* Ensuring that methods in your connector are declared as public

-* Excluding prefixes from method names. For example:

- * **Correct:** public Schema GetSchema (KeyedCollection<string, ConfigParameter> configParameters)

- * **Incorrect:** Schema PrefixGetSchema.GetSchema (KeyedCollection<string, ConfigParameter> configParameters)

-

-The following table includes capabilities of the ECMA framework that are either partially supported or not supported by the Microsoft Entra provisioning agent. For a list of known limitations for the Microsoft Entra provisioning service and on-premises application provisioning, see [here](known-issues.md#on-premises-application-provisioning).

-| **Capability / feature** | **Support** | **Comments** |

-| | | |

-| Object type | Partially supported | Supports one object type |

-| Partitions | Partially supported | Supports one partition |

-| Hierarchies | Not supported | |

-| Full export | Not supported | |

-| ExportPasswordInFirstPass | Not supported | |

-| Normalizations | Not supported | |

-| Concurrent operations | Ignored | |

-| DeleteAddAsReplace | Ignored | |

-## Next steps

-description: Describes how to troubleshoot various issues you might encounter when you install and use the ECMA Connector Host.

-# Troubleshoot on-premises application provisioning

-## Troubleshoot test connection issues

-After you configure the provisioning agent and ECMA host, it's time to test connectivity from the Microsoft Entra provisioning service to the provisioning agent, the ECMA host, and the application. To perform this end-to-end test, select **Test connection** in the application in the Azure portal. Be sure to wait 10 to 20 minutes after assigning an initial agent or changing the agent before testing the connection. If after this time the test connection fails, try the following troubleshooting steps:

- 1. Check that the agent and ECMA host are running:

- 1. On the server with the agent installed, open **Services** by going to **Start** > **Run** > **Services.msc**.

- 2. Under **Services**, make sure the **Microsoft Entra Connect Provisioning Agent**, and **Microsoft ECMA2Host** services are present and their status is *Running*.

-

- 

- 2. Check that the ECMA Connector Host service is responding to requests.

- 1. On the server with the agent installed, launch PowerShell.

- 1. Change to the folder where the ECMA host was installed, such as `C:\Program Files\Microsoft ECMA2Host`.

- 1. Change to the subdirectory `Troubleshooting`.

- 1. Run the script `TestECMA2HostConnection.ps1` in that directory. Provide as arguments the connector name and the secret token when prompted.

- ```

- PS C:\Program Files\Microsoft ECMA2Host\Troubleshooting> .\TestECMA2HostConnection.ps1

- Supply values for the following parameters:

- ConnectorName: CORPDB1

- SecretToken: ************

- ```

- 1. This script sends a SCIM GET or POST request to validate that the ECMA Connector Host is operating and responding to requests. If the output does not show that an HTTP connection was successful, then check that the service is running and that the correct secret token was provided.

- 1. Ensure that the agent is active by going to your application in the Azure portal, selecting **admin connectivity**, selecting the agent dropdown list, and ensuring your agent is active.

- 1. Check if the secret token provided is the same as the secret token on-premises. Go to on-premises, provide the secret token again, and then copy it into the Azure portal.

- 1. Ensure that you've assigned one or more agents to the application in the Azure portal.

- 1. After you assign an agent, you need to wait 10 to 20 minutes for the registration to complete. The connectivity test won't work until the registration completes.

- 1. Ensure that you're using a valid certificate that has not expired. Go to the **Settings** tab of the ECMA host to view the certificate expiration date. If the certificate has expired, click `Generate certificate` to generate a new certificate.

- 1. Restart the provisioning agent by going to the taskbar on your VM by searching for the Microsoft Entra Connect provisioning agent. Right-click **Stop**, and then select **Start**.

- 1. If you continue to see `The ECMA host is currently importing data from the target application` even after restarting the ECMA Connector Host and the provisioning agent, and waiting for the initial import to complete, then you may need to cancel and start over configuring provisioning to the application in the Azure portal.

- 1. When you provide the tenant URL in the Azure portal, ensure that it follows the following pattern. You can replace `localhost` with your host name, but it isn't required. Replace `connectorName` with the name of the connector you specified in the ECMA host. The error message 'invalid resource' generally indicates that the URL does not follow the expected format.

-

- ```

- https://localhost:8585/ecma2host_connectorName/scim

- ```

- 1. Navigate to the following folder to review the provisoning agent logs: C:\ProgramData\Microsoft\Azure AD Connect Provisioning Agent\Trace

- 1. If you see the following error, please add the service account "NT SERVICE\AADConnectProvisioningAgent" to the local group called "Performance Log Users". This eliminates the "Unable to initialize metrics collector" exception error by allowing the account to access the desired registry key: HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib

-```

-Unable to initialize metrics collector, exception: 'System.UnauthorizedAccessException: Access to the registry key 'Global' is denied.

-```

- 12. When configuring the ECMA host, ensure that you provide a certificate with a subject that matches the hostname of your windows server. The certificate that is generated by the ECMA host will do this for you automatically, but should only be used for testing purposes.

-```

-Error code: SystemForCrossDomainIdentityManagementCredentialValidationUnavailable

-Details: We received this unexpected response from your application: Received response from Web resource. Resource: https://localhost/Users?filter=PLACEHOLDER+eq+"8646d011-1693-4cd3-9ee6-0d7482ca2219" Operation: GET Response Status Code: InternalServerError Response Headers: Response Content: An error occurred while sending the request. Please check the service and try again.

-```

-## Unable to configure the ECMA host, view logs in Event Viewer, or start the ECMA host service

-To resolve the following issues, run the ECMA host configuration wizard as an administrator:

-* I get an error when I open the ECMA host wizard.

- 

-* I can configure the ECMA host wizard, but I can't see the ECMA host logs. In this case, you need to open the ECMA Host configuration wizard as an administrator and set up a connector end to end. This step can be simplified by exporting an existing connector and importing it again.

- 

-* I can configure the ECMA host wizard, but I can't start the ECMA host service.

- 

-## Turn on verbose logging

-By default, `switchValue` for the ECMA Connector Host is set to `Verbose`. This setting will emit detailed logging that will help you troubleshoot issues. You can change the verbosity to `Error` if you would like to limit the number of logs emitted to only errors. Wen using the SQL connector without Windows Integrated Auth, we recommend setting the `switchValue` to `Error` as it will ensure that the connection string is not emitted in the logs. In order to change the verbosity to error, update the `switchValue` to "Error" in both places as shown below.

-The file location for verbose service logging is C:\Program Files\Microsoft ECMA2Host\Service\Microsoft.ECMA2Host.Service.exe.config.

- ```

- <?xml version="1.0" encoding="utf-8"?>

- <configuration>

- <startup>

- <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.6" />

- </startup>

- <appSettings>

- <add key="Debug" value="true" />

- </appSettings>

- <system.diagnostics>

- <sources>

- <source name="ConnectorsLog" switchValue="Error">

- <listeners>

- <add initializeData="ConnectorsLog" type="System.Diagnostics.EventLogTraceListener, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" name="ConnectorsLog" traceOutputOptions="LogicalOperationStack, DateTime, Timestamp, Callstack">

- <filter type=""/>

- </add>

- </listeners>

- </source>

- <!-- Choose one of the following switchTrace: Off, Error, Warning, Information, Verbose -->

- <source name="ECMA2Host" switchValue="Error">

- <listeners>

- <add initializeData="ECMA2Host" type="System.Diagnos

- ```

-The file location for wizard logging is C:\Program Files\Microsoft ECMA2Host\Wizard\Microsoft.ECMA2Host.ConfigWizard.exe.config.

- ```

- <source name="ConnectorsLog" switchValue="Error">

- <listeners>

- <add initializeData="ConnectorsLog" type="System.Diagnostics.EventLogTraceListener, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" name="ConnectorsLog" traceOutputOptions="LogicalOperationStack, DateTime, Timestamp, Callstack">

- <filter type=""/>

- </add>

- </listeners>

- </source>

- <!-- Choose one of the following switchTrace: Off, Error, Warning, Information, Verbose -->

- <source name="ECMA2Host" switchValue="Error">

- <listeners>

- <add initializeData="ECMA2Host" type="System.Diagnostics.EventLogTraceListener, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" name="ECMA2HostListener" traceOutputOptions="LogicalOperationStack, DateTime, Timestamp, Callstack" />

- ```

-## Query the ECMA Host Cache

-The ECMA Host has a cache of users in your application that is updated according to the schedule you specify in the properties page of the ECMA Host wizard. In order to query the cache, perform the steps below:

-1. Set the Debug flag to `true`.

- Please be aware that setting the debug flag to `true` disables authentication on the ECMA Host. You will need to set it back to `false` and restart the ECMA Host service once you are done querying the cache.

- The file location for verbose service logging is `C:\Program Files\Microsoft ECMA2Host\Service\Microsoft.ECMA2Host.Service.exe.config`.

- ```

- <?xml version="1.0" encoding="utf-8"?>

- <configuration>

- <startup>

- <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.6" />

- </startup>

- <appSettings>

- <add key="Debug" value="true" />

- </appSettings>

- ```

-2. Restart the `Microsoft ECMA2Host` service.

-1. Wait for the ECMA Host to connect to the target systems and re-read its cache from each of the connected systems. If there are many users in those connected systems, this import process could take several minutes.

-1. Query this endpoint from the server the ECMA Host is installed on, replacing `{connector name}` with the name of your connector, specified in the properties page of the ECMA Host: `https://localhost:8585/ecma2host_{connectorName}/scim/cache`.

- 1. On the server with the agent installed, launch PowerShell.

- 1. Change to the folder where the ECMA host was installed, such as `C:\Program Files\Microsoft ECMA2Host`.

- 1. Change to the subdirectory `Troubleshooting`.

- 1. Run the script `TestECMA2HostConnection.ps1` in that directory, and provide as arguments the connector name and the `ObjectTypePath` value `cache`. When prompted, type the secret token configured for that connector.

- ```

- PS C:\Program Files\Microsoft ECMA2Host\Troubleshooting> .\TestECMA2HostConnection.ps1 -ConnectorName CORPDB1 -ObjectTypePath cache

- Supply values for the following parameters:

- SecretToken: ************

- ```

- 1. This script sends a SCIM GET request to validate that the ECMA Connector Host is operating and responding to requests. If the output does not show that an HTTP connection was successful, then check that the service is running and that the correct secret token was provided.

-1. Set the Debug flag back to `false` or remove the setting once you are done querying the cache.

-2. Restart the `Microsoft ECMA2Host` service.

-## Target attribute is missing

-The provisioning service automatically discovers attributes in your target application. If you see that a target attribute is missing in the target attribute list in the Azure portal, perform the following troubleshooting step:

- 1. Review the **Select Attributes** page of your ECMA host configuration to check that the attribute has been selected, so that it will be exposed to the Azure portal.

- 1. Ensure that the ECMA host service is running.

- 1. Review the ECMA host logs to check that a /schemas request was made, and review the attributes in the response. This information will be valuable for support to troubleshoot the issue.

-## Collect logs from Event Viewer as a zip file

-You can use an included script to capture the event logs in a zip file and export them.

- 1. On the server with the agent installed, right click on PowerShell in the Start menu and select to `Run as administrator`.

- 1. Change to the folder where the ECMA host was installed, such as `C:\Program Files\Microsoft ECMA2Host`.

- 1. Change to the subdirectory `Troubleshooting`.

- 1. Run the script `CollectTroubleshootingInfo.ps1` in that directory.

- 1. The script will create a ZIP file in that directory containing the event logs.

-## Review events in Event Viewer

-After the ECMA Connector Host schema mapping has been configured, start the service so it will listen for incoming connections. Then, monitor for incoming requests.

- 1. Select the **Start** menu, enter **event viewer**, and select **Event Viewer**.

- 1. In **Event Viewer**, expand **Applications and Services** logs, and select **Microsoft ECMA2Host Logs**.

- 1. As changes are received by the connector host, events will be written to the application log.

-### Common errors

-| Error | Resolution |

-| -- | -- |

-| Could not load file or assembly 'file:///C:\Program Files\Microsoft ECMA2Host\Service\ECMA\Cache\8b514472-c18a-4641-9a44-732c296534e8\Microsoft.IAM.Connector.GenericSql.dll' or one of its dependencies. Access is denied. | Ensure that the network service account has 'full control' permissions over the cache folder. |

-| Invalid LDAP style of object's DN. DN: username@domain.com" or `Target Site: ValidByLdapStyle` | Ensure the 'DN is Anchor' checkbox is not checked in the 'connectivity' page of the ECMA host. Ensure the 'autogenerated' checkbox is selected in the 'object types' page of the ECMA host. For more information, see [About anchor attributes and distinguished names](on-premises-application-provisioning-architecture.md#about-anchor-attributes-and-distinguished-names).|

-## Understand incoming SCIM requests

-Requests made by Microsoft Entra ID to the provisioning agent and connector host use the SCIM protocol. Requests made from the host to apps use the protocol the app supports. The requests from the host to the agent to Microsoft Entra ID rely on SCIM. You can learn more about the SCIM implementation in [Tutorial: Develop and plan provisioning for a SCIM endpoint in Microsoft Entra ID](use-scim-to-provision-users-and-groups.md).

-The Microsoft Entra provisioning service generally makes a get-user call to check for a [dummy user](use-scim-to-provision-users-and-groups.md#request-3) in three situations: at the beginning of each provisioning cycle, before performing on-demand provisioning and when **test connection** is selected. This check ensures the target endpoint is available and returning SCIM-compliant responses to the Microsoft Entra provisioning service.

-## How do I troubleshoot the provisioning agent?

-You might experience the following error scenarios.

-### Agent failed to start

-You might receive an error message that states:

-"Service 'Microsoft Entra Connect Provisioning Agent' failed to start. Check that you have sufficient privileges to start the system services."

-This problem is typically caused by a group policy that prevented permissions from being applied to the local NT Service sign-in account created by the installer (NT SERVICE\AADConnectProvisioningAgent). These permissions are required to start the service.

-To resolve this problem:

- 1. Sign in to the server with an administrator account.

- 2. Open **Services** by either navigating to it or by going to **Start** > **Run** > **Services.msc**.

- 3. Under **Services**, double-click **Microsoft Entra Connect Provisioning Agent**.

- 4. On the **Log On** tab, change **This account** to a domain admin. Then restart the service.

-This test verifies that your agents can communicate with Azure over port 443. Open a browser, and go to the previous URL from the server where the agent is installed.

-### Agent times out or certificate is invalid

-You might get the following error message when you attempt to register the agent.

-

-This problem is usually caused by the agent being unable to connect to the Hybrid Identity Service and requires you to configure an HTTP proxy. To resolve this problem, configure an outbound proxy.

-The provisioning agent supports use of an outbound proxy. You can configure it by editing the agent config file *C:\Program Files\Microsoft Azure AD Connect Provisioning Agent\AADConnectProvisioningAgent.exe.config*.

-Add the following lines into it, toward the end of the file just before the closing `</configuration>` tag.

-Replace the variables `[proxy-server]` and `[proxy-port]` with your proxy server name and port values.

-```xml

- <system.net>

- <defaultProxy enabled="true" useDefaultCredentials="true">

- <proxy

- usesystemdefault="true"

- proxyaddress="http://[proxy-server]:[proxy-port]"

- bypassonlocal="true"

- />

- </defaultProxy>

- </system.net>

-```

-### Agent registration fails with security error

-You might get an error message when you install the cloud provisioning agent.

-This problem is typically caused by the agent being unable to execute the PowerShell registration scripts because of local PowerShell execution policies.

-To resolve this problem, change the PowerShell execution policies on the server. You need to have Machine and User policies set as *Undefined* or *RemoteSigned*. If they're set as *Unrestricted*, you'll see this error. For more information, see [PowerShell execution policies](/powershell/module/microsoft.powershell.core/about/about_execution_policies).

-### Log files

-By default, the agent emits minimal error messages and stack trace information. You can find trace logs in the folder C:\ProgramData\Microsoft\Azure AD Connect Provisioning Agent\Trace.

-To gather more information for troubleshooting agent-related problems:

- 1. Install the `AADCloudSyncTools` PowerShell module as described in [`AADCloudSyncTools` PowerShell module for Microsoft Entra Connect cloud sync](../hybrid/cloud-sync/reference-powershell.md#install-the-aadcloudsynctools-powershell-module).

- 2. Use the `Export-AADCloudSyncToolsLogs` PowerShell cmdlet to capture the information. Use the following switches to fine-tune your data collection. Use:

- - **SkipVerboseTrace** to only export current logs without capturing verbose logs (default = false).

- - **TracingDurationMins** to specify a different capture duration (default = 3 mins).

- - **OutputPath** to specify a different output path (default = user's documents).

-By using Microsoft Entra ID, you can monitor the provisioning service in the cloud and collect logs on-premises. The provisioning service emits logs for each user that was evaluated as part of the synchronization process. Those logs can be consumed through the [Azure portal UI, APIs, and log analytics](../reports-monitoring/concept-provisioning-logs.md). The ECMA host also generates logs on-premises. It shows each provisioning request that was received and the response that was sent to Microsoft Entra ID.

-### Agent installation fails

-* The error `System.ComponentModel.Win32Exception: The specified service already exists` indicates that the previous ECMA host was unsuccessfully uninstalled. Uninstall the host application. Go to program files, and remove the ECMA host folder. You might want to store the configuration file for backup.

-* The following error indicates a prerequisite wasn't fulfilled. Ensure that you have .NET 4.7.1 installed.

- ```

- Method Name : <>c__DisplayClass0_1 :

- RegisterNotLoadedAssemblies Error during load assembly: System.Management.Automation.resources.dll

- Outer Exception Data

- Message: Could not load file or assembly 'file:///C:\Program Files\Microsoft ECMA2Host\Service\ECMA\System.Management.Automation.resources.dll' or one of its dependencies. The system cannot find the file specified.

- ```

-### I am getting an Invalid LDAP style DN error when trying to configure the ECMA Connector Host with SQL

-By default, the generic SQL connector expects the DN to be populated using the LDAP style (when the 'DN is anchor' attribute is left unchecked in the first connectivity page). In the error message `Invalid LDAP style DN` or `Target Site: ValidByLdapStyle`, you may see that the DN field contains a user principal name (UPN), rather than an LDAP style DN that the connector expects.

-To resolve this error message, ensure that **Autogenerated** is selected on the object types page when you configure the connector.

-For more information, see [About anchor attributes and distinguished names](on-premises-application-provisioning-architecture.md#about-anchor-attributes-and-distinguished-names).

-## Next steps

-description: This document describes how to configure Microsoft Entra ID to provision users into an LDAP directory.

-# Configuring Microsoft Entra ID to provision users into LDAP directories

-The following documentation provides configuration and tutorial information demonstrating how to provision users from Microsoft Entra ID into an LDAP directory.

-## Next steps

-description: This document describes how to configure Microsoft Entra ID to provision users into Active Directory Lightweight Directory Services as an example of an LDAP directory.

-# Prepare Active Directory Lightweight Directory Services for provisioning from Microsoft Entra ID

-The following documentation provides tutorial information demonstrating how to prepare an Active Directory Lightweight Directory Services (AD LDS) installation. This can be used as an example LDAP directory for troubleshooting or to demonstrate [how to provision users from Microsoft Entra ID into an LDAP directory](on-premises-ldap-connector-configure.md).

-## Prepare the LDAP directory

-If you do not already have a directory server, the following information is provided to help create a test AD LDS environment. This setup uses PowerShell and the ADAMInstall.exe with an answers file. This document does not cover in-depth information on AD LDS. For more information, see [Active Directory Lightweight Directory Services](/previous-versions/windows/it-pro/windows-server-2012-r2-and-2012/hh831593(v=ws.11)).

-If you already have AD LDS or another directory server, you can skip this content, and continue at the [Tutorial: ECMA Connector Host generic LDAP connector](on-premises-ldap-connector-configure.md) for installing and configuring the ECMA connector host.

-### Create an SSL certificate, a test directory and install AD LDS.

-Use the PowerShell script from [Appendix A](#appendix-ainstall-ad-lds-powershell-script). The script performs the following actions:

- 1. Creates a self-signed certificate that will be used by the LDAP connector.

- 2. Creates a directory for the feature install log.

- 3. Exports the certificate in the personal store to the directory.

- 4. Imports the certificate to the trusted root of the local machine.

- 5. Installs the AD LDS role on our virtual machine.

-On the Windows Server virtual machine where you are using to test the LDAP connector, edit the script to match your computer name, and then run the script using Windows PowerShell with administrative privileges.

-### Create an instance of AD LDS

-Now that the role has been installed, you need to create an instance of AD LDS. To create an instance, you can use the answer file provided below. This file will install the instance quietly without using the UI.

-Copy the contents of [Appendix B](#appendix-banswer-file) in to notepad and save it as **answer.txt** in **"C:\Windows\ADAM"**.

-Now open a cmd prompt with administrative privileges and run the following executable:

-```

-C:\Windows\ADAM> ADAMInstall.exe /answer:answer.txt

-```

-### Create containers and a service account for AD LDS

-The use the PowerShell script from [Appendix C](#appendix-cpopulate-ad-lds-powershell-script). The script performs the following actions:

- 1. Creates a container for the service account that will be used with the LDAP connector.

- 1. Creates a container for the cloud users, where users will be provisioned to.

- 1. Creates the service account in AD LDS.

- 1. Enables the service account.

- 1. Adds the service account to the AD LDS Administrators role.

-On the Windows Server virtual machine, you are using to test the LDAP connector run the script using Windows PowerShell with administrative privileges.

-### Grant the NETWORK SERVICE read permissions to the SSL certificate

-In order to enable SSL to work, you need to grant the NETWORK SERVICE read permissions to our newly created certificate. To grant permissions, use the following steps.

- 1. Navigate to **C:\Program Data\Microsoft\Crypto\Keys**.

- 2. Right-click on the system file located here. It will be a guid. This container is storing our certificate.

- 1. Select properties.

- 1. At the top, select the **Security** tab.

- 1. Select **Edit**.

- 1. Click **Add**.

- 1. In the box, enter **Network Service** and select **Check Names**.

- 1. Select **NETWORK SERVICE** from the list and click **OK**.

- 1. Click **Ok**.

- 1. Ensure the Network service account has read and read & execute permissions and click **Apply** and **OK**.

-### Verify SSL connectivity with AD LDS

-Now that we have configured the certificate and granted the network service account permissions, test the connectivity to verify that it is working.

- 1. Open Server Manager and select AD LDS on the left

- 2. Right-click your instance of AD LDS and select ldp.exe from the pop-up.

- [](../../../includes/media/app-provisioning-ldap/ldp-1.png#lightbox)</br>

- 3. At the top of ldp.exe, select **Connection** and **Connect**.

- 4. Enter the following information and click **OK**.

- - Server: APP3

- - Port: 636

- - Place a check in the SSL box

- [](../../../includes/media/app-provisioning-ldap/ldp-2.png#lightbox)</br>

- 5. You should see a response similar to the screenshot below.

- [](../../../includes/media/app-provisioning-ldap/ldp-3.png#lightbox)</br>

- 6. At the top, under **Connection** select **Bind**.

- 7. Leave the defaults and click **OK**.

- [](../../../includes/media/app-provisioning-ldap/ldp-4.png#lightbox)</br>

- 8. You should now, successfully bind to the instance.

- [](../../../includes/media/app-provisioning-ldap/ldp-5.png#lightbox)</br>

-### Disable the local password policy

-Currently, the LDAP connector provisions users with a blank password. This provisioning will not satisfy the local password policy on our server so we are going to disable it for testing purposes. To disable password complexity, on a non-domain-joined server, use the following steps.

->[!IMPORTANT]

->Because on-going password sync is not a feature of on-premises LDAP provisioning, Microsoft recommends that AD LDS is used specifically with federated applications, when used in conjunction with AD DS, or when updating existing users in an instance of AD LDS.

- 1. On the server, click **Start**, **Run**, and then **gpedit.msc**

- 2. On the **Local Group Policy editor**, navigate to Computer Configuration > Windows Settings > Security Settings > Account Policies > Password Policy

- 3. On the right, double-click **Password must meet complexity requirements** and select **Disabled**.

- [](../../../includes/media/app-provisioning-ldap/local-1.png#lightbox)</br>

- 5. Click **Apply** and **Ok**

- 6. Close the Local Group Policy editor

-

-Next, continue in the guidance to [provision users from Microsoft Entra ID into an LDAP directory](on-premises-ldap-connector-configure.md) to download and configure the provisioning agent.

-## Appendix A - Install AD LDS PowerShell script

-The following PowerShell script can be used to automate the installation of Active Directory Lightweight Directory Services. You'll need to edit the script to match your environment; in particular, change `APP3` to the hostname of your computer.

-```powershell

-# Filename: 1_SetupADLDS.ps1

-# Description: Creates a certificate that will be used for SSL and installs Active Directory Lighetweight Directory Services.

-#

-# DISCLAIMER:

-# Copyright (c) Microsoft Corporation. All rights reserved. This

-# script is made available to you without any express, implied or

-# statutory warranty, not even the implied warranty of

-# merchantability or fitness for a particular purpose, or the

-# warranty of title or non-infringement. The entire risk of the

-# use or the results from the use of this script remains with you.

-#

-#

-#

-#

-#Declare variables

-$DNSName = 'APP3'

-$CertLocation = 'cert:\LocalMachine\MY'

-$logpath = "c:\"

-$dirname = "test"

-$dirtype = "directory"

-$featureLogPath = "c:\test\featurelog.txt"

-#Create a new self-signed certificate

-New-SelfSignedCertificate -DnsName $DNSName -CertStoreLocation $CertLocation

-#Create directory

-New-Item -Path $logpath -Name $dirname -ItemType $dirtype

-#Export the certificate from the local machine personal store

-Get-ChildItem -Path cert:\LocalMachine\my | Export-Certificate -FilePath c:\test\allcerts.sst -Type SST

-#Import the certificate in to the trusted root

-Import-Certificate -FilePath "C:\test\allcerts.sst" -CertStoreLocation cert:\LocalMachine\Root

-#Install AD LDS

-start-job -Name addFeature -ScriptBlock {

-Add-WindowsFeature -Name "ADLDS" -IncludeAllSubFeature -IncludeManagementTools

- }

-Wait-Job -Name addFeature

-Get-WindowsFeature | Where installed >>$featureLogPath

- ```

-## Appendix B - Answer file

-This file is used to automate and create an instance of AD LDS. You will edit this file to match your environment; in particular, change `APP3` to the hostname of your server.

->[!IMPORTANT]

-> This script uses the local administrator for the AD LDS service account and has its password hard-coded in the answers. This action is for **testing only** and should never be used in a production environment.

->

-> If you are installing AD LDS on a domain controller and not a member or standalone server, you will need to change the LocalLDAPPortToListenOn and LocalSSLPortToListonOn to something other than the well-known ports for LDAP and LDAP over SSL. For example, LocalLDAPPortToListenOn=51300 and LocalSSLPortToListenOn=51301.

-```

- [ADAMInstall]

- InstallType=Unique

- InstanceName=AD-APP-LDAP

- LocalLDAPPortToListenOn=389

- LocalSSLPortToListenOn=636

- NewApplicationPartitionToCreate=CN=App,DC=contoso,DC=lab

- DataFilesPath=C:\Program Files\Microsoft ADAM\AD-APP-LDAP\data

- LogFilesPath=C:\Program Files\Microsoft ADAM\AD-APP-LDAP\data

- ServiceAccount=APP3\Administrator

- ServicePassword=Pa$$Word1

- AddPermissionsToServiceAccount=Yes

- Administrator=APP3\Administrator

- ImportLDIFFiles="MS-User.LDF"

- SourceUserName=APP3\Administrator

- SourcePassword=Pa$$Word1

- ```

-## Appendix C - Populate AD LDS PowerShell script

-PowerShell script to populate AD LDS with containers and a service account.

-```powershell

-# Filename: 2_PopulateADLDS.ps1

-# Description: Populates our AD LDS environment with 2 containers and a service account

-# DISCLAIMER:

-# Copyright (c) Microsoft Corporation. All rights reserved. This

-# script is made available to you without any express, implied or

-# statutory warranty, not even the implied warranty of

-# merchantability or fitness for a particular purpose, or the

-# warranty of title or non-infringement. The entire risk of the

-# use or the results from the use of this script remains with you.

-#

-#

-#

-#

-# Create service accounts container

-New-ADObject -Name "ServiceAccounts" -Type "container" -Path "CN=App,DC=contoso,DC=lab" -Server "APP3:389"

-Write-Output "Creating ServiceAccounts container"

-# Create cloud users container

-New-ADObject -Name "CloudUsers" -Type "container" -Path "CN=App,DC=contoso,DC=lab" -Server "APP3:389"

-Write-Output "Creating CloudUsers container"

-# Create a new service account

-New-ADUser -name "svcAccountLDAP" -accountpassword (ConvertTo-SecureString -AsPlainText 'Pa$$1Word' -Force) -Displayname "LDAP Service Account" -server 'APP3:389' -path "CN=ServiceAccounts,CN=App,DC=contoso,DC=lab"

-Write-Output "Creating service account"

-# Enable the new service account

-Enable-ADAccount -Identity "CN=svcAccountLDAP,CN=ServiceAccounts,CN=App,DC=contoso,DC=lab" -Server "APP3:389"

-Write-Output "Enabling service account"

-# Add the service account to the Administrators role

-Get-ADGroup -Server "APP3:389" -SearchBase "CN=Administrators,CN=Roles,CN=App,DC=contoso,DC=lab" -Filter "name -like 'Administrators'" | Add-ADGroupMember -Members "CN=svcAccountLDAP,CN=ServiceAccounts,CN=App,DC=contoso,DC=lab"

-Write-Output "Adding service accounnt to Administrators role"

- ```

-## Next steps

-description: Describes how to create and export a connector from MIM Sync to be used with the Microsoft Entra ECMA Connector Host.

-# Export a Microsoft Identity Manager connector for use with the Microsoft Entra ECMA Connector Host

-You can import into the Microsoft Entra ECMA Connector Host a configuration for a specific connector from a Forefront Identity Manager Synchronization Service or Microsoft Identity Manager Synchronization Service (MIM Sync) installation. The MIM Sync installation is only used for configuration, not for the ongoing synchronization from Microsoft Entra ID.

-## Create a connector configuration in MIM Sync

-This section is included for illustrative purposes, if you wish to set up MIM Sync with a connector. If you already have MIM Sync with your ECMA connector configured, skip to the next section.

- 1. Prepare a Windows Server 2016 server, which is distinct from the server that will be used for running the Microsoft Entra ECMA Connector Host. This host server should either have a SQL Server 2016 database colocated or have network connectivity to a SQL Server 2016 database. One way to set up this server is by deploying an Azure virtual machine with the image **SQL Server 2016 SP1 Standard on Windows Server 2016**. This server doesn't need internet connectivity other than remote desktop access for setup purposes.

- 1. Create an account for use during the MIM Sync installation. It can be a local account on that Windows Server instance. To create a local account, open **Control Panel** > **User Accounts**, and add the user account **mimsync**.

- 1. Add the account created in the previous step to the local Administrators group.

- 1. Give the account created earlier the ability to run a service. Start **Local Security Policy** and select **Local Policies** > **User Rights Assignment** > **Log on as a service**. Add the account mentioned earlier.

- 1. Install MIM Sync on this host.

- 1. After the installation of MIM Sync is complete, sign out and sign back in.

- 1. Install your connector on the same server as MIM Sync. For illustration purposes, use either of the Microsoft-supplied SQL or LDAP connectors for download from the [Microsoft Download Center](https://www.microsoft.com/download/details.aspx?id=51495).

- 1. Start the Synchronization Service UI. Select **Management Agents**. Select **Create**, and specify the connector management agent. Be sure to select a connector management agent that's ECMA based.

- 1. Give the connector a name, and configure the parameters needed to import and export data to the connector. Be sure to configure that the connector can import and export single-valued string attributes of a user or person object type.

-## Export a connector configuration from MIM Sync

- 1. On the MIM Sync server computer, start the Synchronization Service UI, if it isn't already running. Select **Management Agents**.

- 1. Select the connector, and select **Export Management Agent**. Save the XML file, and the DLL and related software for your connector, to the Windows server that will be holding the ECMA Connector Host.

-At this point, the MIM Sync server is no longer needed.

-## Import a connector configuration

- 1. Install the ECMA Connector host and provisioning agent on a Windows Server, using the [provisioning users into SQL based applications](on-premises-sql-connector-configure.md#3-install-and-configure-the-azure-ad-connect-provisioning-agent) or [provisioning users into LDAP directories](on-premises-ldap-connector-configure.md#install-and-configure-the-azure-ad-connect-provisioning-agent) articles.

- 1. Sign in to the Windows server as the account that the Microsoft Entra ECMA Connector Host runs as.

- 1. Change to the directory C:\Program Files\Microsoft ECMA2host\Service\ECMA. Ensure there are one or more DLLs already present in that directory. Those DLLs correspond to Microsoft-delivered connectors.

- 1. Copy the MA DLL for your connector, and any of its prerequisite DLLs, to that same ECMA subdirectory of the Service directory.

- 1. Change to the directory C:\Program Files\Microsoft ECMA2Host\Wizard. Run the program Microsoft.ECMA2Host.ConfigWizard.exe to set up the ECMA Connector Host configuration.

- 1. A new window appears with a list of connectors. By default, no connectors will be present. Select **New connector**.

- 1. Specify the management agent XML file that was exported from MIM Sync earlier. Continue with the configuration and schema-mapping instructions from the section "Create a connector" in either the [provisioning users into SQL based applications](on-premises-sql-connector-configure.md#6-create-a-generic-sql-connector) or [provisioning users into LDAP directories](on-premises-ldap-connector-configure.md#configure-a-generic-ldap-connector) articles.

-## Next steps

-description: This document describes how to configure Microsoft Entra ID to provision users with external systems that offer Windows PowerShell based APIs.

-# Provisioning users into applications using PowerShell

-The following documentation provides configuration and tutorial information demonstrating how the generic PowerShell connector and the ECMA Connector Host can be used to integrate Microsoft Entra ID with external systems that offer Windows PowerShell based APIs.

-For additional information see [Windows PowerShell Connector technical reference](/microsoft-identity-manager/reference/microsoft-identity-manager-2016-connector-powershell)

-## Prerequisites for provisioning via PowerShell

-The following sections detail the prerequisites for this tutorial.

-### Download the PowerShell setup files

-[Download the PowerShell setup files from our GitHub repository](https://github.com/microsoft/MIMPowerShellConnectors/tree/master/src/ECMA2HostCSV). The setup files consist of the configuration file, the input file, schema file and the scripts used.

-### On-premises prerequisites

-The connector provides a bridge between the capabilities of the ECMA Connector Host and Windows PowerShell. Before you use the Connector, make sure you have the following on the server hosting the connector

-`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned`

-### Cloud requirements

-<a name='download-install-and-configure-the-azure-ad-connect-provisioning-agent-package'></a>

-## Download, install, and configure the Microsoft Entra Connect Provisioning Agent Package

-If you have already downloaded the provisioning agent and configured it for another on-premises application, then continue reading in the next section.

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Hybrid Identity Administrator](../roles/permissions-reference.md#hybrid-identity-administrator).

-1. Browse to **Identity** > **Hybrid management** > **Microsoft Entra Connect** > **Cloud sync** > **Agents**.

-

- :::image type="content" source="../../../includes/media/active-directory-cloud-sync-how-to-install/new-ux-1.png" alt-text="Screenshot of new UX screen." lightbox="../../../includes/media/active-directory-cloud-sync-how-to-install/new-ux-1.png":::

-1. Select **Download on-premises agent**, review the terms of service, then select **Accept terms & download**.

- > [!NOTE]

- > Please use different provisioning agents for on-premises application provisioning and Microsoft Entra Connect cloud sync / HR-driven provisioning. All three scenarios should not be managed on the same agent.

-1. Open the provisioning agent installer, agree to the terms of service, and select **next**.

-1. When the provisioning agent wizard opens, continue to the **Select Extension** tab and select **On-premises application provisioning** when prompted for the extension you want to enable.

-1. The provisioning agent uses the operating system's web browser to display a popup window for you to authenticate to Microsoft Entra ID, and potentially also your organization's identity provider. If you are using Internet Explorer as the browser on Windows Server, then you may need to add Microsoft web sites to your browser's trusted site list to allow JavaScript to run correctly.

-1. Provide credentials for a Microsoft Entra administrator when you're prompted to authorize. The user is required to have the Hybrid Identity Administrator or Global Administrator role.

-1. Select **Confirm** to confirm the setting. Once installation is successful, you can select **Exit**, and also close the Provisioning Agent Package installer.

-## Configure the On-premises ECMA app

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. Select **New application**.

-1. Search for the **On-premises ECMA app** application, give the app a name, and select **Create** to add it to your tenant.

-1. Navigate to the **Provisioning** page of your application.

-1. Select **Get started**.

-1. On the **Provisioning** page, change the mode to **Automatic**.

-1. On the **On-Premises Connectivity** section, select the agent that you just deployed and select **Assign Agent(s)**.

-1. Keep this browser window open, as you complete the next step of configuration using the configuration wizard.

-## Place the InputFile.txt and Schema.xml file in locations

-Before you can create the PowerShell connector for this tutorial, you need to copy the InputFile.txt and Schema.xml file into the correct locations. These files are the ones you needed to download in section [Download the PowerShell setup files](#download-the-powershell-setup-files).

- |File|location|

- |--|--|

- |InputFile.txt|`C:\Program Files\Microsoft ECMA2Host\Service\ECMA\MAData`|

- |Schema.xml|`C:\Program Files\Microsoft ECMA2Host\Service\ECMA`|

- <a name='configure-the-azure-ad-ecma-connector-host-certificate'></a>

-## Configure the Microsoft Entra ECMA Connector Host certificate

-1. On the Windows Server where the provisioning agent is installed, right click the **Microsoft ECMA2Host Configuration Wizard** from the start menu, and run as administrator. Running as a Windows administrator is necessary for the wizard to create the necessary Windows event logs.

-2. After the ECMA Connector Host Configuration starts, if it's the first time you have run the wizard, it will ask you to create a certificate. Leave the default port **8585** and select **Generate certificate** to generate a certificate. The autogenerated certificate will be self-signed as part of the trusted root. The certificate SAN matches the host name.

-3. Select **Save**.

-## Create the PowerShell Connector

-

-### General Screen

-1. Launch the Microsoft ECMA2Host Configuration Wizard from the start menu.

-2. At the top, select **Import** and select the configuration.xml file from step 1.

-3. The new connector should be created and appear in red. Click **Edit**.

-4. Generate a secret token used for authenticating Microsoft Entra ID to the connector. It should be 12 characters minimum and unique for each application. If you do not already have a secret generator, you can use a PowerShell command such as the following to generate an example random string.

- ```powershell

- -join (((48..90) + (96..122)) * 16 | Get-Random -Count 16 | % {[char]$_})

- ```

-5. On the **Properties** page, all of the information should be populated. The table is provided as reference. Click **Next**.

-

- |Property|Value|

- |--|--|

- |Name|The name you chose for the connector, which should be unique across all connectors in your environment. For example, `PowerShell`.|

- |Autosync timer (minutes)|120|

- |Secret Token|Enter your secret token here. It should be 12 characters minimum.|

- |Extension DLL|For the PowerShell connector, select **Microsoft.IAM.Connector.PowerShell.dll**.|

-### Connectivity

-The connectivity tab allows you to supply configuration parameters for connecting to a remote system. Configure the connectivity tab with the information provided in the table.

-|Parameter|Value|Purpose|

-|-|--|--|

-| Server | \<Blank\> | Server name that the connector should connect to. |

-| Domain | \<Blank\> |Domain of the credential to store for use when the connector is run.|

-|User| \<Blank\> | Username of the credential to store for use when the connector is run. |

-| Password | \<Blank\> | Password of the credential to store for use when the connector is run. |

-| Impersonate Connector Account |Unchecked| When true, the synchronization service runs the Windows PowerShell scripts in the context of the credentials supplied. When possible, it is recommended that the **$Credentials** parameter is passed to each script is used instead of impersonation.|

-| Load User Profile When Impersonating |Unchecked|Instructs Windows to load the user profile of the connectorΓÇÖs credentials during impersonation. If the impersonated user has a roaming profile, the connector does not load the roaming profile.|

-| Logon Type When Impersonating |None|Logon type during impersonation. For more information, see the [dwLogonType](/windows/win32/api/winbase/nf-winbase-logonusera#parameters) documentation. |

-|Signed Scripts Only |Unchecked| If true, the Windows PowerShell connector validates that each script has a valid digital signature. If false, ensure that the Synchronization Service serverΓÇÖs Windows PowerShell execution policy is RemoteSigned or Unrestricted.|

-|Common Module Script Name (with extension)|xADSyncPSConnectorModule.psm1|The connector allows you to store a shared Windows PowerShell module in the configuration. When the connector runs a script, the Windows PowerShell module is extracted to the file system so that it can be imported by each script.|

-|Common Module Script|[AD Sync PowerShell Connector Module code](https://github.com/microsoft/MIMPowerShellConnectors/blob/master/src/ECMA2HostCSV/Scripts/CommonModule.psm1) as value. This module will be automatically created by the ECMA2Host when the connector is running.||

-|Validation Script|\<Blank\>|The Validation Script is an optional Windows PowerShell script that can be used to ensure that connector configuration parameters supplied by the administrator are valid.|

-|Schema Script|[GetSchema code](https://github.com/microsoft/MIMPowerShellConnectors/blob/master/src/ECMA2HostCSV/Scripts/Schema%20Script.ps1) as value.||

-|Additional Config Parameter Names|FileName,Delimiter,Encoding|In addition to the standard configuration settings, you can define additional custom configuration settings that are specific to the instance of the Connector. These parameters can be specified at the connector, partition, or run step levels and accessed from the relevant Windows PowerShell script. |

-|Additional Encrypted Config Parameter Names|\<Blank\> ||

-### Capabilities

-The capabilities tab defines the behavior and functionality of the connector. The selections made on this tab cannot be modified when the connector has been created. Configure the capabilities tab with the information provided in the table.

-|Parameter|Value|Purpose|

-|-|--|--|

-|Distinguished Name Style|None|Indicates if the connector supports distinguished names and if so, what style. |

-|Export Type|ObjectReplace|Determines the type of objects that are presented to the Export script.|

-|Data Normalization|None|Instructs the Synchronization Service to normalize anchor attributes before they are provided to scripts. |

-|Object Confirmation|Normal|This is ignored.|

-|Use DN as Anchor|Unchecked|If the Distinguished Name Style is set to LDAP, the anchor attribute for the connector space is also the distinguished name. |

-|Concurrent Operations of Several Connectors|Checked|When checked, multiple Windows PowerShell connectors can run simultaneously. |

-|Partitions|Unchecked|When checked, the connector supports multiple partitions and partition discovery. |

-|Hierarchy|Unchecked|When checked, the connector supports an LDAP style hierarchical structure. |

-|Enable Import|Checked|When checked, the connector imports data via import scripts. |

-|Enable Delta Import|Unchecked|When checked, the connector can request deltas from the import scripts. |

-|Enable Export|Checked|When checked, the connector exports data via export scripts. |

-|Enable Full Export|Checked|Not supported. This will be ignored.|

-|No Reference Values In First Export Pass|Unchecked|When checked, reference attributes are exported in a second export pass. |

-|Enable Object Rename|Unchecked|When checked, distinguished names can be modified. |

-|Delete-Add As Replace|Checked|Not supported. This will be ignored.|

-|Enable Export Password in First Pass|Unchecked|Not supported. This will be ignored.|

-### Global Parameters

-The Global Parameters tab enables you to configure the Windows PowerShell scripts that are run by the connector. You can also configure global values for custom configuration settings defined on the Connectivity tab. Configure the global parameters tab with the information provided in the table.

-|Parameter|Value|

-|--|--|

-|Partition Script|\<Blank>|

-|Hierarchy Script|\<Blank>|

-|Begin Import Script|\<Blank>|

-|Import Script|[Paste the import script as the value](https://github.com/microsoft/MIMPowerShellConnectors/blob/master/src/ECMA2HostCSV/Scripts/Import%20Scripts.ps1)|

-|End Import Script|\<Blank>|

-|Begin Export Script|\<Blank>|

-|Export Script|[Paste the import script as the value](https://github.com/microsoft/MIMPowerShellConnectors/blob/master/src/ECMA2HostCSV/Scripts/Export%20Script.ps1)|

-|End Export Script|\<Blank>|

-|Begin Password Script|\<Blank>|

-|Password Extension Script|\<Blank>|

-|End Password Script|\<Blank>|

-|FileName_Global|InputFile.txt|

-|Delimiter_Global|;|

-|Encoding_Global|\<Blank> (defaults to UTF8)|

-### Partitions, Run Profiles, Export, FullImport

-Keep the defaults and click **next**.

-### Object types

-Configure the object types tab with the information provided in the table.

-|Parameter|Value|

-|--|--|

-|Target Object|Person|

-|Anchor|AzureObjectID|

-|Query Attribute|AzureObjectID|

-|DN|AzureObjectID|

-### Select Attributes

-Ensure that the following attributes are selected:

-### Deprovisioning

-On the Deprovisioning page, you can specify if you wish to have Microsoft Entra ID remove users from the directory when they go out of scope of the application. If so, under Disable flow, select Delete, and under Delete flow, select Delete. If Set attribute value is chosen, the attributes selected on the previous page won't be available to select on the Deprovisioning page.

-## Ensure ECMA2Host service is running and can read from file via PowerShell

-Follow these steps to confirm that the connector host has started and has identified any existing users from the target system.

-1. On the server running the Microsoft Entra ECMA Connector Host, select **Start**.

-2. Select **run** if needed, then enter **services.msc** in the box.

-3. In the **Services** list, ensure that **Microsoft ECMA2Host** is present and running. If it is not running, select **Start**.

-4. On the server running the Microsoft Entra ECMA Connector Host, launch PowerShell.

-5. Change to the folder where the ECMA host was installed, such as `C:\Program Files\Microsoft ECMA2Host`.

-6. Change to the subdirectory `Troubleshooting`.

-7. Run the script `TestECMA2HostConnection.ps1` in the directory as shown, and provide as arguments the connector name and the `ObjectTypePath` value `cache`. If your connector host is not listening on TCP port 8585, then you may also need to provide the `-Port` argument as well. When prompted, type the secret token configured for that connector.

- ```

- PS C:\Program Files\Microsoft ECMA2Host\Troubleshooting> $cout = .\TestECMA2HostConnection.ps1 -ConnectorName PowerShell -ObjectTypePath cache; $cout.length -gt 9

- Supply values for the following parameters:

- SecretToken: ************

- ```

-8. If the script displays an error or warning message, then check that the service is running, and the connector name and secret token match those values you configured in the configuration wizard.

-9. If the script displays the output `False`, then the connector has not seen any entries in the source target system for existing users. If this is a new target system installation, then this behavior is to be expected, and you can continue at the next section.

-10. However, if the target system already contains one or more users but the script displayed `False`, then this status indicates the connector could not read from the target system. If you attempt to provision, then Microsoft Entra ID may not correctly match users in that source directory with users in Microsoft Entra ID. Wait several minutes for the connector host to finish reading objects from the existing target system, and then rerun the script. If the output continues to be `False`, then check the configuration of your connector and the permissions in the target system are allowing the connector to read existing users.

-<a name='test-the-connection-from-azure-ad-to-the-connector-host'></a>

-## Test the connection from Microsoft Entra ID to the connector host

-1. Return to the web browser window where you were configuring the application provisioning in the portal.

- > [!NOTE]

- > If the window had timed out, then you need to re-select the agent.

-

- 1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

- 1. Browse to **Identity** > **Applications** > **Enterprise applications**.

- 1. Select the **On-premises ECMA app** application.

- 1. Select **Provisioning**.

- 1. If **Get started** appears, then change the mode to **Automatic**, on the **On-Premises Connectivity** section, select the agent that you just deployed and select **Assign Agent(s)**, and wait 10 minutes. Otherwise go to **Edit Provisioning**.

-1. Under the **Admin credentials** section, enter the following URL. Replace the `connectorName` portion with the name of the connector on the ECMA host, such as `PowerShell`. If you provided a certificate from your certificate authority for the ECMA host, then replace `localhost` with the host name of the server where the ECMA host is installed.

- |Property|Value|

- |--|--|

- |Tenant URL|https://localhost:8585/ecma2host_connectorName/scim|

-1. Enter the **Secret Token** value that you defined when you created the connector.

- > [!NOTE]

- > If you just assigned the agent to the application, please wait 10 minutes for the registration to complete. The connectivity test won't work until the registration completes. Forcing the agent registration to complete by restarting the provisioning agent on your server can speed up the registration process. Go to your server, search for **services** in the Windows search bar, identify the **Microsoft Entra Connect Provisioning Agent** service, right-click the service, and restart.

-1. Select **Test Connection**, and wait one minute.

-1. After the connection test is successful and indicates that the supplied credentials are authorized to enable provisioning, select **Save**.

-## Configure the application connection

-Return to the web browser window where you were configuring the application provisioning.

-> [!NOTE]

-> If the window had timed out, then you need to re-select the agent.

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. Select the **On-premises ECMA app** application.

-1. Select **Provisioning**.

-1. If **Get started** appears, then change the mode to **Automatic**, on the **On-Premises Connectivity** section, select the agent that you deployed and select **Assign Agent(s)**. Otherwise go to **Edit Provisioning**.

-1. Under the **Admin credentials** section, enter the following URL. Replace the `{connectorName}` portion with the name of the connector on the ECMA connector host, such as **CSV**. The connector name is case sensitive and should be the same case as was configured in the wizard. You can also replace `localhost` with your machine hostname.

- |Property|Value|

- |--|--|

- |Tenant URL| `https://localhost:8585/ecma2host_CSV/scim`|

-1. Enter the **Secret Token** value that you defined when you created the connector.

- > [!NOTE]

- > If you just assigned the agent to the application, please wait 10 minutes for the registration to complete. The connectivity test won't work until the registration completes. Forcing the agent registration to complete by restarting the provisioning agent on your server can speed up the registration process. Go to your server, search for **services** in the Windows search bar, identify the **Microsoft Entra Connect Provisioning Agent Service**, right-click the service, and restart.

-1. Select **Test Connection**, and wait one minute.

-1. After the connection test is successful and indicates that the supplied credentials are authorized to enable provisioning, select **Save**.

-## Configure attribute mappings

-Now you need to map attributes between the representation of the user in Microsoft Entra ID and the representation of a user in the on-premises InputFile.txt.

-You'll use the Azure portal to configure the mapping between the Microsoft Entra user's attributes and the attributes that you previously selected in the ECMA Host configuration wizard.

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. Select the **On-premises ECMA app** application.

-1. Select **Provisioning**.

-1. Select **Edit provisioning**, and wait 10 seconds.

-1. Expand **Mappings** and select **Provision Microsoft Entra users**. If this is the first time you've configured the attribute mappings for this application, there will be only one mapping present, for a placeholder.

-1. To confirm that the schema is available in Microsoft Entra ID, select the **Show advanced options** checkbox and select **Edit attribute list for ScimOnPremises**. Ensure that all the attributes selected in the configuration wizard are listed. If not, then wait several minutes for the schema to refresh, and then reload the page. Once you see the attributes listed, then cancel from this page to return to the mappings list.

-1. Now, on the click on the **userPrincipalName** PLACEHOLDER mapping. This mapping is added by default when you first configure on-premises provisioning. Change the value to match the following:

-

- |Mapping type|Source attribute|Target attribute|

- |--|--|--|

- |Direct|userPrincipalName|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:UserName|

-

-1. Now select **Add New Mapping**, and repeat the next step for each mapping.

-1. Specify the source and target attributes for each of the mappings in the following table.

- |Mapping type|Source attribute|Target attribute|

- |--|--|--|

- |Direct|objectId|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:AzureObjectID|

- |Direct|userPrincipalName|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:UserName|

- |Direct|displayName|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:DisplayName|

- |Direct|employeeId|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:EmployeeId|

- |Direct|jobTitle|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:Title|

- |Direct|mail|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:Email|

- |Expression|Switch([IsSoftDeleted],, "False", "True", "True", "False")|urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:IsActive|

-

- :::image type="content" source="media/on-premises-powershell-connector/powershell-8.png" alt-text="Screenshot of attribute mappings." lightbox="media/on-premises-powershell-connector/powershell-8.png":::

-1. Once all of the mappings have been added, select **Save**.

-## Assign users to an application

-Now that you have the Microsoft Entra ECMA Connector Host talking with Microsoft Entra ID, and the attribute mapping configured, you can move on to configuring who's in scope for provisioning.

->[!IMPORTANT]

->If you were signed in using a Hybrid Identity Administrator role, you need to sign-out and sign-in with an account that has the Application Administrator, Cloud Application Administrator or Global Administrator role, for this section. The Hybrid Identity Administrator role does not have permissions to assign users to applications.

-If there are existing users in the InputFile.txt, then you should create application role assignments for those existing users. To learn more about how to create application role assignments in bulk, see [governing an application's existing users in Microsoft Entra ID](../governance/identity-governance-applications-existing-users.md).

-Otherwise, if there are no current users of the application, then select a test user from Microsoft Entra who will be provisioned to the application.

-1. Ensure that the user selected has all the properties, mapped to the required attributes of the schema.

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. Select the **On-premises ECMA app** application.

-1. On the left, under **Manage**, select **Users and groups**.

-1. Select **Add user/group**.

-1. Under **Users**, select **None Selected**.

-1. Select users from the right and select the **Select** button.

-1. Now select **Assign**.

-## Test provisioning

-Now that your attributes are mapped and users are assigned, you can test on-demand provisioning with one of your users.

-

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. Select the **On-premises ECMA app** application.

-1. Select **Provisioning**.

-1. Select **Provision on demand**.

-1. Search for one of your test users, and select **Provision**.

-1. After several seconds, then the message **Successfully created user in target system** appears, with a list of the user attributes.

-## Start provisioning users

-1. After on-demand provisioning is successful, change back to the provisioning configuration page. Ensure that the scope is set to only assigned users and groups, turn provisioning **On**, and select **Save**.

-2. Wait several minutes for provisioning to start. It might take up to 40 minutes. After the provisioning job has been completed, as described in the next section, if you're done testing, you can change the provisioning status to **Off**, and select **Save**. This action stops the provisioning service from running in the future.

-## Next steps

-description: This document describes how to configure Microsoft Entra ID to provision users into SAP ERP Central Component (SAP ECC, formerly SAP R/3) with NetWeaver AS ABAP 7.0 or later.

-# Configuring Microsoft Entra ID to provision users into SAP ECC with NetWeaver AS ABAP 7.0 or later

-The following documentation provides configuration and tutorial information demonstrating how to provision users from Microsoft Entra ID into SAP ERP Central Component (SAP ECC, formerly SAP R/3) with NetWeaver 7.0 or later. If you are using other versions such as SAP R/3, you can still use the guides provided in the [download center](https://www.microsoft.com/download/details.aspx?id=51495) as a reference to build your own template and configure provisioning.

-## Next steps

-description: This article describes how to use the Microsoft Entra provisioning service to provision users into an on-premises app that's SCIM enabled.

-# Microsoft Entra on-premises application provisioning to SCIM-enabled apps

-The Microsoft Entra provisioning service supports a [SCIM 2.0](https://techcommunity.microsoft.com/t5/security-compliance-and-identity/provisioning-with-scim-getting-started/ba-p/880010) client that can be used to automatically provision users into cloud or on-premises applications. This article outlines how you can use the Microsoft Entra provisioning service to provision users into an on-premises application that's SCIM enabled. If you want to provision users into non-SCIM on-premises applications that use SQL as a data store, see the [Microsoft Entra ECMA Connector Host Generic SQL Connector tutorial](tutorial-ecma-sql-connector.md). If you want to provision users into cloud apps such as DropBox and Atlassian, review the app-specific [tutorials](../saas-apps/tutorial-list.md).

-

-## Prerequisites

-<a name='download-install-and-configure-the-azure-ad-connect-provisioning-agent-package'></a>

-## Download, install, and configure the Microsoft Entra Connect Provisioning Agent Package

-If you have already downloaded the provisioning agent and configured it for another on-premises application, then continue reading in the next section.

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Hybrid Identity Administrator](../roles/permissions-reference.md#hybrid-identity-administrator).

-1. Browse to **Identity** > **Hybrid management** > **Microsoft Entra Connect** > **Cloud sync** > **Agents**.

- :::image type="content" source="../../../includes/media/active-directory-cloud-sync-how-to-install/new-ux-1.png" alt-text="Screenshot of new UX screen." lightbox="../../../includes/media/active-directory-cloud-sync-how-to-install/new-ux-1.png":::

-1. Select **Download on-premises agent**, and select **Accept terms & download**.

- >[!NOTE]

- >Please use different provisioning agents for on-premises application provisioning and Microsoft Entra Connect cloud sync / HR-driven provisioning. All three scenarios should not be managed on the same agent.

- 1. Open the provisioning agent installer, agree to the terms of service, and select **next**.

- 1. When the provisioning agent wizard opens, continue to the **Select Extension** tab and select **On-premises application provisioning** when prompted for the extension you want to enable.

- 1. The provisioning agent will use the operating system's web browser to display a popup window for you to authenticate to Microsoft Entra ID, and potentially also your organization's identity provider. If you are using Internet Explorer as the browser on Windows Server, then you may need to add Microsoft web sites to your browser's trusted site list to allow JavaScript to run correctly.

- 1. Provide credentials for a Microsoft Entra administrator when you're prompted to authorize. The user is required to have the Hybrid Identity Administrator or Global Administrator role.

- 1. Select **Confirm** to confirm the setting. Once installation is successful, you can select **Exit**, and also close the Provisioning Agent Package installer.

-

-## Provisioning to SCIM-enabled application

-Once the agent is installed, no further configuration is necessary on-premises, and all provisioning configurations are then managed from the portal. Repeat the below steps for every on-premises application being provisioned via SCIM.

-

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. Add the **On-premises SCIM app** from the [gallery](../manage-apps/add-application-portal.md).

-1. From the left hand menu navigate to the **Provisioning** option and select **Get started**.

-1. Select **Automatic** from the dropdown list and expand the **On-Premises Connectivity** option.

-1. Select the agent that you installed from the dropdown list and select **Assign Agent(s)**.

-1. Now either wait 10 minutes or restart the **Microsoft Entra Connect Provisioning Agent** before proceeding to the next step & testing the connection.

-1. In the **Tenant URL** field, provide the SCIM endpoint URL for your application. The URL is typically unique to each target application and must be resolvable by DNS. An example for a scenario where the agent is installed on the same host as the application is https://localhost:8585/scim

- 

-1. Select **Test Connection**, and save the credentials. The application SCIM endpoint must be actively listening for inbound provisioning requests, otherwise the test will fail. Use the steps [here](on-premises-ecma-troubleshoot.md#troubleshoot-test-connection-issues) if you run into connectivity issues.

- > [!NOTE]

- > If the test connection fails, you will see the request made. Please note that while the URL in the test connection error message is truncated, the actual request sent to the application contains the entire URL provided above.

-1. Configure any [attribute mappings](customize-application-attributes.md) or [scoping](define-conditional-rules-for-provisioning-user-accounts.md) rules required for your application.

-1. Add users to scope by [assigning users and groups](../manage-apps/add-application-portal-assign-users.md) to the application.

-1. Test provisioning a few users [on demand](provision-on-demand.md).

-1. Add more users into scope by assigning them to your application.

-1. Go to the **Provisioning** pane, and select **Start provisioning**.

-1. Monitor using the [provisioning logs](../reports-monitoring/concept-provisioning-logs.md).

-The following video provides an overview of on-premises provisioning.

-> [!VIDEO https://www.youtube.com/embed/QdfdpaFolys]

-## Additional requirements

-* Ensure your [SCIM](https://techcommunity.microsoft.com/t5/security-compliance-and-identity/provisioning-with-scim-getting-started/ba-p/880010) implementation meets the [Microsoft Entra SCIM requirements](use-scim-to-provision-users-and-groups.md).

-

- Microsoft Entra ID offers open-source [reference code](https://github.com/AzureAD/SCIMReferenceCode/wiki) that developers can use to bootstrap their SCIM implementation. The code is as is.

-* Support the /schemas endpoint to reduce configuration required in the Azure portal.

-## Next steps

-description: Provisioning users into SQL based applications using the ECMA Connector host

-# Provisioning users into SQL based applications

-The following documentation provides configuration and tutorial information demonstrating how the generic SQL connector and the ECMA Connector Host can be used with a SQL Server.

-## Next steps

-description: This document describes how to configure Microsoft Entra ID to provision users with external systems that offer web services based APIs.

-# Provisioning with the web services connector

-The following documentation provides information about the generic web services connector. Microsoft Entra ID Governance supports provisioning accounts into various applications such as SAP ECC, Oracle eBusiness Suite, and line of business applications that expose REST or SOAP APIs. Customers that have previously deployed MIM to connect to these applications can easily switch to using the lightweight Microsoft Entra provisioning agent, while reusing the same web services connector built for MIM.

-## Capabilities supported

-> [!div class="checklist"]

-> - Create users in your application.

-> - Remove users in your application when they don't need access anymore.

-> - Keep user attributes synchronized between Microsoft Entra ID and your application.

-> - Discover the schema for your application.

-The web services connector implements the following functionalities:

- - Assignment of parameters from connector space to web service functions.

- - Assignment of parameters from web service functions to the connector space.

-## Documentation for popular applications

-Integrations with popular applications such as [SAP ECC 7.0](on-premises-sap-connector-configure.md) and Oracle eBusiness Suite can be found [here](https://www.microsoft.com/download/details.aspx?id=51495). You can also configure a template to connect to your own [rest or SOAP API](/microsoft-identity-manager/reference/microsoft-identity-manager-2016-ma-ws).

-For more information, see [the Overview of the generic Web Service connector](/microsoft-identity-manager/reference/microsoft-identity-manager-2016-ma-ws) in the MIM documentation library.

-## Next steps

-description: Use partner driven integrations to provision accounts into all your applications.

-# Partner-driven provisioning integrations

-The Microsoft Entra provisioning service allows you to provision users and groups into both [SaaS](user-provisioning.md) and [on-premises](on-premises-scim-provisioning.md) applications. There are four integration paths:

-**Option 1 - Microsoft Entra Application Gallery:**

-Popular third party applications, such as Dropbox, Snowflake, and Workplace by Facebook, are made available for customers through the Microsoft Entra application gallery. New applications can easily be onboarded to the gallery using the [application network portal](../manage-apps/v2-howto-app-gallery-listing.md).

-**Option 2 - Implement a SCIM compliant API for your application:**

-If your line-of-business application supports the [SCIM](https://aka.ms/scimoverview) standard, it can easily be integrated with the [Microsoft Entra SCIM client](use-scim-to-provision-users-and-groups.md).

- [](media/partner-driven-integrations/scim-compliant-api-1.png#lightbox)

-**Option 3 - Use Microsoft Graph:**

-Many new applications use Microsoft Graph to retrieve users, groups and other resources from Microsoft Entra ID. You can learn more about what scenarios to use [SCIM and Graph](scim-graph-scenarios.md) in.

-**Option 4 - Use partner-driven connectors:**

-In cases where an application doesn't support SCIM, partners have built [custom ECMA connectors](on-premises-custom-connector.md) and SCIM gateways to integrate Microsoft Entra ID with numerous applications. **This document serves as a place for partners to attest to integrations that are compatible with Microsoft Entra ID, and for customers to discover these partner-driven integrations.** Custom ECMA connectors and SCIM gateways are built, maintained, and owned by the third-party vendor.

- [](media/partner-driven-integrations/partner-driven-connectors-1.png#lightbox)

-## Available partner-driven integrations

-The descriptions and lists of applications below are provided by the partners themselves. You can use the lists of applications supported to identify a partner that you may want to contact and learn more about.

-### IDMWORKS

-#### Description

-We Are Experts In Identity & Access Management and Data Center Management.

-The Microsoft Entra platform integrates with IDMWORKS IdentityForge (IDF) Gateway for user lifecycle management for Mainframe systems (RACF, Top Secret, ACF2), Midrange system (AS400), Healthcare applications (EPIC/Cerner), Linux/Unix servers, Databases, and dozens of on-premises and cloud applications. IdentityForge provides a central, standardized integration engine and modern identity store that serves as a trusted source for all lifecycle management.

-The IDF Gateway for Microsoft Entra ID provides lifecycle management for import sources and provisioning target systems that are not covered by the Microsoft Entra connector portfolio like Mainframe systems (RACF, Top Secret, ACF2) or Healthcare applications (EPIC/Cerner). The IDF Gateway powers Microsoft Entra identity lifecycle management (LCM) to continuously synchronize user account information from Mainframe/Healthcare sources and to automate the account provisioning lifecycle use cases like create, read (import), update, deactivate, delete user accounts and perform group management.

-#### Contact information

-* Company website: https://www.idmworks.com/identity-forge

-* Contact information: https://www.idmworks.com/contacts/

-#### Popular applications supported

-Leading provider of Mainframe, Healthcare and ERP integrations. More can be found at https://www.idmworks.com/identity-forge/

-* IBM RACF

-* CA Top Secret

-* CA ACF2

-* IBM i (AS/400)

-* HP NonStop

-* EPIC

-* SAP ECC

-### UNIFY Solutions

-#### Description

-UNIFY Solutions is the leading provider of Identity, Access, Security and Governance solutions.

-#### Contact information

-* Company website: https://unifysolutions.net/identity/unifyconnect

-* Contact information: https://unifysolutions.net/contact/

-#### Popular applications supported

-* Aurion People & Payroll

-* Frontier Software chris21

-* TechnologyOne HR

-* Ascender HCM

-* Fusion5 EmpowerHR

-* SAP ERP Human Capital Management

-## How-to add partner-driven integrations to this document

-If you have built a SCIM Gateway and would like to add it to this list, follow the steps below.

-1. Review the Microsoft Entra SCIM [documentation](use-scim-to-provision-users-and-groups.md) to understand the Microsoft Entra SCIM implementation.

-1. Test compatibility between the Microsoft Entra SCIM client and your SCIM gateway.

-1. Click the pencil at the top of this document to edit the article

-1. Once you're redirected to GitHub, click the pencil at the top of the article to start making changes

-1. Make changes in the article using the Markdown language and create a pull request. Make sure to provide a description for the pull request.

-1. An admin of the repository will review and merge your changes so that others can view them.

-## Guidelines

-* Add any new partners in alphabetical order.

-* Limit your entries to 500 words.

-* Ensure that you provide contact information for customers to learn more.

-* To avoid duplication, only include applications that don't already have out of the box provisioning connectors in the [Microsoft Entra application gallery](../saas-apps/tutorial-list.md).

-## Disclaimer

-For independent software vendors: The Microsoft Entra Application Gallery Terms & Conditions, excluding Sections 2ΓÇô4, apply to this Partner-Driven Integrations Catalog (the ΓÇ£Integrations CatalogΓÇ¥). References to the ΓÇ£GalleryΓÇ¥ shall be read as the ΓÇ£Integrations CatalogΓÇ¥ and references to an ΓÇ£AppΓÇ¥ shall be read as ΓÇ£IntegrationΓÇ¥.

-If you don't agree with these terms, you shouldn't submit your Integration for listing in the Integrations Catalog. If you submit an Integration to the Integrations Catalog, you agree that you or the entity you represent (ΓÇ£YOUΓÇ¥ or ΓÇ£YOURΓÇ¥) is bound by these terms.

-

-Microsoft reserves the right to accept or reject your proposed Integration in its sole discretion and reserves the right to determine the manner in which Apps are presented, promoted, or featured in this Integrations Catalog.

-description: Guidance for planning and executing automatic user provisioning in Microsoft Entra ID

-# Plan an automatic user provisioning deployment in Microsoft Entra ID

-Many organizations rely on software as a service (SaaS) applications such as ServiceNow, Zscaler, and Slack for end-user productivity. Historically IT staff has relied on manual provisioning methods such as uploading CSV files, or using custom scripts to securely manage user identities in each SaaS application. These processes are error prone, insecure, and hard to manage.

-Microsoft Entra automatic user provisioning simplifies this process by securely automating the creation, maintenance, and removal of user identities in SaaS applications based on business rules. This automation allows you to effectively scale your identity management systems on both cloud-only and hybrid environments as you expand their dependency on cloud-based solutions.

-See [Automate user provisioning and deprovisioning to SaaS applications with Microsoft Entra ID](../app-provisioning/user-provisioning.md) to better understand the functionality.

-## Learn

-User provisioning creates a foundation for ongoing identity governance and enhances the quality of business processes that rely on authoritative identity data.

-### Key benefits

-The key benefits of enabling automatic user provisioning are:

-* **Increased productivity**. You can manage user identities across SaaS applications with a single user provisioning management interface. This interface has a single set of provisioning policies.

-* **Manage risk**. You can increase security by automating changes based on employee status or group memberships that define roles and/or access.

-* **Address compliance and governance**. Microsoft Entra ID supports native audit logs for every user provisioning request. Requests are executed in both the source and target systems. Audit logs let you track who has access to applications from a single screen.

-* **Reduce cost**. Automatic user provisioning reduces costs by avoiding inefficiencies and human error associated with manual provisioning. It reduces the need for custom-developed user provisioning solutions, scripts, and audit logs.

-### Licensing

-Microsoft Entra ID provides self-service integration of any application using templates provided in the application gallery menu. For a full list of license requirements, see [Microsoft Entra pricing page](https://www.microsoft.com/security/business/identity-access-management/azure-ad-pricing).

-#### Application licensing

-You need the appropriate licenses for the application(s) you want to automatically provision. Discuss with the application owners whether the users assigned to the application have the proper licenses for their application roles. If Microsoft Entra ID manages automatic provisioning based on roles, the roles assigned in Microsoft Entra ID must align to application licenses. Incorrect licenses owned in the application may lead to errors during the provisioning/updating of a user.

-### Terms

-This article uses the following terms:

-* CRUD operations - Actions taken on user accounts: Create, Read, Update, Delete.

-* Single sign-on (SSO) - The ability for a user to sign-on once and access all SSO enabled applications. In the context of user provisioning, SSO is a result of users having a single account to access all systems that use automatic user provisioning.

-* Source system - The repository of users that the Microsoft Entra ID provisions from. Microsoft Entra ID is the source system for most preintegrated provisioning connectors. However, there are some exceptions for cloud applications such as SAP, Workday, and AWS. For example, see [User provisioning from Workday to AD](../saas-apps/workday-inbound-tutorial.md).

-* Target system - The repository of users that the Microsoft Entra ID provisions to. The Target system is typically a SaaS application such as ServiceNow, Zscaler, and Slack. The target system can also be an on-premises system such as AD.

-* [System for Cross-domain Identity Management (SCIM)](https://aka.ms/scimoverview) - An open standard that allows for the automation of user provisioning. SCIM communicates user identity data between identity providers and service providers. Microsoft is an example of an identity provider. Salesforce is an example of a service provider. Service providers require user identity information and an identity provider fulfills that need. SCIM is the mechanism the identity provider and service provider use to send information back and forth.

-### Training resources

-| Resources| Link and Description |

-| - | - |

-| On-demand webinars| [Manage your Enterprise Applications with Microsoft Entra ID](https://info.microsoft.com/CO-AZUREPLAT-WBNR-FY18-03Mar-06-ManageYourEnterpriseApplicationsOption1-MCW0004438_02OnDemandRegistration-ForminBody.html)<br>ΓÇÄLearn how Microsoft Entra ID can help you achieve SSO to your enterprise SaaS applications and best practices for controlling access. |

-| Videos| [What is user provisioning in Active Azure Directory?](https://youtu.be/_ZjARPpI6NI) <br> [How to deploy user provisioning in Active Azure Directory?](https://youtu.be/pKzyts6kfrw) <br> [Integrating Salesforce with Microsoft Entra ID: How to automate User Provisioning](https://youtu.be/MAy8s5WSe3A)

-| Online courses| SkillUp Online: [Managing Identities](https://skillup.online/courses/course-v1:Microsoft+AZ-100.5+2018_T3/) <br> Learn how to integrate Microsoft Entra ID with many SaaS applications and to secure user access to those applications. |

-| Books| [Modern Authentication with Microsoft Entra ID for Web Applications (Developer Reference) 1st Edition](https://www.amazon.com/Authentication-Directory-Applications-Developer-Reference/dp/0735696942/ref=sr_1_fkmr0_1?keywords=Azure+multifactor+authentication&qid=1550168894&s=gateway&sr=8-1-fkmr0). <br> ΓÇÄThis is an authoritative, deep-dive guide to building Active Directory authentication solutions for these new environments. |

-| Tutorials| See the [list of tutorials on how to integrate SaaS apps with Microsoft Entra ID](../saas-apps/tutorial-list.md). |

-| FAQ| [Frequently asked questions](../app-provisioning/user-provisioning.md) on automated user provisioning |

-### Solution architectures

-The Microsoft Entra provisioning service provisions users to SaaS apps and other systems by connecting to user management API endpoints provided by each application vendor. These user management API endpoints allow Microsoft Entra ID to programmatically create, update, and remove users.

-#### Automatic user provisioning for hybrid enterprises

-In this example, users and or groups are created in an HR database connected to an on-premises directory. The Microsoft Entra provisioning service manages automatic user provisioning to the target SaaS applications.

- 

-**Description of workflow:**

-1. Users/groups are created in an on-premises HR application/system, such as SAP.

-1. **Microsoft Entra Connect agent** runs scheduled synchronizations of identities (users and groups) from the local AD to Microsoft Entra ID.

-1. **Microsoft Entra provisioning service** begins an [initial cycle](../app-provisioning/user-provisioning.md) against the source system and target system.

-1. **Microsoft Entra provisioning service** queries the source system for any users and groups changed since the initial cycle, and pushes changes in [incremental cycles](../app-provisioning/user-provisioning.md).

-#### Automatic user provisioning for cloud-only enterprises

-In this example, user creation occurs in Microsoft Entra ID and the Microsoft Entra provisioning service manages automatic user provisioning to the target (SaaS) applications.

-

-**Description of workflow:**

-1. Users/groups are created in Microsoft Entra ID.

-1. **Microsoft Entra provisioning service** begins an [initial cycle](../app-provisioning/user-provisioning.md) against the source system and target system.

-1. **Microsoft Entra provisioning service** queries the source system for any users and groups updated since the initial cycle, and performs any [incremental cycles](../app-provisioning/user-provisioning.md).

-#### Automatic user provisioning for cloud HR applications

-In this example, the users and or groups are created in a cloud HR application like such as Workday and SuccessFactors. The Microsoft Entra provisioning service and Microsoft Entra Connect provisioning agent provisions the user data from the cloud HR app tenant into AD. Once the accounts are updated in AD, it's synced with Microsoft Entra ID through Microsoft Entra Connect, and the email addresses and username attributes can be written back to the cloud HR app tenant.

-

-1. **HR team** performs the transactions in the cloud HR app tenant.

-2. **Microsoft Entra provisioning service** runs the scheduled cycles from the cloud HR app tenant and identifies changes that need to be processed for sync with AD.

-3. **Microsoft Entra provisioning service** invokes the Microsoft Entra Connect provisioning agent with a request payload containing AD account create/update/enable/disable operations.

-4. **Microsoft Entra Connect provisioning agent** uses a service account to manage AD account data.

-5. **Microsoft Entra Connect** runs delta sync to pull updates in AD.

-6. **AD** updates are synced with Microsoft Entra ID.

-7. **Microsoft Entra provisioning service** writebacks email attribute and username from Microsoft Entra ID to the cloud HR app tenant.

-## Plan the deployment project

-Consider your organizational needs to determine the strategy for deploying user provisioning in your environment.

-### Engage the right stakeholders

-When technology projects fail, it's typically because of mismatched expectations on impact, outcomes, and responsibilities. To avoid these pitfalls, [ensure you're engaging the right stakeholders](../architecture/deployment-plans.md) and that stakeholder roles in the project are well understood by documenting the stakeholders and their project input and accountabilities.

-### Plan communications

-Communication is critical to the success of any new service. Proactively communicate to your users about their experience, how the experience is changing, when to expect any change, and how to gain support if they experience issues.

-### Plan a pilot

-We recommend that the initial configuration of automatic user provisioning is in a test environment with a small subset of users before scaling it to all users in production. See [best practices](../architecture/deployment-plans.md#best-practices-for-a-pilot) for running a pilot.

-#### Best practices for a pilot  

-A pilot allows you to test with a small group before deploying a capability for everyone. Ensure that as part of your testing, each use case within your organization is thoroughly tested.

-In your first wave, target IT, usability, and other appropriate users who can test and provide feedback. Use this feedback to further develop the communications and instructions you send to your users, and to give insights into the types of issues your support staff may see.

-Widen the rollout to larger groups of users by increasing the scope of the group(s) targeted. Increasing the scope of the group(s) is done through [dynamic group membership](../enterprise-users/groups-dynamic-membership.md), or by manually adding users to the targeted group(s).

-## Plan application connections and administration

-Use the Microsoft Entra admin center to view and manage all the applications that support provisioning. See [Finding your apps in the portal](../app-provisioning/configure-automatic-user-provisioning-portal.md).

-### Determine the type of connector to use

-The actual steps required to enable and configure automatic provisioning vary depending on the application. If the application you wish to automatically provision is listed in the [Microsoft Entra SaaS app gallery](../saas-apps/tutorial-list.md), then you should select the [app-specific integration tutorial](../saas-apps/tutorial-list.md) to configure its preintegrated user provisioning connector.

-If not, follow the steps:

-1. [Create a request](../manage-apps/v2-howto-app-gallery-listing.md) for a preintegrated user provisioning connector. Our team works with you and the application developer to onboard your application to our platform if it supports SCIM.

-1. Use the [BYOA SCIM](../app-provisioning/use-scim-to-provision-users-and-groups.md) generic user provisioning support for the app. Using SCIM is a requirement for Microsoft Entra ID to provision users to the app without a preintegrated provisioning connector.

-1. If the application is able to utilize the BYOA SCIM connector, then refer to [BYOA SCIM integration tutorial](../app-provisioning/use-scim-to-provision-users-and-groups.md) to configure the BYOA SCIM connector for the application.

-For more information, see [What applications and systems can I use with Microsoft Entra automatic user provisioning?](../app-provisioning/user-provisioning.md)

-### Collect information to authorize application access

-Setting up automatic user provisioning is a per-application process. For each application, you need to provide [administrator credentials](../app-provisioning/configure-automatic-user-provisioning-portal.md) to connect to the target systemΓÇÖs user management endpoint.

-The image shows one version of the required admin credentials:

-

-While some applications require the admin username and password, others may require a bearer token.

-## Plan user and group provisioning

-If you enable user provisioning for enterprise apps, the [Microsoft Entra admin center](https://entra.microsoft.com) controls its attribute values through attribute mapping.

-### Determine operations for each SaaS app

-Each application may have unique user or group attributes that must be mapped to the attributes in your Microsoft Entra ID. Application may have only a subset of CRUD operations available.

-For each application, document the following information:

-* CRUD provisioning operations to be performed on the user and or Group objects for the target systems. For example, each SaaS app business owner may not want all possible operations.

-* Attributes available in the source system

-* Attributes available in the target system

-* Mapping of attributes between systems.

-### Choose which users and groups to provision

-Before implementing automatic user provisioning, you must determine the users and groups to be provisioned to your application.

-* Use [scoping filters](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md) to define attribute-based rules that determine which users are provisioned to an application.

-* Next, use [user and group assignments](../manage-apps/assign-user-or-group-access-portal.md) as needed for more filtering.

-### Define user and group attribute mapping

-To implement automatic user provisioning, you need to define the user and group attributes that are needed for the application. There's a preconfigured set of attributes and [attribute-mappings](../app-provisioning/configure-automatic-user-provisioning-portal.md) between Microsoft Entra user objects, and each SaaS applicationΓÇÖs user objects. Not all SaaS apps enable group attributes.

-Microsoft Entra ID supports by direct attribute-to-attribute mapping, providing constant values, or [writing expressions for attribute mappings](../app-provisioning/functions-for-customizing-application-data.md). This flexibility gives you fine control over what is populated in the targeted system's attribute. You can use [Microsoft Graph API](../app-provisioning/export-import-provisioning-configuration.md) and Graph Explorer to export your user provisioning attribute mappings and schema to a JSON file and import it back into Microsoft Entra ID.

-For more information, see [Customizing User Provisioning Attribute-Mappings for SaaS Applications in Microsoft Entra ID](../app-provisioning/customize-application-attributes.md).

-### Special considerations for user provisioning

-Consider the following to reduce issues post-deployment:

-* Ensure that the attributes used to map user/group objects between source and target applications are resilient. They shouldn't cause users/groups to be provisioned incorrectly if the attributes change (for example, a user moves to a different part of the company).

-* Applications may have specific restrictions and/or requirements that need to be met for user provisioning to work correctly. For example, Slack truncates values for certain attributes. Refer to [automatic user provisioning tutorials](../saas-apps/tutorial-list.md) specific to each application.

-* Confirm schema consistency between source and target systems. Common issues include attributes such as UPN or mail not matching. For example, UPN in Microsoft Entra ID set as *john_smith@contoso.com* and in the app, it's *jsmith@contoso.com*. For more information, see The [User and group schema reference](../app-provisioning/use-scim-to-provision-users-and-groups.md).

-## Plan testing and security

-At each stage of your deployment ensure that youΓÇÖre testing that results are as expected, and auditing the provisioning cycles.

-### Plan testing

-First, configure automatic user provisioning for the application. Then run test cases to verify the solution meets your organizationΓÇÖs requirements.

-| Scenarios| Expected results |

-| - | - |

-| User is added to a group assigned to the target system. | User object is provisioned in target system. <br>User can sign-in to target system and perform the desired actions. |

-| User is removed from a group that is assigned to target system. | User object is deprovisioned in the target system.<br>User can't sign-in to target system. |

-| User information updates in Microsoft Entra ID by any method. | Updated user attributes reflect in the target system after an incremental cycle. |

-| User is out of scope. | User object is disabled or deleted. <br>Note: This behavior is overridden for [Workday provisioning](skip-out-of-scope-deletions.md). |

-### Plan security

-It's common for a security review to be required as part of a deployment. If you require a security review, see the many Microsoft Entra ID [whitepapers](https://www.microsoft.com/download/details.aspx?id=36391) that provides an overview for identity as a service.

-### Plan rollback

-If the automatic user provisioning implementation fails to work as desired in the production environment, the following rollback steps can assist you in reverting to a previous known good state:

-1. Review the [provisioning logs](../app-provisioning/check-status-user-account-provisioning.md) to determine what incorrect operations occurred on the affected users and/or groups.

-1. Use provisioning audit logs to determine the last known good state of the users and/or groups affected. Also review the source systems (Microsoft Entra ID or AD).

-1. Work with the application owner to update the users and/or groups affected directly in the application using the last known good state values.

-## Deploy automatic user provisioning service

-Choose the steps that align to your solution requirements.

-### Prepare for the initial cycle

-When the Microsoft Entra provisioning service runs for the first time, the initial cycle against the source system and target systems creates a snapshot of all user objects for each target system.

-When you enable automatic provisioning for an application, the initial cycle takes anywhere from 20 minutes to several hours. The duration depends on the size of the Microsoft Entra directory and the number of users in scope for provisioning.

-The provisioning service stores the state of both systems after the initial cycle, improving performance of subsequent incremental cycles.

-### Configure automatic user provisioning

-Use the [Microsoft Entra admin center](https://entra.microsoft.com) to manage automatic user account provisioning and deprovisioning for applications that support it. Follow the steps in [How do I set up automatic provisioning to an application?](../app-provisioning/user-provisioning.md)

-The Microsoft Entra user provisioning service can also be configured and managed using the [Microsoft Graph API](/graph/api/resources/synchronization-overview).

-## Manage automatic user provisioning

-Now that you've deployed, you need to manage the solution.

-### Monitor user provisioning operation health

-After a successful [initial cycle](../app-provisioning/user-provisioning.md), the Microsoft Entra provisioning service will run incremental updates indefinitely, at intervals specific to each application, until one of the following events occurs:

-* The service is manually stopped, and a new initial cycle is triggered using the [Microsoft Entra admin center](https://entra.microsoft.com), or using the appropriate [Microsoft Graph API](/graph/api/resources/synchronization-overview) command.

-* A new initial cycle triggers a change in attribute mappings or scoping filters.

-* The provisioning process goes into quarantine due to a high error rate and stays in quarantine for more than four weeks then it's automatically disabled.

-To review these events, and all other activities performed by the provisioning service, refer to Microsoft Entra [provisioning logs](../reports-monitoring/concept-provisioning-logs.md?context=azure/active-directory/manage-apps/context/manage-apps-context).

-To understand how long the provisioning cycles take and monitor the progress of the provisioning job, you can [check the status of user provisioning](../app-provisioning/application-provisioning-when-will-provisioning-finish-specific-user.md).

-### Gain insights from reports

-Microsoft Entra ID can provide more insights into your organizationΓÇÖs user provisioning usage and operational health through audit logs and reports. To learn more about user insights, see [Check the status of user provisioning](application-provisioning-when-will-provisioning-finish-specific-user.md).

-Admins should check the provisioning summary report to monitor the operational health of the provisioning job. All activities performed by the provisioning service are recorded in the Microsoft Entra audit logs. See [Tutorial: Reporting on automatic user account provisioning](../app-provisioning/check-status-user-account-provisioning.md).

-We recommend that you assume ownership of and consume these reports on a cadence that meets your organizationΓÇÖs requirements. Microsoft Entra ID retains most audit data for 30 days.

-### Troubleshoot

-Refer to the following links to troubleshoot any issues that may turn up during provisioning:

-* [Problem configuring user provisioning to a Microsoft Entra Gallery application](../app-provisioning/application-provisioning-config-problem.md)

-* [Sync an attribute from your on-premises Active Directory to Microsoft Entra ID for provisioning to an application](../app-provisioning/user-provisioning-sync-attributes-for-mapping.md)

-* [Problem saving administrator credentials while configuring user provisioning to a Microsoft Entra Gallery application](./user-provisioning.md)

-* [No users are being provisioned to a Microsoft Entra Gallery application](../app-provisioning/application-provisioning-config-problem-no-users-provisioned.md)

-* [Wrong set of users are being provisioned to a Microsoft Entra Gallery application](../manage-apps/add-application-portal-assign-users.md)

-### Helpful documentation

-* [Writing expressions for attribute mappings](../app-provisioning/functions-for-customizing-application-data.md)

-* [Microsoft Entra synchronization API overview](/graph/api/resources/synchronization-overview)

-* [Skip deletion of user accounts that go out of scope](skip-out-of-scope-deletions.md)

-* [Microsoft Entra Connect Provisioning Agent: Version release history](provisioning-agent-release-version-history.md)

-#### Resources

-* [Provide product feedback](https://feedback.azure.com/d365community/forum/22920db1-ad25-ec11-b6e6-000d3a4f0789)

-* [Keep up to date on what's new with Microsoft Entra ID](https://azure.microsoft.com/updates/?product=active-directory)

-* [Microsoft Q&A Microsoft Entra forum](/answers/tags/455/entra-id)

-## Next steps

-* [Configure Automatic User Provisioning](../app-provisioning/configure-automatic-user-provisioning-portal.md)

-* [Export or import your provisioning configuration by using Microsoft Graph API](../app-provisioning/export-import-provisioning-configuration.md)

-* [Writing expressions for attribute mappings in Microsoft Entra ID](../app-provisioning/functions-for-customizing-application-data.md)

-description: This article describes the deployment process of integrating cloud HR systems, such as Workday and SuccessFactors, with Microsoft Entra ID. Integrating Microsoft Entra ID with your cloud HR system results in a complete identity lifecycle management system.

-# Plan cloud HR application to Microsoft Entra user provisioning

-Historically, IT staff has relied on manual methods to create, update, and delete employees. They've used methods such as uploading CSV files or custom scripts to sync employee data. These provisioning processes are error prone, insecure, and hard to manage.

-To manage the identity lifecycles of employees, vendors, or contingent workers, [Microsoft Entra user provisioning service](../app-provisioning/user-provisioning.md) offers integration with cloud-based human resources (HR) applications. Examples of applications include Workday or SuccessFactors.

-Microsoft Entra ID uses this integration to enable the following cloud HR application (app) workflows:

-The following video provides guidance on planning your HR-driven provisioning integrations.

-> [!VIDEO https://www.youtube-nocookie.com/embed/HsdBt40xEHs]

-> [!NOTE]

-> This deployment plan shows you how to deploy your cloud HR app workflows with Microsoft Entra user provisioning. For information on how to deploy automatic user provisioning to software as a service (SaaS) apps, see [Plan an automatic user provisioning deployment](./plan-auto-user-provisioning.md).

-## Enabled HR scenarios

-The Microsoft Entra user provisioning service enables automation of the following HR-based identity lifecycle management scenarios:

-## Who is this integration best suited for?

-The cloud HR app integration with Microsoft Entra user provisioning is ideally suited for organizations that:

-## Learn

-User provisioning creates a foundation for ongoing identity governance. It enhances the quality of business processes that rely on authoritative identity data.

-### Terms

-This article uses the following terms:

-### Key benefits

-This capability of HR-driven IT provisioning offers the following significant business benefits:

-### Licensing

-To configure the cloud HR app to Microsoft Entra user provisioning integration, you require a valid [Microsoft Entra ID P1 or P2 license](https://www.microsoft.com/security/business/identity-access-management/azure-ad-pricing) and a license for the cloud HR app, such as Workday or SuccessFactors.

-You also need a valid Microsoft Entra ID P1 or higher subscription license for every user that is sourced from the cloud HR app and provisioned to either Active Directory or Microsoft Entra ID. Any improper number of licenses owned in the cloud HR app might lead to errors during user provisioning.

-### Prerequisites

-### Training resources

-| **Resources** | **Link and description** |

-|:-|:-|

-| Videos | [What is user provisioning in Active Azure Directory?](https://youtu.be/_ZjARPpI6NI) |

-| | [How to deploy user provisioning in Active Azure Directory](https://youtu.be/pKzyts6kfrw) |

-| Tutorials | [List of tutorials on how to integrate SaaS apps with Microsoft Entra ID](../saas-apps/tutorial-list.md) |

-| | [Tutorial: Configure automatic user provisioning with Workday](../saas-apps/workday-inbound-tutorial.md) |

-| | [Tutorial: Configure automatic user provisioning with SAP SuccessFactors](../saas-apps/sap-successfactors-inbound-provisioning-tutorial.md) |

-| FAQ | [Automated user provisioning](../app-provisioning/user-provisioning.md#what-applications-and-systems-can-i-use-with-azure-ad-automatic-user-provisioning) |

-| | [Provisioning from Workday to Microsoft Entra ID](../saas-apps/workday-inbound-tutorial.md#frequently-asked-questions-faq) |

-### Solution architecture

-The following example describes the end-to-end user provisioning solution architecture for common hybrid environments and includes:

-

-#### Description of workflow

-The following key steps are indicated in the diagram:  

-1. **HR team** performs the transactions in the cloud HR app tenant.

-2. **Microsoft Entra provisioning service** runs the scheduled cycles from the cloud HR app tenant and identifies changes to process for sync with Active Directory.

-3. **Microsoft Entra provisioning service** invokes the Microsoft Entra Connect provisioning agent with a request payload that contains Active Directory account create, update, enable, and disable operations.

-4. **Microsoft Entra Connect provisioning agent** uses a service account to manage Active Directory account data.

-5. **Microsoft Entra Connect** runs delta [sync](../hybrid/connect/how-to-connect-sync-whatis.md) to pull updates in Active Directory.

-6. **Active Directory** updates are synced with Microsoft Entra ID.

-7. **Microsoft Entra provisioning service** write backs email attribute and username from Microsoft Entra ID to the cloud HR app tenant.

-## Plan the deployment project

-Consider your organizational needs while you determine the strategy for this deployment in your environment.

-### Engage the right stakeholders

-When technology projects fail, they typically do so owing to mismatched expectations on impact, outcomes, and responsibilities. To avoid these pitfalls, [ensure that you're engaging the right stakeholders](../architecture/deployment-plans.md). Also make sure that stakeholder roles in the project are well understood. Document the stakeholders and their project input and accountabilities.

-Include a representative from the HR organization who can provide inputs on existing HR business processes and worker identity plus job data-processing requirements.

-### Plan communications

-Communication is critical to the success of any new service. Proactively communicate with your users about when and how their experience is changing. Let them know how to gain support if they experience issues.

-### Plan a pilot

-Integrating HR business processes and identity workflows from the cloud HR app to target systems requires a considerable amount of data validation, data transformation, data cleansing, and end-to-end testing before you can deploy the solution into production.

-Run the initial configuration in a [pilot environment](../architecture/deployment-plans.md#best-practices-for-a-pilot) before you scale it to all users in production.

-## Select cloud HR provisioning connector apps

-To facilitate Microsoft Entra provisioning workflows between the cloud HR app and Active Directory, you can add multiple provisioning connector apps from the Microsoft Entra app gallery:

-For example, the following image lists the Workday connector apps that are available in the Microsoft Entra app gallery.

-

-### Decision flow chart

-Use the following decision flow chart to identify which cloud HR provisioning apps are relevant to your scenario.

-

-<a name='design-the-azure-ad-connect-provisioning-agent-deployment-topology'></a>

-## Design the Microsoft Entra Connect provisioning agent deployment topology

-The provisioning integration between the cloud HR app and Active Directory requires four components:

-The Microsoft Entra Connect provisioning agent deployment topology depends on the number of cloud HR app tenants and Active Directory child domains that you plan to integrate. If you have multiple Active Directory domains, it depends on whether the Active Directory domains are contiguous or [disjoint](/windows-server/identity/ad-ds/plan/disjoint-namespace).

-Based on your decision, choose one of the deployment scenarios:

-### Single cloud HR app tenant -> target single or multiple Active Directory child domains in a trusted forest

-We recommend the following production configuration:

-|Requirement|Recommendation|

-|:-|:-|

-|Number of Microsoft Entra Connect provisioning agents to deploy.|Two (for high availability and failover).

-|Number of provisioning connector apps to configure.|One app per child domain.|

-|Server host for Microsoft Entra Connect provisioning agent.|Windows Server 2016 with line of sight to geolocated Active Directory domain controllers. </br>Can coexist with Microsoft Entra Connect service.|

-

-### Single cloud HR app tenant -> target multiple child domains in a disjoint Active Directory forest

-This scenario involves provisioning users from the cloud HR app to domains in disjoint Active Directory forests.

-We recommend the following production configuration:

-|Requirement|Recommendation|

-|:-|:-|

-|Number of Microsoft Entra Connect provisioning agents to deploy on-premises|Two per disjoint Active Directory forest.|

-|Number of provisioning connector apps to configure|One app per child domain.|

-|Server host for Microsoft Entra Connect provisioning agent.|Windows Server 2016 with line of sight to geolocated Active Directory domain controllers. </br>Can coexist with Microsoft Entra Connect service.|

-

-<a name='azure-ad-connect-provisioning-agent-requirements'></a>

-### Microsoft Entra Connect provisioning agent requirements

-The cloud HR app to Active Directory user provisioning solution requires the deployment of one or more Microsoft Entra Connect provisioning agents. These agents must be deployed on servers that run Windows Server 2016 or greater. The servers must have a minimum of 4-GB RAM and .NET 4.7.1+ runtime. Ensure that the host server has network access to the target Active Directory domain.

-To prepare the on-premises environment, the Microsoft Entra Connect provisioning agent configuration wizard registers the agent with your Microsoft Entra tenant, [opens ports](../app-proxy/application-proxy-add-on-premises-application.md#open-ports), [allows access to URLs](../app-proxy/application-proxy-add-on-premises-application.md#allow-access-to-urls), and supports [outbound HTTPS proxy configuration](../saas-apps/workday-inbound-tutorial.md#how-do-i-configure-the-provisioning-agent-to-use-a-proxy-server-for-outbound-http-communication).

-The provisioning agent configures a [Global Managed Service Account (GMSA)](../hybrid/cloud-sync/how-to-prerequisites.md#group-managed-service-accounts)

-to communicate with the Active Directory domains.

-You can select domain controllers that should handle provisioning requests. If you have several geographically distributed domain controllers, install the provisioning agent in the same site as your preferred domain controllers. This positioning improves the reliability and performance of the end-to-end solution.

-For high availability, you can deploy more than one Microsoft Entra Connect provisioning agent. Register the agent to handle the same set of on-premises Active Directory domains.

-## Design HR provisioning app deployment topology

-Depending on the number of Active Directory domains involved in the inbound user provisioning configuration, you may consider one of the following deployment topologies. Each topology diagram uses an example deployment scenario to highlight configuration aspects. Use the example that closely resembles your deployment requirement to determine the configuration that meets your needs.

-### Deployment topology one: Single app to provision all users from Cloud HR to single on-premises Active Directory domain

-Deployment topology one is the most common deployment topology. Use this topology, if you need to provision all users from Cloud HR to a single AD domain and same provisioning rules apply to all users.

-**Salient configuration aspects**

-* Setup two provisioning agent nodes for high availability and failover.

-* Use the [provisioning agent configuration wizard](../hybrid/cloud-sync/how-to-install.md#install-the-agent) to register your AD domain with your Microsoft Entra tenant.

-* When configuring the provisioning app, select the AD domain from the dropdown of registered domains.

-* If you're using scoping filters, configure [skip out of scope deletions flag](skip-out-of-scope-deletions.md) to prevent accidental account deactivations.

-### Deployment topology two: Separate apps to provision distinct user sets from Cloud HR to single on-premises Active Directory domain

-This topology supports business requirements where attribute mapping and provisioning logic differ based on user type (employee/contractor), user location or user's business unit. You can also use this topology to delegate the administration and maintenance of inbound user provisioning based on division or country/region.

-**Salient configuration aspects**

-* Setup two provisioning agent nodes for high availability and failover.

-* Create an HR2AD provisioning app for each distinct user set that you want to provision.

-* Use [scoping filters](define-conditional-rules-for-provisioning-user-accounts.md) in the provisioning app to define users to process each app.

-* In the scenario where manager references need to be resolved across distinct user sets, create a separate HR2AD provisioning app. For example, contractors reporting to managers who are employees. Use the separate app to update only the *manager* attribute. Set the scope of this app to all users.

-* Configure [skip out of scope deletions flag](skip-out-of-scope-deletions.md) to prevent accidental account deactivations.

-> [!NOTE]

-> If you do not have a test AD domain and use a TEST OU container in AD, then you may use this topology to create two separate apps *HR2AD (Prod)* and *HR2AD (Test)*. Use the *HR2AD (Test)* app to test your attribute mapping changes before promoting it to the *HR2AD (Prod)* app.

-### Deployment topology three: Separate apps to provision distinct user sets from Cloud HR to multiple on-premises Active Directory domains (no cross-domain visibility)

-Use topology three to manage multiple independent child AD domains belonging to the same forest. Make sure that managers always exist in the same domain as the user. Also make sure that your unique ID generation rules for attributes like *userPrincipalName*, *samAccountName*, and *mail* don't require a forest-wide lookup. Topology three offers the flexibility of delegating the administration of each provisioning job by domain boundary.

-For example: In the diagram, the provisioning apps are set up for each geographic region: North America (NA), Europe, Middle East and Africa (EMEA) and Asia Pacific (APAC). Depending on the location, users are provisioned to the respective AD domain. Delegated administration of the provisioning app is possible so that *EMEA administrators* can independently manage the provisioning configuration of users belonging to the EMEA region.

-**Salient configuration aspects**

-* Setup two provisioning agent nodes for high availability and failover.

-* Use the [provisioning agent configuration wizard](../hybrid/cloud-sync/how-to-install.md#install-the-agent) to register all child AD domains with your Microsoft Entra tenant.

-* Create a separate HR2AD provisioning app for each target domain.

-* When configuring the provisioning app, select the respective child AD domain from the dropdown of available AD domains.

-* Use [scoping filters](define-conditional-rules-for-provisioning-user-accounts.md) in the provisioning app to define users that each app processes.

-* Configure [skip out of scope deletions flag](skip-out-of-scope-deletions.md) to prevent accidental account deactivations.

-### Deployment topology four: Separate apps to provision distinct user sets from Cloud HR to multiple on-premises Active Directory domains (with cross-domain visibility)

-Use topology four to manage multiple independent child AD domains belonging to the same forest. A user's manager may exist in a different domain. Also, your unique ID generation rules for attributes like *userPrincipalName*, *samAccountName* and *mail* require a forest-wide lookup.

-For example: In the diagram, the provisioning apps are set up for each geographic region: North America (NA), Europe, Middle East and Africa (EMEA) and Asia Pacific (APAC). Depending on the location, users are provisioned to the respective AD domain. Cross-domain manager references and forest-wide lookup are handled by enabling referral chasing on the provisioning agent.

-**Salient configuration aspects**

-* Setup two provisioning agent nodes for high availability and failover.

-* Configure [referral chasing](../hybrid/cloud-sync/how-to-manage-registry-options.md#configure-referral-chasing) on the provisioning agent.

-* Use the [provisioning agent configuration wizard](../hybrid/cloud-sync/how-to-install.md#install-the-agent) to register the parent AD domain and all child AD domains with your Microsoft Entra tenant.

-* Create a separate HR2AD provisioning app for each target domain.

-* When configuring each provisioning app, select the parent AD domain from the dropdown of available AD domains. Selecting the parent domain ensures forest-wide lookup while generating unique values for attributes like *userPrincipalName*, *samAccountName* and *mail*.

-* Use *parentDistinguishedName* with expression mapping to dynamically create user in the correct child domain and [OU container](#configure-active-directory-ou-container-assignment).

-* Use [scoping filters](define-conditional-rules-for-provisioning-user-accounts.md) in the provisioning app to define users that each app processes.

-* To resolve cross-domain managers references, create a separate HR2AD provisioning app for updating only the *manager* attribute. Set the scope of this app to all users.

-* Configure [skip out of scope deletions flag](skip-out-of-scope-deletions.md) to prevent accidental account deactivations.

-### Deployment topology 5: Single app to provision all users from Cloud HR to multiple on-premises Active Directory domains (with cross-domain visibility)

-Use this topology if you want to use a single provisioning app to manage users belonging to all your parent and child AD domains. This topology is recommended if provisioning rules are consistent across all domains and there's no requirement for delegated administration of provisioning jobs. This topology supports resolving cross-domain manager references and can perform forest-wide uniqueness check.

-For example: In the diagram, a single provisioning app manages users present in three different child domains grouped by region: North America (NA), Europe, Middle East and Africa (EMEA) and Asia Pacific (APAC). The attribute mapping for *parentDistinguishedName* is used to dynamically create a user in the appropriate child domain. Cross-domain manager references and forest-wide lookup are handled by enabling referral chasing on the provisioning agent.

-**Salient configuration aspects**

-* Setup two provisioning agent nodes for high availability and failover.

-* Configure [referral chasing](../hybrid/cloud-sync/how-to-manage-registry-options.md#configure-referral-chasing) on the provisioning agent.

-* Use the [provisioning agent configuration wizard](../hybrid/cloud-sync/how-to-install.md#install-the-agent) to register the parent AD domain and all child AD domains with your Microsoft Entra tenant.

-* Create a single HR2AD provisioning app for the entire forest.

-* When configuring the provisioning app, select the parent AD domain from the dropdown of available AD domains. Selecting the parent domain ensures forest-wide lookup while generating unique values for attributes like *userPrincipalName*, *samAccountName* and *mail*.

-* Use *parentDistinguishedName* with expression mapping to dynamically create user in the correct child domain and [OU container](#configure-active-directory-ou-container-assignment).

-* If you're using scoping filters, configure [skip out of scope deletions flag](skip-out-of-scope-deletions.md) to prevent accidental account deactivations.

-### Deployment topology 6: Separate apps to provision distinct users from Cloud HR to disconnected on-premises Active Directory forests

-Use this topology if your IT infrastructure has disconnected/disjoint AD forests and you need to provision users to different forests based on business affiliation. For example: Users working for subsidiary *Contoso* need to be provisioned into the *contoso.com* domain, while users working for subsidiary *Fabrikam* need to be provisioned into the *fabrikam.com* domain.

-**Salient configuration aspects**

-* Setup two different sets of provisioning agents for high availability and failover, one for each forest.

-* Create two different provisioning apps, one for each forest.

-* If you need to resolve cross domain references within the forest, enable [referral chasing](../hybrid/cloud-sync/how-to-manage-registry-options.md#configure-referral-chasing) on the provisioning agent.

-* Create a separate HR2AD provisioning app for each disconnected forest.

-* When configuring each provisioning app, select the appropriate parent AD domain from the dropdown of available AD domain names.

-* Configure [skip out of scope deletions flag](skip-out-of-scope-deletions.md) to prevent accidental account deactivations.

-### Deployment topology 7: Separate apps to provision distinct users from multiple Cloud HR to disconnected on-premises Active Directory forests

-In large organizations, it isn't uncommon to have multiple HR systems. During business M&A (mergers and acquisitions) scenarios, you may come across a need to connect your on-premises Active Directory to multiple HR sources. We recommend the topology if you have multiple HR sources and would like to channel the identity data from these HR sources to either the same or different on-premises Active Directory domains.

-**Salient configuration aspects**

-* Setup two different sets of provisioning agents for high availability and failover, one for each forest.

-* If you need to resolve cross domain references within the forest, enable [referral chasing](../hybrid/cloud-sync/how-to-manage-registry-options.md#configure-referral-chasing) on the provisioning agent.

-* Create a separate HR2AD provisioning app for each HR system and on-premises Active Directory combination.

-* When configuring each provisioning app, select the appropriate parent AD domain from the dropdown of available AD domain names.

-* Configure [skip out of scope deletions flag](skip-out-of-scope-deletions.md) to prevent accidental account deactivations.

-## Plan scoping filters and attribute mapping

-When you enable provisioning from the cloud HR app to Active Directory or Microsoft Entra ID, the Azure portal controls the attribute values through attribute mapping.

-### Define scoping filters

-Use [scoping filters](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md) to define the attribute-based rules that determine which users should be provisioned from the cloud HR app to Active Directory or Microsoft Entra ID.

-When you initiate the Joiners process, gather the following requirements:

-Depending on your requirements, when you configure attribute mappings, you can set the **Source Object Scope** field to select which sets of users in the cloud HR app should be in scope for provisioning to Active Directory. For more information, see the cloud HR app tutorial for commonly used scoping filters.

-### Determine matching attributes

-With provisioning, you get the ability to match existing accounts between the source and target system. When you integrate the cloud HR app with the Microsoft Entra provisioning service, you can [configure attribute mapping](../app-provisioning/configure-automatic-user-provisioning-portal.md#mappings) to determine what user data should flow from the cloud HR app to Active Directory or Microsoft Entra ID.

-When you initiate the Joiners process, gather the following requirements:

-Depending on your requirements, Microsoft Entra ID supports direct attribute-to-attribute mapping by providing constant values or [writing expressions for attribute mappings](../app-provisioning/functions-for-customizing-application-data.md). This flexibility gives you ultimate control of what's populated in the targeted app attribute. You can use the [Microsoft Graph API](../app-provisioning/export-import-provisioning-configuration.md) and Graph Explorer to export your user provisioning attribute mappings and schema to a JSON file and import it back into Microsoft Entra ID.

-By default, the attribute in the cloud HR app that represents the unique employee ID is used as the matching attribute *mapped to the unique attribute in Active Directory.* For example, in the Workday app scenario, the **Workday** **WorkerID** attribute is mapped to the Active Directory **employeeID** attribute.

-You can set multiple matching attributes and assign matching precedence. They're evaluated on matching precedence. As soon as a match is found, no further matching attributes are evaluated.

-You can also [customize the default attribute mappings](../app-provisioning/customize-application-attributes.md#understanding-attribute-mapping-types), such as changing or deleting existing attribute mappings. You can also create new attribute mappings according to your business needs. For more information, see the cloud HR app tutorial (such as [Workday](../saas-apps/workday-inbound-tutorial.md#managing-your-configuration)) for a list of custom attributes to map.

-### Determine user account status

-By default, the provisioning connector app maps the HR user profile status to the user account status. The status is used to determine whether to enable or disable the user account.

-When you initiate the Joiners-Leavers process, gather the following requirements.

-| Process | Requirements |

-| - | - |

-| **Joiners** | From an identity lifecycle perspective, how do you handle rehires? Do rehires keep their old employee IDs? |

-| | Do you process future-dated hires and create Active Directory accounts for them in advance? Are these accounts created in an enabled or disabled state? |

-| | From an identity lifecycle perspective, how do you handle employee to contingent worker conversion, or otherwise? |

-| | Do converted users keep their old Active Directory accounts, or do they get new ones? |

-| **Leavers** | Are terminations handled differently for employees and contingent workers in Active Directory? |

-| | What effective dates are considered for processing user termination? |

-| | How do employee and contingent worker conversions affect existing Active Directory accounts? |

-| | How do you process the Rescind operation in Active Directory? Rescind operations need to be handled if future dated hires are created in Active Directory as part of the Joiner process. |

-Depending on your requirements, you might customize the mapping logic by using [Microsoft Entra expressions](../app-provisioning/functions-for-customizing-application-data.md) so that the Active Directory account is enabled or disabled based on a combination of data points.

-### Map cloud HR app to Active Directory user attributes

-Each cloud HR app ships with default cloud HR app to Active Directory mappings.

-When you initiate the Joiners-Movers-Leavers process, gather the following requirements.

-| Process | Requirements |

-| - | - |

-| **Joiners** | Is the Active Directory account creation process manual, automated, or partially automated? |

-| | Do you plan to propagate custom attributes from the cloud HR app to Active Directory? |

-| **Movers** | What attributes would you like to process whenever a Movers operation takes place in the cloud HR app? |

-| | Do you perform any specific attribute validations at the time of user updates? If yes, provide details. |

-| **Leavers** | Are terminations handled differently for employees and contingent workers in Active Directory? |

-| | What effective dates are considered for processing user termination? |

-| | How do employee and contingent worker conversions impact existing Active Directory accounts? |

-Depending on your requirements, you can modify the mappings to meet your integration goals. For more information, see the specific cloud HR app tutorial (such as [Workday](../saas-apps/workday-inbound-tutorial.md#part-4-configure-attribute-mappings)) for a list of custom attributes to map.

-### Generate a unique attribute value

-Attributes like CN, samAccountName, and the UPN have unique constraints. You may need to generate unique attribute values when you initiate the Joiners process.

-The Microsoft Entra ID function [SelectUniqueValues](../app-provisioning/functions-for-customizing-application-data.md#selectuniquevalue) evaluates each rule and then checks the value generated for uniqueness in the target system. For an example, see [Generate unique value for the userPrincipalName (UPN) attribute](../app-provisioning/functions-for-customizing-application-data.md#generate-unique-value-for-userprincipalname-upn-attribute).

-> [!NOTE]

-> This function is currently only supported for Workday to Active Directory and SAP SuccessFactors to Active Directory user provisioning. It can't be used with other provisioning apps.

-### Configure Active Directory OU container assignment

-It's a common requirement to place Active Directory user accounts into containers based on business units, locations, and departments. When you initiate a Movers process, and if there's a supervisory organization change, you might need to move the user from one OU to another in Active Directory.

-Use the [Switch()](../app-provisioning/functions-for-customizing-application-data.md#switch) function to configure the business logic for the OU assignment, and map it to the Active Directory attribute **parentDistinguishedName**.

-For example, if you want to create users in OU based on the HR attribute **Municipality**, you can use the following expression:

-`

-Switch([Municipality], "OU=Default,OU=Users,DC=contoso,DC=com", "Dallas", "OU=Dallas,OU=Users,DC=contoso,DC=com", "Austin", "OU=Austin,OU=Users,DC=contoso,DC=com", "Seattle", "OU=Seattle,OU=Users,DC=contoso,DC=com", "London", "OU=London,OU=Users,DC=contoso,DC=com")

-`

-With this expression, if the Municipality value is Dallas, Austin, Seattle, or London, the user account is created in the corresponding OU. If there's no match, then the account is created in the default OU.

-## Plan for password delivery of new user accounts

-When you initiate the Joiners process, you need to set and deliver a temporary password of new user accounts. With cloud HR to Microsoft Entra user provisioning, you can roll out the Microsoft Entra ID [self-service password reset](../authentication/tutorial-enable-sspr.md) (SSPR) capability for the user on day one.

-SSPR is a simple means for IT administrators to enable users to reset their passwords or unlock their accounts. You can provision the **Mobile Number** attribute from the cloud HR app to Active Directory and sync it with Microsoft Entra ID. After the **Mobile Number** attribute is in Microsoft Entra ID, you can enable SSPR for the user's account. Then on day one, the new user can use the registered and verified mobile number for authentication. Refer to the [SSPR documentation](../authentication/howto-sspr-authenticationdata.md) for details on how to prepopulate authentication contact information.

-## Plan for initial cycle

-When the Microsoft Entra provisioning service runs for the first time, it performs an [initial cycle](../app-provisioning/how-provisioning-works.md#initial-cycle) against the cloud HR app to create a snapshot of all user objects in the cloud HR app. The time taken for initial cycles is directly dependent on how many users are present in the source system. The initial cycle for some cloud HR app tenants with over 100,000 users can take a long time.

-**For large cloud HR app tenants (>30,000 users),** run the initial cycle in progressive stages. Start the incremental updates only after you validate that the correct attributes are set in Active Directory for different user provisioning scenarios. Follow the order here.

-1. Run the initial cycle only for a limited set of users by setting the [scoping filter](#plan-scoping-filters-and-attribute-mapping).

-2. Verify Active Directory account provisioning and the attribute values set for the users selected for the first run. If the result meets your expectations, expand the scoping filter to progressively include more users and verify the results for the second run.

-After you're satisfied with the results of the initial cycle for test users, start the [incremental updates](../app-provisioning/how-provisioning-works.md#incremental-cycles).

-## Plan testing and security

-A deployment consists of stages ranging from the initial pilot to enabling user provisioning. At each stage, ensure that you're testing for expected results. Also, audit the provisioning cycles.

-### Plan testing

-After you configure the cloud HR app to Microsoft Entra user provisioning, run test cases to verify whether this solution meets your organization's requirements.

-|Scenarios|Expected results|

-|:-|:-|

-|New employee is hired in the cloud HR app.| - The user account is provisioned in Active Directory.</br>- The user can log into Active Directory-domain apps and perform the desired actions.</br>- If Microsoft Entra Connect Sync is configured, the user account also gets created in Microsoft Entra ID.

-|User is terminated in the cloud HR app.|- The user account is disabled in Active Directory.</br>- The user can't log into any enterprise apps protected by Active Directory.

-|User supervisory organization is updated in the cloud HR app.|Based on the attribute mapping, the user account moves from one OU to another in Active Directory.|

-|HR updates the user's manager in the cloud HR app.|The manager field in Active Directory is updated to reflect the new manager's name.|

-|HR rehires an employee into a new role.|Behavior depends on how the cloud HR app is configured to generate employee IDs. If the old employee ID is used for a rehired employee, the connector enables the existing Active Directory account for the user. If the rehired employee gets a new employee ID, the connector creates a new Active Directory account for the user.|

-|HR converts the employee to a contract worker or vice versa.|A new Active Directory account is created for the new persona and the old account gets disabled on the conversion effective date.|

-Use the previous results to determine how to transition your automatic user provisioning implementation into production based on your established timelines.

-> [!TIP]

-> Use techniques such as data reduction and data scrubbing when you refresh the test environment with production data to remove or mask sensitive personal data to comply with privacy and security standards.

-### Plan security

-It's common for a security review to be required as part of the deployment of a new service. If a security review is required or hasn't been conducted, see the many Microsoft Entra ID [white papers](https://www.microsoft.com/download/details.aspx?id=36391) that provide an overview of the identity as a service.

-### Plan rollback

-The cloud HR user provisioning implementation might fail to work as desired in the production environment. If so, the following rollback steps can assist you in reverting to a previous known good state.

-1. Review the [provisioning logs](../app-provisioning/check-status-user-account-provisioning.md#provisioning-logs) to determine what incorrect operations were performed on the affected users or groups. For more information on the provisioning summary report and logs, see [Manage cloud HR app user provisioning](#manage-your-configuration).

-2. The last known good state of the users or groups affected can be determined through the provisioning audit logs or by reviewing the target systems (Microsoft Entra ID or Active Directory).

-3. Work with the app owner to update the users or groups affected directly in the app by using the last known good state values.

-## Deploy the cloud HR app

-Choose the cloud HR app that aligns to your solution requirements.

-**Workday**: To import worker profiles from Workday into Active Directory and Microsoft Entra ID, see [Tutorial: Configure Workday for automatic user provisioning](../saas-apps/workday-inbound-tutorial.md#planning-your-deployment). Optionally, you can write back the email address, username and phone number to Workday.

-**SAP SuccessFactors**: To import worker profiles from SuccessFactors into Active Directory and Microsoft Entra ID, see [Tutorial: Configure SAP SuccessFactors for automatic user provisioning](../saas-apps/sap-successfactors-inbound-provisioning-tutorial.md). Optionally, you can write back the email address and username to SuccessFactors.

-## Manage your configuration

-Microsoft Entra ID can provide more insights into your organization's user provisioning usage and operational health through audit logs and reports.

-### Gain insights from reports and logs

-After a successful [initial cycle](../app-provisioning/how-provisioning-works.md#initial-cycle), the Microsoft Entra provisioning service continues to run back-to-back incremental updates indefinitely, at intervals defined in the tutorials specific to each app, until one of the following events occurs:

-To review these events and all other activities performed by the provisioning service, [learn how to review logs and get reports on provisioning activity](../app-provisioning/check-status-user-account-provisioning.md).

-#### Azure Monitor logs

-All activities performed by the provisioning service are recorded in the Microsoft Entra audit logs. You can route Microsoft Entra audit logs to Azure Monitor logs for further analysis. With Azure Monitor logs (also known as Log Analytics workspace), you can query data to find events, analyze trends, and perform correlation across various data sources. Watch this [video](https://youtu.be/MP5IaCTwkQg) to learn the benefits of using Azure Monitor logs for Microsoft Entra logs in practical user scenarios.

-Install the [log analytics views for Microsoft Entra activity logs](/azure/azure-monitor/visualize/workbooks-view-designer-conversion-overview) to get access to [prebuilt reports](https://github.com/AzureAD/Deployment-Plans/tree/master/Log%20Analytics%20Views) around provisioning events in your environment.

-For more information, see how to [analyze the Microsoft Entra activity logs with your Azure Monitor logs](../reports-monitoring/howto-analyze-activity-logs-log-analytics.md).

-### Manage personal data

-The Microsoft Entra Connect provisioning agent installed on the Windows server creates logs in the Windows event log that might contain personal data depending on your cloud HR app to Active Directory attribute mappings. To comply with user privacy obligations, set up a Windows scheduled task to clear the event log and ensure that no data is kept beyond 48 hours.

-Microsoft Entra provisioning service doesn't generate reports, perform analytics, or provide insights beyond 30 days because the service doesn't store, process, or keep any data beyond 30 days.

-### Troubleshoot

-To troubleshoot any issues that might turn up during provisioning, see the following articles:

-### Next steps

-description: Learn how to provision users on demand in Microsoft Entra ID.

-zone_pivot_groups: app-provisioning-cross-tenant-synchronization

-# On-demand provisioning in Microsoft Entra ID

-Use on-demand provisioning to provision a user or group in seconds. Among other things, you can use this capability to:

-* Troubleshoot configuration issues quickly.

-* Validate expressions that you've defined.

-* Test scoping filters.

-## How to use on-demand provisioning

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-2. Browse to **Identity** > **Applications** > **Enterprise applications** > select your application.

-3. Select **Provisioning**.

-2. Browse to **Identity** > **External Identities** > **Cross-tenant Synchronization** > **Configurations**

-3. Select your configuration, and then go to the **Provisioning** configuration page.

-4. Configure provisioning by providing your admin credentials.

-5. Select **Provision on demand**.

-6. Search for a user by first name, last name, display name, user principal name, or email address. Alternatively, you can search for a group and pick up to five users.

- > [!NOTE]

- > For Cloud HR provisioning app (Workday / SuccessFactors to Active Directory / Microsoft Entra ID), the input value is different.

- > For Workday scenario, please provide "WorkerID" or "WID" of the user in Workday.

- > For SuccessFactors scenario, please provide "personIdExternal" of the user in SuccessFactors.

-

-7. Select **Provision** at the bottom of the page.

- :::image type="content" source="media/provision-on-demand/on-demand-provision-user.png" alt-text="Screenshot that shows the Microsoft Entra admin center UI for provisioning a user on demand." lightbox="media/provision-on-demand/on-demand-provision-user.png":::

-## Understand the provisioning steps

-The on-demand provisioning process attempts to show the steps that the provisioning service takes when provisioning a user. There are typically five steps to provision a user. One or more of those steps, explained in the following sections, are shown during the on-demand provisioning experience.

-### Step 1: Test connection

-The provisioning service attempts to authorize access to the target system by making a request for a "test user". The provisioning service expects a response that indicates that the service authorized to continue with the provisioning steps. This step is shown only when it fails. It's not shown during the on-demand provisioning experience when the step is successful.

-#### Troubleshooting tips

-* Ensure that you've provided valid credentials, such as the secret token and tenant URL, to the target system. The required credentials vary by application. For detailed configuration tutorials, see the [tutorial list](../saas-apps/tutorial-list.md).

-* Make sure that the target system supports filtering on the matching attributes defined in the **Attribute mappings** pane. You might need to check the API documentation provided by the application developer to understand the supported filters.

-* For System for Cross-domain Identity Management (SCIM) applications, you can use a tool like Postman. Such tools help you ensure that the application responds to authorization requests in the way that the Microsoft Entra provisioning service expects. Have a look at an [example request](./use-scim-to-provision-users-and-groups.md#request-3).

-### Step 2: Import user

-Next, the provisioning service retrieves the user from the source system. The user attributes that the service retrieves are used later to:

-* Evaluate whether the user is in scope for provisioning.

-* Check the target system for an existing user.

-* Determine what user attributes to export to the target system.

-#### View details

-The **View details** section shows the properties of the user that were imported from the source system (for example, Microsoft Entra ID).

-#### Troubleshooting tips

-* Importing the user can fail when the matching attribute is missing on the user object in the source system. To resolve this failure, try one of these approaches:

- * Update the user object with a value for the matching attribute.

- * Change the matching attribute in your provisioning configuration.

-* If an attribute that you expected is missing from the imported list, ensure that the attribute has a value on the user object in the source system. The provisioning service currently doesn't support provisioning null attributes.

-* Make sure that the **Attribute mapping** page of your provisioning configuration contains the attribute that you expect.

-### Step 3: Determine if user is in scope

-Next, the provisioning service determines whether the user is in [scope](./how-provisioning-works.md#scoping) for provisioning. The service considers aspects such as:

-* Whether the user is assigned to the application.

-* Whether scope is set to **Sync assigned** or **Sync all**.

-* The scoping filters defined in your provisioning configuration.

-#### View details

-The **View details** section shows the scoping conditions that were evaluated. You might see one or more of the following properties:

-* **Active in source system** indicates that the user has the property `IsActive` set to **true** in Microsoft Entra ID.

-* **Assigned to application** indicates that the user is assigned to the application in Microsoft Entra ID.

-* **Scope sync all** indicates that the scope setting allows all users and groups in the tenant.

-* **User has required role** indicates that the user has the necessary roles to be provisioned into the application.

-* **Scoping filters** are also shown if you have defined scoping filters for your application. The filter is displayed with the following format: {scoping filter title} {scoping filter attribute} {scoping filter operator} {scoping filter value}.

-#### Troubleshooting tips

-* Make sure that you've defined a valid scoping role. For example, avoid using the [Greater_Than operator](./define-conditional-rules-for-provisioning-user-accounts.md#create-a-scoping-filter) with a noninteger value.

-* If the user doesn't have the necessary role, review the [tips for provisioning users assigned to the default access role](./application-provisioning-config-problem-no-users-provisioned.md#provisioning-users-assigned-to-the-default-access-role).

-### Step 4: Match user between source and target

-In this step, the service attempts to match the user that was retrieved in the import step with a user in the target system.

-#### View details

-The **View details** page shows the properties of the users that were matched in the target system. The context pane changes as follows:

-* If no users are matched in the target system, no properties are shown.

-* If one user matches in the target system, the properties of that user are shown.

-* If multiple users match, the properties of both users are shown.

-* If multiple matching attributes are part of your attribute mappings, each matching attribute is evaluated sequentially and the matched users for that attribute are shown.

-#### Troubleshooting tips

-* The provisioning service might not be able to match a user in the source system uniquely with a user in the target. Resolve this problem by ensuring that the matching attribute is unique.

-* Make sure that the target system supports filtering on the attribute that's defined as the matching attribute.

-### Step 5: Perform action

-Finally, the provisioning service takes an action, such as creating, updating, deleting, or skipping the user.

-Here's an example of what you might see after the successful on-demand provisioning of a user:

-#### View details

-The **View details** section displays the attributes that were modified in the target system. This display represents the final output of the provisioning service activity and the attributes that were exported. If this step fails, the attributes displayed represent the attributes that the provisioning service attempted to modify.

-#### Troubleshooting tips

-* Failures for exporting changes can vary greatly. Check the [documentation for provisioning logs](../reports-monitoring/howto-analyze-provisioning-logs.md#error-codes) for common failures.

-* On-demand provisioning says the group or user can't be provisioned because they're not assigned to the application. There's a replication delay of up to a few minutes between when an object is assigned to an application and when that assignment is honored in on-demand provisioning. You may need to wait a few minutes and try again.

-## Frequently asked questions

-* **Do you need to turn provisioning off to use on-demand provisioning?** For applications that use a long-lived bearer token or a user name and password for authorization, no more steps are required. Applications that use OAuth for authorization currently require the provisioning job to be stopped before using on-demand provisioning. Applications such as G Suite, Box, Workplace by Facebook, and Slack fall into this category. Work is in progress to support on-demand provisioning for all applications without having to stop provisioning jobs.

-* **How long does on-demand provisioning take?** On-demand provisioning typically takes less than 30 seconds.

-## Known limitations

-There are currently a few known limitations to on-demand provisioning. Post your [suggestions and feedback](https://aka.ms/appprovisioningfeaturerequest) so we can better determine what improvements to make next.

-> [!NOTE]

-> The following limitations are specific to the on-demand provisioning capability. For information about whether an application supports provisioning groups, deletions, or other capabilities, check the tutorial for that application.

-* On-demand provisioning of groups supports updating up to five members at a time. Connectors for cross-tenant synchronization, Workday, etc. do not support group provisioning and as a result do not support on-demand provisioning of groups.

-* On-demand provisioning of groups is not supported for cross-tenant synchronization.

-* On-demand provisioning supports provisioning one user at a time through the Microsoft Entra admin center.

-* Restoring a previously soft-deleted user in the target tenant with on-demand provisioning isn't supported. If you try to soft-delete a user with on-demand provisioning and then restore the user, it can result in duplicate users.

-* On-demand provisioning of roles isn't supported.

-* On-demand provisioning supports disabling users that have been unassigned from the application. However, it doesn't support disabling or deleting users that have been disabled or deleted from Microsoft Entra ID. Those users don't appear when you search for a user.

-* On-demand provisioning doesn't support nested groups that aren't directly assigned to the application.

-* The on-demand provisioning request API can only accept a single group with up to 5 members at a time.

-## Next steps

-* [Troubleshooting provisioning](./application-provisioning-config-problem.md)

-description: This article lists all releases of Microsoft Entra Connect Provisioning Agent and describes new features and fixed issues.

-# Microsoft Entra Connect Provisioning Agent: Version release history

-description: This article describes the Azure Monitor workbook for provisioning.

-# Provisioning insights workbook

-The Provisioning workbook provides a flexible canvas for data analysis. This workbook brings together all of the provisioning logs from various sources and allows you to gain insight, in a single area. The workbook allows you to create rich visual reports within the Azure portal. To learn more, see Azure Monitor Workbooks overview.

-This workbook is intended for Hybrid Identity Admins who use provisioning to sync users from various data sources to various data repositories. It allows admins to gain insights into sync status and details.

-This workbook:

-## Enabling provisioning logs

-You should already be familiar with Azure monitoring and Log Analytics. If not, jump over to learn about them and then come back to learn about application provisioning logs. To learn more about Azure monitoring, see [Azure Monitor overview](/azure/azure-monitor/overview). To learn more about Azure Monitor logs and Log Analytics, see [Overview of log queries in Azure Monitor](/azure/azure-monitor/logs/log-query-overview) and [Provisioning Logs for troubleshooting cloud sync](../hybrid/cloud-sync/how-to-troubleshoot.md).

-## Source and Target

-At the top of the workbook, using the drop-down, specify the source and target identities.

-Theses fields are the source and target of identities. The rest of the filters that appear are based on the selection of source and target.

-You can scope your search so that it is more granular using the additional fields. Use the table below as a reference for queries.

-For example, if you wanted to see data from your cloud sync workflow, your source would be Active Directory and your target would be Microsoft Entra ID.

->[!NOTE]

->Source and target are required. If you do not select a source and target, you won't see any data.

-|Field|Description|

-|--|--|

-|Source|The provisioning source repository|

-|Target|The provisioning target repository|

-|Time Range|The range of provisioning information you want to view. This can be anywhere from 4 hours to 90 days. You can also set a custom value.|

-|Status|View the provisioning status such as Success or Skipped.|

-|Action|View the provisioning actions taken such as Create or Delete.|

-|App Name|Allows you to filter by the application name. In the case of Active Directory, you can filter by domains.|

-|Job Id|Allows you to target specific Job Ids.|

-|Sync type|Filter by type of synchronization such as object or password.|

->[!NOTE]

-> All of the charts and grids in Sync Summary, Sync Details, and Sync Details by grid, change based on source,target and the parameter selections.

-## Sync Summary

-The sync summary section provides a summary of your organizations synchronization activities. These activities include:

- - Total synced objects by type

- - Provisioning events by action

- - Provisioning events by status

- - Unique sync count by status

- - Provisioning success rate

- - Top provisioning errors

- :::image type="content" source="media/provisioning-workbook/sync-summary-1.png" alt-text="Screenshot of the synchronization summary." lightbox="media/provisioning-workbook/sync-summary-1.png":::

-## Sync details

-The sync details tab allows you to drill into the synchronization data and get more information. This information includes:

- - Objects sync by status

- - Objects synced by action

- - Sync log details

-

- >[!NOTE]

- >The grid is filterable on any of the above filters but you can also click the tiles under under **Objects synced by Status** and **Action**.

-

- :::image type="content" source="media/provisioning-workbook/sync-details-1.png" alt-text="Screenshot of the synchronization details." lightbox="media/provisioning-workbook/sync-details-1.png":::

-You can further drill in to the sync log details for additional information.

->[!NOTE]

->Clicking on the Source ID it will dive deeper and provide more information on the synchronized object.

-

-## Sync details by cycle

-The sync details by cycle tab allow you to get more granular with the synchronization data. This information includes:

- - Objects sync by status

- - Objects synced by action

- - Sync log details

-

- :::image type="content" source="media/provisioning-workbook/sync-details-2.png" alt-text="Screenshot of the synchronization details by cycle tab." lightbox="media/provisioning-workbook/sync-details-2.png":::

-You can further drill in to the sync log details for additional information.

->[!NOTE]

->The grid is filterable on any of the above filters but you can also click the tiles under under **Objects synced by Status** and **Action**.

-## Single user view

-The user provisioning view tab allows you to get synchronization data on individual users.

->[!NOTE]

->This section does not involve using source and target.

-In this section, you enter a time range and select a specific user to see which applications a user has been provisioned or deprovisioned in.

-Once you select a time range, it will filter for users that have events in that time range.

-To target a specific user, you can add one of the following parameters, for that user.

- - UPN

- - UserID

-

-

-## Details

-By clicking on the Source ID in the **Sync details** or the **Sync details by cycle** views, you can see additional information on the object synchronized.

-## Custom queries

-You can create custom queries and show the data on Azure dashboards. To learn how, see [Create and share dashboards of Log Analytics data](/azure/azure-monitor/logs/get-started-queries). Also, be sure to check out [Overview of log queries in Azure Monitor](/azure/azure-monitor/logs/log-query-overview).

-## Custom alerts

-Azure Monitor lets you configure custom alerts so that you can get notified about key events related to Provisioning. For example, you might want to receive an alert on spikes in failures. Or perhaps spikes in disables or deletes. Another example of where you might want to be alerted is a lack of any provisioning, which indicates something is wrong.

-To learn more about alerts, see [Azure Monitor Log Alerts](/azure/azure-monitor/alerts/alerts-create-new-alert-rule).

-## Next steps

-description: Learn which attributes from SuccessFactors are supported by SuccessFactors-HR driven provisioning in Microsoft Entra ID.

-# SAP SuccessFactors attribute reference for Microsoft Entra ID

-In this article, you'll find information on:

-## Supported SuccessFactors entities and attributes

-The table below captures the list of SuccessFactors attributes included by default in the following two provisioning apps:

-Please refer to the [SAP SuccessFactors integration reference](./sap-successfactors-integration-reference.md#retrieving-more-attributes) to extend the schema for additional attributes.

-| \# | SuccessFactors Entity | SuccessFactors Attribute | Operation Type |

-|-|-||-|

-| 1 | PerPerson | personIdExternal | Read |

-| 2 | PerPerson | personId | Read |

-| 3 | PerPerson | perPersonUuid | Read |

-| 4 | PerPersonal | displayName | Read |

-| 5 | PerPersonal | firstName | Read |

-| 6 | PerPersonal | gender | Read |

-| 7 | PerPersonal | lastName | Read |

-| 8 | PerPersonal | middleName | Read |

-| 9 | PerPersonal | preferredName | Read |

-| 10 | User | addressLine1 | Read |

-| 11 | User | addressLine2 | Read |

-| 12 | User | addressLIne3 | Read |

-| 13 | User | businessPhone | Read |

-| 14 | User | cellPhone | Read |

-| 15 | User | city | Read |

-| 16 | User | country | Read |

-| 17 | User | custom01 | Read |

-| 18 | User | custom02 | Read |

-| 19 | User | custom03 | Read |

-| 20 | User | custom04 | Read |

-| 21 | User | custom05 | Read |

-| 22 | User | custom06 | Read |

-| 23 | User | custom07 | Read |

-| 24 | User | custom08 | Read |

-| 25 | User | custom09 | Read |

-| 26 | User | custom10 | Read |

-| 27 | User | custom11 | Read |

-| 28 | User | custom12 | Read |

-| 29 | User | custom13 | Read |

-| 30 | User | custom14 | Read |

-| 31 | User | empId | Read |

-| 32 | User | homePhone | Read |

-| 33 | User | jobFamily | Read |

-| 34 | User | nickname | Read |

-| 35 | User | state | Read |

-| 36 | User | timeZone | Read |

-| 37 | User | username | Read |

-| 38 | User | zipCode | Read |

-| 39 | PerPhone | areaCode | Read |

-| 40 | PerPhone | countryCode | Read |

-| 41 | PerPhone | extension | Read |

-| 42 | PerPhone | phoneNumber | Read |

-| 43 | PerPhone | phoneType | Read |

-| 44 | PerEmail | emailAddress | Read, Write |

-| 45 | PerEmail | emailType | Read |

-| 46 | EmpEmployment | firstDateWorked | Read |

-| 47 | EmpEmployment | lastDateWorked | Read |

-| 48 | EmpEmployment | userId | Read |

-| 49 | EmpEmployment | isContingentWorker | Read |

-| 50 | EmpJob | countryOfCompany | Read |

-| 51 | EmpJob | emplStatus | Read |

-| 52 | EmpJob | endDate | Read |

-| 53 | EmpJob | startDate | Read |

-| 54 | EmpJob | jobTitle | Read |

-| 55 | EmpJob | position | Read |

-| 65 | EmpJob | customString13 | Read |

-| 56 | EmpJob | managerId | Read |

-| 57 | EmpJob\.BusinessUnit | businessUnit | Read |

-| 58 | EmpJob\.BusinessUnit | businessUnitId | Read |

-| 59 | EmpJob\.Company | company | Read |

-| 60 | EmpJob\.Company | companyId | Read |

-| 61 | EmpJob\.Company\.CountryOfRegistration | twoCharCountryCode | Read |

-| 62 | EmpJob\.CostCenter | costCenter | Read |

-| 63 | EmpJob\.CostCenter | costCenterId | Read |

-| 64 | EmpJob\.CostCenter | costCenterDescription | Read |

-| 65 | EmpJob\.Department | department | Read |

-| 66 | EmpJob\.Department | departmentId | Read |

-| 67 | EmpJob\.Division | division | Read |

-| 68 | EmpJob\.Division | divisionId | Read |

-| 69 | EmpJob\.JobCode | jobCode | Read |

-| 70 | EmpJob\.JobCode | jobCodeId | Read |

-| 71 | EmpJob\.Location | LocationName | Read |

-| 72 | EmpJob\.Location | officeLocationAddress | Read |

-| 73 | EmpJob\.Location | officeLocationCity | Read |

-| 74 | EmpJob\.Location | officeLocationCustomString4 | Read |

-| 75 | EmpJob\.Location | officeLocationZipCode | Read |

-| 76 | EmpJob\.PayGrade | payGrade | Read |

-| 77 | EmpEmploymentTermination | activeEmploymentsCount | Read |

-| 78 | EmpEmploymentTermination | latestTerminationDate | Read |

-## Default attribute mapping

-The table below provides the default attribute mapping between SuccessFactors attributes listed above and Active Directory / Microsoft Entra attributes. In the Microsoft Entra provisioning app "Mapping" blade, you can modify this default mapping to include attributes from the list above.

-| \# | SuccessFactors Entity | SuccessFactors Attribute | Default attribute mapping | Processing Remark |

-|-|-|--|--|-|

-| 1 | PerPerson | personIdExternal | employeeId | Used as matching attribute |

-| 2 | PerPerson | perPersonUuid | \[Not mapped \- used as source anchor\] | During initial sync, the Provisioning Service links the personUuid to existing objectGuid\. |

-| 3 | PerPersonal | displayName | displayName | NA |

-| 4 | PerPersonal | firstName | givenName | NA |

-| 5 | PerPersonal | lastName | sn | NA |

-| 6 | User | addressLine1 | streetAddress | NA |

-| 7 | User | city | l | NA |

-| 8 | User | country | co | NA |

-| 9 | User | state | st | NA |

-| 10 | User | username | samAccountName | NA |

-| 11 | User | zipCode | postalCode | NA |

-| 12 | PerEmail | emailAddress | mail | NA |

-| 13 | EmpJob | jobTitle | title | NA |

-| 14 | EmpJob | managerId | manager | NA |

-| 15 | EmpJob\.Company\.CountryOfRegistration | twoCharCountryCode | c | NA |

-| 16 | EmpJob\.Department | department | department | NA |

-| 17 | EmpJob\.Division | division | company | NA |

-| 18 | EmpJob\.Location | officeLocationAddress | streetAddress | NA |

-| 19 | EmpJob\.Location | officeLocationZipCode | postalCode | NA |

-| 20 | EmpEmploymentTermination | activeEmploymentsCount | accountEnabled | if activeEmploymentsCount=0, disable the account\. |

-description: Technical deep dive into SAP SuccessFactors-HR driven provisioning for Microsoft Entra ID.

-# How Microsoft Entra provisioning integrates with SAP SuccessFactors

-[Microsoft Entra user provisioning service](../app-provisioning/user-provisioning.md) integrates with [SAP SuccessFactors Employee Central](https://www.sap.com/products/hcm/employee-central-payroll.html) to manage the identity life cycle of users. Microsoft Entra ID offers three prebuilt integrations:

-* [SuccessFactors to on-premises Active Directory user provisioning](../saas-apps/sap-successfactors-inbound-provisioning-tutorial.md)

-* [SuccessFactors to Microsoft Entra user provisioning](../saas-apps/sap-successfactors-inbound-provisioning-cloud-only-tutorial.md)

-* [SuccessFactors Writeback](../saas-apps/sap-successfactors-writeback-tutorial.md)

-This article explains how the integration works and how you can customize the provisioning behavior for different HR scenarios.

-## Establishing connectivity

-Microsoft Entra provisioning service uses basic authentication to connect to Employee Central OData API endpoints. When setting up the SuccessFactors provisioning app, use the *Tenant URL* parameter in the *Admin Credentials* section to configure the [API data center URL](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/d599f15995d348a1b45ba5603e2aba9b/af2b8d5437494b12be88fe374eba75b6.html).

-To further secure the connectivity between Microsoft Entra provisioning service and SuccessFactors, add the Microsoft Entra IP ranges in the SuccessFactors IP allowlist:

-1. Download the [latest IP Ranges](https://www.microsoft.com/download/details.aspx?id=56519) for the Azure Public Cloud

-1. Open the file and search for tag **Microsoft Entra ID**

- >[!div class="mx-imgBorder"]

- >

-1. Copy all IP address ranges listed within the element *addressPrefixes* and use the range to build your IP address restriction list.

-1. Translate the CIDR values to IP ranges.

-1. Log in to SuccessFactors admin portal to add IP ranges to the allowlist. Refer to SAP [support note 2253200](https://userapps.support.sap.com/sap/support/knowledge/2253200). You can now [enter IP ranges](https://answers.sap.com/questions/12882263/whitelisting-sap-cloud-platform-ip-address-range-i.html) in this tool.

-## Supported entities

-For every user in SuccessFactors, Microsoft Entra provisioning service retrieves the following entities. Each entity is expanded using the OData API *$expand* query parameter as outlined in the *Retrieval rule* column. Some entities are expanded by default, while some entities are expanded only if a specific attribute is present in the mapping.

-| \# | SuccessFactors Entity | OData Node | Retrieval rule |

-|-|-|||

-| 1 | `PerPerson` | `*root node*` | Always |

-| 2 | `PerPersonal` | `personalInfoNav` | Always |

-| 3 | `PerPhone` | `phoneNav` | Always |

-| 4 | `PerEmail` | `emailNav` | Always |

-| 5 | `EmpEmployment` | `employmentNav` | Always |

-| 6 | `User` | `employmentNav/userNav` | Always |

-| 7 | `EmpJob` | `employmentNav/jobInfoNav` | Always |

-| 8 | `EmpEmploymentTermination` | `activeEmploymentsCount` | Always |

-| 9 | `User's manager` | `employmentNav/userNav/manager/empInfo` | Always |

-| 10 | `FOCompany` | `employmentNav/jobInfoNav/companyNav` | Only if `company` or `companyId` attribute is mapped |

-| 11 | `FODepartment` | `employmentNav/jobInfoNav/departmentNav` | Only if `department` or `departmentId` attribute is mapped |

-| 12 | `FOBusinessUnit` | `employmentNav/jobInfoNav/businessUnitNav` | Only if `businessUnit` or `businessUnitId` attribute is mapped |

-| 13 | `FOCostCenter` | `employmentNav/jobInfoNav/costCenterNav` | Only if `costCenter` or `costCenterId` attribute is mapped |

-| 14 | `FODivision` | `employmentNav/jobInfoNav/divisionNav` | Only if `division` or `divisionId` attribute is mapped |

-| 15 | `FOJobCode` | `employmentNav/jobInfoNav/jobCodeNav` | Only if `jobCode` or `jobCodeId` attribute is mapped |

-| 16 | `FOPayGrade` | `employmentNav/jobInfoNav/payGradeNav` | Only if `payGrade` attribute is mapped |

-| 17 | `FOLocation` | `employmentNav/jobInfoNav/locationNav` | Only if `location` attribute is mapped |

-| 18 | `FOCorporateAddressDEFLT` | `employmentNav/jobInfoNav/addressNavDEFLT` | If mapping contains one of the following attributes: `officeLocationAddress, officeLocationCity, officeLocationZipCode` |

-| 19 | `FOEventReason` | `employmentNav/jobInfoNav/eventReasonNav` | Only if `eventReason` attribute is mapped |

-| 20 | `EmpGlobalAssignment` | `employmentNav/empGlobalAssignmentNav` | Only if `assignmentType` is mapped |

-| 21 | `EmploymentType Picklist` | `employmentNav/jobInfoNav/employmentTypeNav` | Only if `employmentType` is mapped |

-| 22 | `EmployeeClass Picklist` | `employmentNav/jobInfoNav/employeeClassNav` | Only if `employeeClass` is mapped |

-| 23 | `EmplStatus Picklist` | `employmentNav/jobInfoNav/emplStatusNav` | Only if `emplStatus` is mapped |

-| 24 | `AssignmentType Picklist` | `employmentNav/empGlobalAssignmentNav/assignmentTypeNav` | Only if `assignmentType` is mapped |

-| 25 | `Position` | `employmentNav/jobInfoNav/positionNav` | Only if `positioNav` is mapped |

-| 26 | `Manager User` | `employmentNav/jobInfoNav/managerUserNav` | Only if `managerUserNav` is mapped |

-## How full sync works

-Based on the attribute-mapping, during full sync Microsoft Entra provisioning service sends the following "GET" OData API query to fetch effective data of all active and terminated workers.

-> [!div class="mx-tdCol2BreakAll"]

->| Parameter | Description |

->| -|-|

->| OData API Host | Appends https to the *Tenant URL*. Example: `https://api4.successfactors.com` |

->| OData API Endpoint | `/odata/v2/PerPerson` |

->| OData $format query parameter | `json` |

->| OData $filter query parameter | `(personEmpTerminationInfoNav/activeEmploymentsCount ne null) and (lastModifiedDateTime le <CurrentExecutionTime>)` |

->| OData $expand query parameter | This parameter value depends on the attributes mapped. Example: `employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav,phoneNav,emailNav,employmentNav/jobInfoNav/companyNav/countryOfRegistrationNav,employmentNav/jobInfoNav/divisionNav,employmentNav/jobInfoNav/departmentNav` |

->| OData customPageSize query parameter | `100` |

-> [!NOTE]

-> During the full initial sync, both active and terminated workers from SAP SuccessFactors are fetched.

-For each SuccessFactors user, the provisioning service looks for an account in the target (Microsoft Entra ID / on-premises Active Directory) using the matching attribute defined in the mapping. For example: if *personIdExternal* maps to *employeeId* and is set as the matching attribute, then the provisioning service uses the *personIdExternal* value to search for the user with *employeeId* filter. If a user match is found, then it updates the target attributes. If no match is found, then it creates a new entry in the target.

-To validate the data returned by your OData API endpoint for a specific `personIdExternal`, update the `SuccessFactorsAPIEndpoint` in the API query with your API data center server URL and use a tool like [Postman](https://www.postman.com/downloads/) to invoke the query. If the "in" filter doesn't work, you can try the "eq" filter.

-```

-https://[SuccessFactorsAPIEndpoint]/odata/v2/PerPerson?$format=json&

-$filter=(personIdExternal in '[personIdExternalValue]')&

-$expand=employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav,

-phoneNav,phoneNav/phoneTypeNav,emailNav,employmentNav/jobInfoNav/businessUnitNav,employmentNav/jobInfoNav/companyNav,

-employmentNav/jobInfoNav/companyNav/countryOfRegistrationNav,employmentNav/jobInfoNav/costCenterNav,

-employmentNav/jobInfoNav/divisionNav,employmentNav/jobInfoNav/departmentNav,employmentNav/jobInfoNav/jobCodeNav,

-employmentNav/jobInfoNav/locationNav,employmentNav/jobInfoNav/locationNav/addressNavDEFLT,employmentNav/jobInfoNav/payGradeNav,

-employmentNav/empGlobalAssignmentNav,employmentNav/empGlobalAssignmentNav/assignmentTypeNav,employmentNav/jobInfoNav/emplStatusNav,

-employmentNav/jobInfoNav/employmentTypeNav,employmentNav/jobInfoNav/employeeClassNav,employmentNav/jobInfoNav/eventReasonNav

-```

-## How incremental sync works

-After full sync, Microsoft Entra provisioning service maintains `LastExecutionTimestamp` and uses it to create delta queries for retrieving incremental changes. The timestamp attributes present in each SuccessFactors entity, such as `lastModifiedDateTime`, `startDate`, `endDate`, and `latestTerminationDate`, are evaluated to see if the change falls between the `LastExecutionTimestamp` and `CurrentExecutionTime`. If yes, then the entry change is considered to be effective and processed for sync.

-Here's the OData API request template that Microsoft Entra ID uses to query SuccessFactors for incremental changes. You can update the variables `SuccessFactorsAPIEndpoint`, `LastExecutionTimestamp` and `CurrentExecutionTime` in the request template use a tool like [Postman](https://www.postman.com/downloads/) to check what data is returned. Alternatively, you can also retrieve the actual request payload from SuccessFactors by [enabling OData API Audit logs](#enabling-odata-api-audit-logs-in-successfactors).

-```

-https://[SuccessFactorsAPIEndpoint]/odata/v2/PerPerson/$count?$format=json&$filter=(personEmpTerminationInfoNav/activeEmploymentsCount ne null) and

-((lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>') or

-(personalInfoNav/startDate ge datetimeoffset'<LastExecutionTimestamp>' and personalInfoNav/startDate le datetimeoffset'<CurrentExecutionTime>') or

-((personalInfoNav/lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and personalInfoNav/lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>') and (personalInfoNav/startDate le datetimeoffset'<CurrentExecutionTime>' and (personalInfoNav/endDate ge datetimeoffset'<CurrentExecutionTime>' or personalInfoNav/endDate eq null))) or

-(employmentNav/startDate ge datetimeoffset'<LastExecutionTimestamp>' and employmentNav/startDate le datetimeoffset'<CurrentExecutionTime>') or

-((employmentNav/lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and employmentNav/lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>') and (employmentNav/startDate le datetimeoffset'<CurrentExecutionTime>' and (employmentNav/endDate ge datetimeoffset'<CurrentExecutionTime>' or employmentNav/endDate eq null)))

-(employmentNav/jobInfoNav/startDate ge datetimeoffset'<LastExecutionTimestamp>' and employmentNav/jobInfoNav/startDate le datetimeoffset'<CurrentExecutionTime>') or

-((employmentNav/jobInfoNav/lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and employmentNav/jobInfoNav/lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>') and (employmentNav/jobInfoNav/startDate le datetimeoffset'<CurrentExecutionTime>' and (employmentNav/jobInfoNav/endDate ge datetimeoffset'<CurrentExecutionTime>' or employmentNav/jobInfoNav/endDate eq null))) or

-(phoneNav/lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and phoneNav/lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>') or

-(emailNav/lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and emailNav/lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>') or

-(personEmpTerminationInfoNav/latestTerminationDate ge datetimeoffset'<previousDayDateStartTime24hrs>' and personEmpTerminationInfoNav/latestTerminationDate le datetimeoffset'<previousDayDateTime24hrs>') or

-(employmentNav/userNav/lastModifiedDateTime ge datetimeoffset'<LastExecutionTimestamp>' and employmentNav/userNav/lastModifiedDateTime le datetimeoffset'<CurrentExecutionTime>'))

-&$expand=employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav,phoneNav,emailNav,employmentNav/userNav/manager/empInfo,employmentNav/jobInfoNav/companyNav,employmentNav/jobInfoNav/departmentNav,employmentNav/jobInfoNav/locationNav,employmentNav/jobInfoNav/locationNav/addressNavDEFLT,employmentNav/jobInfoNav/locationNav/addressNavDEFLT/stateNav&customPageSize=100

-```

-## How pre-hire processing works

-This section explains how the SAP SuccessFactors connector processes pre-hire records (workers with hire date / start date in future).

-Let's say there is a pre-hire with employeeId "1234" in SuccessFactors Employee Central with start date on 1-June-2023. Let's further assume that this pre-hire record was first created either in Employee Central or in the Onboarding module on 15-May-2023. When the provisioning service first observes this record on 15-May-2023 (either as part of full sync or incremental sync), this record is still in pre-hire state. Due to this, SuccessFactors does not send the provisioning service all attributes (example: userNav/username) associated with the user. Only bare minimum data about the user such as `companyName`, `personIdExternal`, `firstname`, `lastname` and `startDate` is available. To process pre-hires successfully, the following pre-requisites must be met:

-1) The `personIdExternal` attribute must be set as the primary matching identifier (joining property). If you configure a different attribute (example: userName) as the joining property then the provisioning service will not be able to retrieve the pre-hire information.

-2) The `startDate` attribute must be available and it's JSONPath must be set to either `$.employmentNav.results[0].startDate` or `$.employmentNav.results[-1:].startDate`.

-3) The pre-hire record must be in one of the following states in Employee Central: 'active' (t), 'inactive' (f), or 'active_external_suite' (e). For details about these states refer to the [SAP support note 2736579](https://launchpad.support.sap.com/#/notes/0002736579).

-> [!NOTE]

-> For a pre-hire who has no history with the organization, both the [0] and [-1:] index will work for `startDate`. For a pre-hire who is a re-hire or conversion, we cannot deterministically tell the order and this may cause certain rehire/converted workers to get processed on their actual start date. This is a known limitation in the connector.

-During full sync or incremental sync or on-demand provisioning, when the provisioning service encounters a pre-hire record, it sends the following OData query to SuccessFactors with "asOfDate" filter set to the startDate of the user (e.g., asOfDate=2023-06-01).

-```

-https://[SuccessFactorsAPIEndpoint]/odata/v2/PerPerson?$format=json&$

-filter=(personIdExternal in '1234' and employmentNav/userNav/status in 't','f','e')&asOfDate=2023-06-01&$

-expand=employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav,phoneNav,emailNav,employmentNav/userNav/manager/empInfo,employmentNav/jobInfoNav/companyNav,employmentNav/jobInfoNav/costCenterNav,employmentNav/jobInfoNav/divisionNav,employmentNav/jobInfoNav/departmentNav,employmentNav/

-```

-If you are observing issues with pre-hire processing, you can use the above OData request format to query your SuccessFactors instance replacing the API endpoint, `personIdExternal` and `asOfDate` filter with values corresponding to your test scenario.

-## Reading attribute data

-When Microsoft Entra provisioning service queries SuccessFactors, it retrieves a JSON result set. The JSON result set includes many attributes stored in Employee Central. By default, the provisioning schema is configured to retrieve only a subset of those attributes.

-To retrieve more attributes, follow the steps listed:

-

-1. Browse to **Enterprise Applications** -> **SuccessFactors App** -> **Provisioning** -> **Edit Provisioning** -> **attribute-mapping page**.

-1. Scroll down and click **Show advanced options**.

-1. Click on **Edit attribute list for SuccessFactors**.

- > [!NOTE]

- > If the **Edit attribute list for SuccessFactors** option doesn't show in the Microsoft Entra admin center, use the URL *https://portal.azure.com/?Microsoft_AAD_IAM_forceSchemaEditorEnabled=true* to access the page.

-1. The **API expression** column in this view displays the JSONPath expressions used by the connector.

- >[!div class="mx-imgBorder"]

- >

-1. You can either edit an existing JSONPath value or add a new attribute with a valid JSONPath expression to the schema.

-The next section provides a list of common scenarios for editing the JSONPath values.

-## Handling different HR scenarios

-JSONPath is a query language for JSON that is similar to XPath for XML. Like XPath, JSONPath allows for the extraction and filtration of data out of a JSON payload.

-By using JSONPath transformation, you can customize the behavior of the Microsoft Entra provisioning app to retrieve custom attributes and handle scenarios such as rehiring, worker conversion and global assignment.

-This section covers how you can customize the provisioning app for the following HR scenarios:

-* [Retrieving more attributes](#retrieving-more-attributes)

-* [Retrieving custom attributes](#retrieving-custom-attributes)

-* [Mapping employment status to account status](#mapping-employment-status-to-account-status)

-* [Handling worker conversion and rehiring scenarios](#handling-worker-conversion-and-rehiring-scenarios)

-* [Retrieving current active employment record](#retrieving-current-active-employment-record)

-* [Handling global assignment scenario](#handling-global-assignment-scenario)

-* [Handling concurrent jobs scenario](#handling-concurrent-jobs-scenario)

-* [Retrieving position details](#retrieving-position-details)

-* [Provisioning users in the Onboarding module](#provisioning-users-in-the-onboarding-module)

-* [Enabling OData API Audit logs in SuccessFactors](#enabling-odata-api-audit-logs-in-successfactors)

-### Retrieving more attributes

-The default Microsoft Entra SuccessFactors provisioning app schema ships with [90+ predefined attributes](sap-successfactors-attribute-reference.md).

-To add more SuccessFactors attributes to the provisioning schema, use the steps listed:

-1. Use the OData query to retrieve data for a valid test user from Employee Central.

- ```

- https://[SuccessFactorsAPIEndpoint]/odata/v2/PerPerson?$format=json&

- $filter=(personIdExternal in '[personIdExternalValue]')&

- $expand=employmentNav/userNav,employmentNav/jobInfoNav,personalInfoNav,personEmpTerminationInfoNav,

- phoneNav,phoneNav/phoneTypeNav,emailNav,employmentNav/jobInfoNav/businessUnitNav,employmentNav/jobInfoNav/companyNav,

- employmentNav/jobInfoNav/companyNav/countryOfRegistrationNav,employmentNav/jobInfoNav/costCenterNav,

- employmentNav/jobInfoNav/divisionNav,employmentNav/jobInfoNav/departmentNav,employmentNav/jobInfoNav/jobCodeNav,

- employmentNav/jobInfoNav/locationNav,employmentNav/jobInfoNav/locationNav/addressNavDEFLT,employmentNav/jobInfoNav/payGradeNav,

- employmentNav/empGlobalAssignmentNav,employmentNav/empGlobalAssignmentNav/assignmentTypeNav,employmentNav/jobInfoNav/emplStatusNav,

- employmentNav/jobInfoNav/employmentTypeNav,employmentNav/jobInfoNav/employeeClassNav,employmentNav/jobInfoNav/eventReasonNav

- ```

-1. Determine the Employee Central entity associated with the attribute

- * If the attribute is part of *EmpEmployment* entity, then look for the attribute under *employmentNav* node.

- * If the attribute is part of *User* entity, then look for the attribute under *employmentNav/userNav* node.

- * If the attribute is part of *EmpJob* entity, then look for the attribute under *employmentNav/jobInfoNav* node.

-1. Construct the JSON Path associated with the attribute and add this new attribute to the list of SuccessFactors attributes.

- * Example 1: Let's say you want to add the attribute `okToRehire`, which is part of `employmentNav` entity, then use the JSONPath `$.employmentNav.results[0].okToRehire`

- * Example 2: Let's say you want to add the attribute *timeZone*, which is part of *userNav* entity, then use the JSONPath `$.employmentNav.results[0].userNav.timeZone`

- * Example 3: Let's say you want to add the attribute *flsaStatus*, which is part of *jobInfoNav* entity, then use the JSONPath `$.employmentNav.results[0].jobInfoNav.results[0].flsaStatus`

-1. Save the schema.

-1. Restart provisioning.

-### Retrieving custom attributes

-By default, the following custom attributes are predefined in the Microsoft Entra SuccessFactors provisioning app:

-* *custom01-custom15* from the User (userNav) entity

-* *customString1-customString15* from the EmpEmployment (employmentNav) entity called *empNavCustomString1-empNavCustomString15*

-* *customString1-customString15* from the EmpJobInfo (jobInfoNav) entity called *empJobNavCustomString1-empNavJobCustomString15*

-Let's say, in your Employee Central instance, *customString35* attribute in *EmpJobInfo* stores the location description. You want to flow this value to Active Directory *physicalDeliveryOfficeName* attribute. To configure attribute-mapping for this scenario, use the steps:

-1. Edit the SuccessFactors attribute list to add a new attribute called *empJobNavCustomString35*.

-1. Set the JSONPath API expression for this attribute as:

- `$.employmentNav.results[0].jobInfoNav.results[0].customString35`

-1. Save and reload the mapping change in the Microsoft Entra admin center.

-1. In the attribute-mapping blade, map *empJobNavCustomString35* to *physicalDeliveryOfficeName*.

-1. Save the mapping.

-Extending this scenario:

-* If you want to map *custom35* attribute from the *User* entity, then use the JSONPath `$.employmentNav.results[0].userNav.custom35`

-* If you want to map *customString35* attribute from the *EmpEmployment* entity, then use the JSONPath `$.employmentNav.results[0].customString35`

-### Mapping employment status to account status

-By default, the Microsoft Entra SuccessFactors connector uses the `activeEmploymentsCount` field of the `PersonEmpTerminationInfo` object to set account status. You may encounter one of the following issues with this attribute.

-1. There's a known issue where the connector may disable the account of a terminated worker one day prior to the termination on the last day of work. The issue is documented in [knowledge base article 3047486](https://launchpad.support.sap.com/#/notes/3047486).

-1. If the `PersonEmpTerminationInfo` object gets set to null, during termination, then AD account disabling doesn't work because the provisioning engine filters out records where the `personEmpTerminationInfoNav` object is set to null.

-If you're running into any of these issues or prefer mapping employment status to account status, you can update the mapping to expand the `emplStatus` field and use the employment status code present in the field `emplStatus.externalCode`. Based on [SAP support note 2505526](https://launchpad.support.sap.com/#/notes/2505526), here's a list of employment status codes that you can retrieve in the provisioning app.

-* A = Active

-* D = Dormant

-* U = Unpaid Leave

-* P = Paid Leave

-* S = Suspended

-* F = Furlough

-* O = Discarded

-* R = Retired

-* T = Terminated

-Use the steps to update your mapping to retrieve these codes.

-1. Open the attribute-mapping blade of your SuccessFactors provisioning app.

-1. Under **Show advanced options**, click on **Edit SuccessFactors attribute list**.

-1. Find the attribute `emplStatus` and update the JSONPath to `$.employmentNav.results[0].jobInfoNav.results[0].emplStatusNav.externalCode`. The update makes the connector retrieve the employment status codes in the table.

-1. Save the changes.

-1. In the attribute mapping blade, update the expression mapping for the account status flag.

- | Provisioning Job | Account status attribute | Mapping expression |

- | - | | |

- | SuccessFactors to Active Directory User Provisioning | `accountDisabled` | `Switch([emplStatus], "True", "A", "False", "U", "False", "P", "False")` |

- | SuccessFactors to Microsoft Entra user provisioning | `accountEnabled` | `Switch([emplStatus], "False", "A", "True", "U", "True", "P", "True")` |

-1. Save the changes.

-1. Test the configuration using [provision on demand](provision-on-demand.md).

-1. After confirming that sync works as expected, restart the provisioning job.

-### Handling worker conversion and rehiring scenarios

-**About worker conversion scenario:** Worker conversion is the process of converting an existing full-time employee to a contractor or a contractor to a full-time employee. In this scenario, Employee Central adds a new *EmpEmployment* entity along with a new *User* entity for the same *Person* entity. The *User* entity nested under the previous *EmpEmployment* entity is set to null.

-**About rehiring scenarios:** In SuccessFactors, there are two options to process rehiring employees:

-* Option 1: Create a new person profile in Employee Central

-* Option 2: Reuse existing person profile in Employee Central

-If your HR process uses Option 1, then no changes are required to the provisioning schema.

-If your HR process uses Option 2, then Employee Central adds a new *EmpEmployment* entity along with a new *User* entity for the same *Person* entity.

-You can handle both scenarios so that the new employment data shows up when a conversion or rehire occurs. Bulk update the provisioning app schema using the steps listed:

-1. Open the attribute-mapping blade of your SuccessFactors provisioning app.

-1. Scroll down and click **Show advanced options**.

-1. Click on the link **Review your schema here** to open the schema editor.

- >

-1. Click on the **Download** link to save a copy of the schema before editing.

- >

-1. In the schema editor, press Ctrl-H key to open the find-replace control.

-1. In the find text box, copy, and paste the value `$.employmentNav.results[0]`

-1. In the replace text box, copy, and paste the value `$.employmentNav.results[-1:]`. This JSONPath expression returns the latest *EmpEmployment* record.

- >

-1. Click on the "replace all" option to update the schema.

-1. Save the schema.

-1. The above process updates all JSONPath expressions as follows:

- * Old JSONPath: `$.employmentNav.results[0].jobInfoNav.results[0].departmentNav.name_localized`

- * New JSONPath: `$.employmentNav.results[-1:].jobInfoNav.results[0].departmentNav.name_localized`

-1. Test the configuration using [provision on demand](provision-on-demand.md).

-1. After confirming that sync works as expected, restart the provisioning job.

-> [!NOTE]

-> The approach described above only works if SAP SuccessFactors returns the employment objects in ascending order, where the latest employment record is always the last record in the *employmentNav* results array. The order in which multiple employment records are returned isn't guaranteed by SuccessFactors. If your SuccessFactors instance has multiple employment records corresponding to a worker and you always want to retrieve attributes associated with the active employment record, use steps described in the next section.

-### Retrieving current active employment record

-Using the JSONPath root of `$.employmentNav.results[0]` or `$.employmentNav.results[-1:]` to fetch employment records works in most scenarios and keeps the configuration simple. However, depending on how your SuccessFactors instance is configured, there may be a need to update this configuration to ensure that the connector always fetches the latest active employment record.

-This section describes how you can update the JSONPath settings to definitely retrieve the current active employment record of the user. It also handles worker conversion and rehiring scenarios.

-1. Open the attribute-mapping blade of your SuccessFactors provisioning app.

-1. Scroll down and click **Show advanced options**.

-1. Click on the link **Review your schema here** to open the schema editor.

-1. Click on the **Download** link to save a copy of the schema before editing.

-1. In the schema editor, press Ctrl-H key to open the find-replace control.

-1. Perform the following find replace operations. Ensure there's no leading or trailing space when performing the find-replace operations. If you're using `[-1:]` index instead of `[0]`, then update the *string-to-find* field accordingly.

- | **String to find** | **String to use for replace** | **Purpose** |

- | | -- | |

- | `$.employmentNav.results[0].<br>jobInfoNav.results[0].emplStatus` | `$.employmentNav..jobInfoNav..results[?(@.emplStatusNav.externalCode == 'A' || @.emplStatusNav.externalCode == 'U' || @.emplStatusNav.externalCode == 'P' )].emplStatusNav.externalCode` | With this find-replace, we're adding the ability to expand emplStatusNav OData object. |

- | `$.employmentNav.results[0].<br>jobInfoNav.results[0]` | `$.employmentNav..jobInfoNav..results[?(@.emplStatusNav.externalCode == 'A' || @.emplStatusNav.externalCode == 'U' || @.emplStatusNav.externalCode == 'P')]` | With this find-replace, we instruct the connector to always retrieve attributes associated with the active SuccessFactors EmpJobInfo record. Attributes associated with terminated/inactive records in SuccessFactors are ignored. |

- | `$.employmentNav.results[0]` | `$.employmentNav..results[?(@.jobInfoNav..results[?(@.emplStatusNav.externalCode == 'A' || @.emplStatusNav.externalCode == 'U' || @.emplStatusNav.externalCode == 'P')])]` | With this find-replace, we instruct the connector to always retrieve attributes associated with the active SuccessFactors Employment record. Attributes associated with terminated/inactive records in SuccessFactors are ignored. |

-1. Save the schema.

-1. The above process updates all JSONPath expressions.

-1. For prehire processing to work, the JSONPath associated with `startDate` attribute must use either `[0]` or `[-1:]` index. Under **Show advanced options**, click on **Edit SuccessFactors attribute list**. Find the attribute `startDate` and set it to the value `$.employmentNav.results[-1:].startDate`

-1. Save the schema.

-1. To ensure that terminations are processed as expected, you can use one of the following settings in the attribute mapping section.

-

- | Provisioning Job | Account status attribute | Expression to use if account status is based on "activeEmploymentsCount" | Expression to use if account status is based on "emplStatus" value |

- | -- | | -- | - |

- | SuccessFactors to Active Directory User Provisioning | `accountDisabled` | `Switch([activeEmploymentsCount], "False", "0", "True")` | `Switch([emplStatus], "True", "A", "False", "U", "False", "P", "False")` |

- | SuccessFactors to Microsoft Entra user provisioning | `accountEnabled` | `Switch([activeEmploymentsCount], "True", "0", "False")` | `Switch([emplStatus], "False", "A", "True", "U", "True", "P", "True")` |

-1. Save your changes. 1.

-1. Test the configuration using [provision on demand](provision-on-demand.md).

-1. After confirming that sync works as expected, restart the provisioning job.

-### Handling global assignment scenario

-When a user in Employee Central is processed for global assignment, SuccessFactors adds a new *EmpEmployment* entity and sets the *assignmentClass* to "GA". It also creates new *User* entity. Thus, the user now has:

-* One *EmpEmployment* + *User* entity that corresponds to home assignment with *assignmentClass* set to "ST" and

-* Another *EmpEmployment* + *User* entity that corresponds to the global assignment with *assignmentClass* set to "GA"

-To fetch attributes belonging to the standard assignment and global assignment user profile, use the steps listed:

-1. Open the attribute-mapping blade of your SuccessFactors provisioning app.

-1. Scroll down and click **Show advanced options**.

-1. Click on the link **Review your schema here** to open the schema editor.

-1. Click on the **Download** link to save a copy of the schema before editing.

-1. In the schema editor, press Ctrl-H key to open the find-replace control.

-1. In the find text box, copy, and paste the value `$.employmentNav.results[0]`

-1. In the replace text box, copy, and paste the value `$.employmentNav.results[?(@.assignmentClass == 'ST')]`. Note the whitespace surrounding the == operator, which is important for successful processing of the JSONPath expression.

-1. Click on the "replace all" option to update the schema.

-1. Save the schema.

-1. The above process updates all JSONPath expressions as follows:

- * Old JSONPath: `$.employmentNav.results[0].jobInfoNav.results[0].departmentNav.name_localized`

- * New JSONPath: `$.employmentNav.results[?(@.assignmentClass == 'ST')].jobInfoNav.results[0].departmentNav.name_localized`

-1. Reload the attribute-mapping blade of the app.

-1. Scroll down and click **Show advanced options**.

-1. Click on **Edit attribute list for SuccessFactors**.

-1. Add new attributes to fetch global assignment data. For example: if you want to fetch the department name associated with a global assignment profile, you can add the attribute *globalAssignmentDepartment* with the JSONPath expression set to `$.employmentNav.results[?(@.assignmentClass == 'GA')].jobInfoNav.results[0].departmentNav.name_localized`.

-1. You can now either flow both department values to Active Directory attributes or selectively flow a value using expression mapping. Example: the expression sets the value of AD *department* attribute to *globalAssignmentDepartment* if present, else it sets the value to *department* associated with standard assignment.

- * `IIF(IsPresent([globalAssignmentDepartment]),[globalAssignmentDepartment],[department])`

-1. Save the mapping.

-1. Test the configuration using [provision on demand](provision-on-demand.md).

-1. After confirming that sync works as expected, restart the provisioning job.

-### Handling concurrent jobs scenario

-When a user in Employee Central has concurrent/multiple jobs, there are two *EmpEmployment* and *User* entities with *assignmentClass* set to "ST".

-To fetch attributes belonging to both jobs, use the steps listed:

-1. Open the attribute-mapping blade of your SuccessFactors provisioning app.

-1. Scroll down and click **Show advanced options**.

-1. Click on **Edit attribute list for SuccessFactors**.

-1. Let's say you want to pull the department associated with job 1 and job 2. The predefined attribute *department* already fetches the value of department for the first job. You can define a new attribute called *secondJobDepartment* and set the JSONPath expression to `$.employmentNav.results[1].jobInfoNav.results[0].departmentNav.name_localized`

-1. You can now either flow both department values to Active Directory attributes or selectively flow a value using expression mapping.

-1. Save the mapping.

-1. Test the configuration using [provision on demand](provision-on-demand.md).

-1. After confirming that sync works as expected, restart the provisioning job.

-

-### Retrieving position details

-The SuccessFactors connector supports expansion of the position object. To expand and retrieve position object attributes such as job level or position names in a specific language, you can use JSONPath expressions as shown.

-| Attribute Name | JSONPath expression |

-| -- | - |

-| positionJobLevel | $.employmentNav.results[0].jobInfoNav.results[0].positionNav.jobLevel |

-| positionNameFR | $.employmentNav.results[0].jobInfoNav.results[0].positionNav.externalName_fr_FR |

-| positionNameDE | $.employmentNav.results[0].jobInfoNav.results[0].positionNav.externalName_de_DE |

-### Provisioning users in the Onboarding module

-Inbound user provisioning from SAP SuccessFactors to on premises Active Directory and Microsoft Entra ID now supports advance provisioning of prehires present in the SAP SuccessFactors Onboarding 2.0 module. When the Microsoft Entra provisioning service encounters a new hire profile with a future start date, it queries SAP SuccessFactors to get new hires with one of the following status codes: `active`, `inactive`, `active_external_suite`. The status code `active_external_suite` corresponds to prehires present in the SAP SuccessFactors Onboarding 2.0 module. For a description of these status codes, refer to [SAP support note 2736579](https://launchpad.support.sap.com/#/notes/0002736579).

-The default behavior of the provisioning service is to process prehires in the Onboarding module.

-If you want to exclude processing of prehires in the Onboarding module, update your provisioning job configuration as follows:

-1. Open the attribute-mapping blade of your SuccessFactors provisioning app.

-1. Under show advanced options, edit the SuccessFactors attribute list to add a new attribute called `userStatus`.

-1. Set the JSONPath API expression for this attribute as: `$.employmentNav.results[0].userNav.status`

-1. Save the schema to return back to the attribute mapping blade.

-1. Edit the Source Object scope to apply a scoping filter `userStatus NOT EQUALS`

-1. Save the mapping and validate that the scoping filter works using provisioning on demand.

-### Enabling OData API Audit logs in SuccessFactors

-The Microsoft Entra SuccessFactors connector uses SuccessFactors OData API to retrieve changes and provision users. If you observe issues with the provisioning service and want to confirm what data was retrieved from SuccessFactors, you can enable OData API Audit logs in SuccessFactors. Retrieve the request payload sent by Microsoft Entra ID from the audit logs. To troubleshoot, you can copy this request payload in a tool like [Postman](https://www.postman.com/downloads/), set it up to use the same API user that is used by the connector and see if it returns the desired changes from SuccessFactors.

-## Writeback scenarios

-This section covers different write-back scenarios. It recommends configuration approaches based on how email and phone number is set up in SuccessFactors.

-### Supported scenarios for phone and email write-back

-| \# | Scenario requirement | Email primary <br> flag value | Business phone <br> primary flag value | Cell phone <br> primary flag value | Business phone <br> mapping | Cell phone <br> mapping |

-|--|--|--|--|--|--|--|

-| 1 | * Only set business email as primary. <br> * Don't set phone numbers. | true | true | false | \[Not Set\] | \[Not Set\] |

-| 2 | * In SuccessFactors, business email and business phone is primary <br> * Always flow Microsoft Entra telephone number to business phone and mobile to cell phone. | true | true | false | telephoneNumber | mobile |

-| 3 | * In SuccessFactors, business email and cell phone is primary <br> * Always flow Microsoft Entra telephone number to business phone and mobile to cell phone | true | false | true | telephoneNumber | mobile |

-| 4 | * In SuccessFactors business email is primary. <br> * In Microsoft Entra ID, check if work telephone number is present, if present, then check if mobile number is also present. Mark work telephone number as primary only if mobile number isn't present. | true | Use expression mapping: `IIF(IsPresent([telephoneNumber]), IIF(IsPresent([mobile]),"false", "true"), "false")` | Use expression mapping: `IIF(IsPresent([mobile]),"false", "true")` | telephoneNumber | mobile |

-| 5 | * In SuccessFactors business email and business phone is primary. <br> * In Microsoft Entra ID, if mobile is available, then set it as the business phone, else use telephoneNumber. | true | true | false | `IIF(IsPresent([mobile]), [mobile], [telephoneNumber])` | \[Not Set\] |

-* If there's no mapping for phone number in the write-back attribute-mapping, then only email is included in the write-back.

-* During new hire onboarding in Employee Central, business email and phone number may not be available. If setting business email and business phone as primary is mandatory during onboarding, you can set a dummy value for business phone and email during new hire creation. After some time, the write-back app updates the value.

-

-### Enabling writeback with UserID

-The SuccessFactors Writeback app uses the following logic to update the User object attributes:

-* As a first step, it looks for *userId* attribute in the changeset. If it's present, then it uses "UserId" for making the SuccessFactors API call.

-* If *userId* isn't found, then it defaults to using the *personIdExternal* attribute value.

-Usually the *personIdExternal* attribute value in SuccessFactors matches the *userId* attribute value. However, in scenarios such as rehiring and worker conversion, an employee in SuccessFactors may have two employment records, one active and one inactive. In such scenarios, to ensure that write-back updates the active user profile, update the configuration of the SuccessFactors provisioning apps as described. This configuration ensures that *userId* is always present in the changeset visible to the connector and is used in the SuccessFactors API call.

-1. Open the SuccessFactors to Microsoft Entra user provisioning app or SuccessFactors to on-premises AD user provisioning app.

-1. Ensure that `extensionAttribute[1-15]` in Microsoft Entra ID always stores the `userId` of every worker's active employment record. The record maps SuccessFactors `userId` attribute to `extensionAttribute[1-15]` in Microsoft Entra ID.

- > [!div class="mx-imgBorder"]

- > 

-1. For guidance regarding JSONPath settings, refer to the section [Handling worker conversion and rehiring scenarios](#handling-worker-conversion-and-rehiring-scenarios) to ensure the *userId* value of the active employment record flows into Microsoft Entra ID.

-1. Save the mapping.

-1. Run the provisioning job to ensure that the *userId* values flow into Microsoft Entra ID.

- > [!NOTE]

- > If you're using SuccessFactors to on-premises Active Directory user provisioning, configure Microsoft Entra Connect to sync the *userId* attribute value from on-premises Active Directory to Microsoft Entra ID.

-1. Open the SuccessFactors Writeback app in the Azure portal.

-1. Map the desired *extensionAttribute* that contains the userId value to the SuccessFactors *userId* attribute.

- > [!div class="mx-imgBorder"]

- > 

-1. Save the mapping.

-1. Go to *Attribute mapping -> Advanced -> Review Schema* to open the JSON schema editor.

-1. Download a copy of the schema as backup.

-1. In the schema editor, hit Ctrl-F and search for the JSON node containing the userId mapping, where it's mapped to a source Microsoft Entra attribute.

-1. Update the flowBehavior attribute from "FlowWhenChanged" to "FlowAlways" as shown.

- > [!div class="mx-imgBorder"]

- > 

-1. Save the mapping and test the write-back scenario with provisioning-on-demand.

-### Unsupported scenarios for phone and email write-back

-* In Employee Central, during onboarding personal email and personal phone is set as primary. The write-back app can't switch this setting and set business email and business phone as primary.

-* In Employee Central, business phone is set as primary. The write-back app can't change this and set cell phone as primary.

-* The write-back app can't read the current primary flag settings and use the same values for the write operation. The flag values configured in the attribute-mapping are always be used.

-## Next steps

-* [Learn how to configure SuccessFactors to Active Directory provisioning](../saas-apps/sap-successfactors-inbound-provisioning-tutorial.md)

-* [Learn how to configure writeback to SuccessFactors](../saas-apps/sap-successfactors-writeback-tutorial.md)

-* [Learn more about supported SuccessFactors Attributes for inbound provisioning](sap-successfactors-attribute-reference.md)

-description: Using SCIM and the Microsoft Graph together to provision users and enrich your application with the data it needs in Microsoft Entra ID.

-# Using SCIM and Microsoft Graph together to provision users and enrich your application with the data it needs

-**Target audience:** This article is targeted towards developers building applications to be integrated with Microsoft Entra ID. If you're looking to use applications already integrated with Microsoft Entra ID, such as Zoom, ServiceNow, and DropBox, you can skip this article and review the application specific [tutorials](../saas-apps/tutorial-list.md) or review [how the provisioning service works](./how-provisioning-works.md).

-**Common scenarios**

-Microsoft Entra ID provides an out of the box service for provisioning and an extensible platform to build your applications on. The decision tree outlines how a developer would use [SCIM](https://aka.ms/scimoverview) and the [Microsoft Graph](/graph/overview) to automate provisioning.

-> [!div class="checklist"]

-> * Automatically create users in my application

-> * Automatically remove users from my application when they shouldn't have access anymore

-> * Integrate my application with multiple identity providers for provisioning

-> * Enrich my application with data from Microsoft services such as Teams, Outlook, and Office.

-> * Automatically create, update, and delete users and groups in Microsoft Entra ID and Active Directory

-

-## Scenario 1: Automatically create users in my app

-Today, IT admins provision users by manually creating user accounts or periodically uploading CSV files into my application. The process is time consuming for customers and slows down adoption of my application. All I need is basic user information such as name, email, and userPrincipalName to create a user.

-**Recommendation**:

-* If your customers use various IdPs and you do not want to maintain a sync engine to integrate with each, support a SCIM compliant [/Users](https://aka.ms/scimreferencecode) endpoint. Your customers will be able to easily use this endpoint to integrate with the Microsoft Entra provisioning service and automatically create user accounts when they need access. You can build the endpoint once and it will be compatible with all IdPs. Check out the example request below for how a user would be created using SCIM.

-* If you require user data found on the user object in Microsoft Entra ID and other data from across Microsoft, consider building a SCIM endpoint for user provisioning and calling into the Microsoft Graph to get the rest of the data.

-```json

-POST /Users

-{

- "schemas": [

- "urn:ietf:params:scim:schemas:core:2.0:User",

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],

- "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",

- "userName": "BillG",

- "active": true,

- "meta": {

- "resourceType": "User"

- },

- "name": {

- "formatted": "Bill Gates",

- "familyName": "Gates",

- "givenName": "Bill"

- },

- "roles": []

-}

-```

-## Scenario 2: Automatically remove users from my app

-The customers using my application are security focused and have governance requirements to remove accounts when employees don't need them anymore. How can I automate deprovisioning from my application?

-**Recommendation:** Support a SCIM compliant /Users endpoint. The Microsoft Entra provisioning service will send requests to disable and delete when the user shouldn't have access anymore. We recommend supporting both disabling and deleting users. See the examples below for what a disable and delete request look like.

-Disable user

-```json

-PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

-{

- "Operations": [

- {

- "op": "Replace",

- "path": "active",

- "value": false

- }

- ],

- "schemas": [

- "urn:ietf:params:scim:api:messages:2.0:PatchOp"

- ]

-}

-```

-Delete user

-```json

-DELETE /Users/5171a35d82074e068ce2 HTTP/1.1

-```

-## Scenario 3: Automate managing group memberships in my app

-My application relies on groups for access to various resources, and customers want to reuse the groups that they have in Microsoft Entra ID. How can I import groups from Microsoft Entra ID and keep them updated as the memberships change?

-**Recommendation:** Support a SCIM compliant /Groups [endpoint](https://aka.ms/scimreferencecode). The Microsoft Entra provisioning service will take care of creating groups and managing membership updates in your application.

-## Scenario 4: Enrich my app with data from Microsoft services such as Teams, Outlook, and OneDrive

-My application is built into Microsoft Teams and relies on message data. In addition, we store files for users in OneDrive. How can I enrich my application with the data from these services and across Microsoft?

-**Recommendation:** The [Microsoft Graph](/graph/) is your entry point to access Microsoft data. Each workload exposes APIs with the data that you need. The Microsoft graph can be used along with [SCIM provisioning](./use-scim-to-provision-users-and-groups.md) for the scenarios above. You can use SCIM to provision basic user attributes into your application while calling into graph to get any other data that you need.

-<a name='scenario-5-track-changes-in-microsoft-services-such-as-teams-outlook-and-azure-ad'></a>

-## Scenario 5: Track changes in Microsoft services such as Teams, Outlook, and Microsoft Entra ID

-I need to be able to track changes to Teams and Outlook messages and react to them in real time. How can I get these changes pushed to my application?

-**Recommendation:** The Microsoft Graph provides [change notifications](/graph/webhooks) and [change tracking](/graph/delta-query-overview) for various resources. Note the following limitations of change notifications:

-For the reasons above, developers often use change notifications along with change tracking for synchronization scenarios.

-<a name='scenario-6-provision-users-and-groups-in-azure-ad'></a>

-## Scenario 6: Provision users and groups in Microsoft Entra ID

-My application creates information about a user that customers need in Microsoft Entra ID. This could be an HR application than manages hiring, a communications app that creates phone numbers for users, or some other app that generates data that would be valuable in Microsoft Entra ID. How do I populate the user record in Microsoft Entra ID with that data?

-**Recommendation** The Microsoft graph exposes /Users and /Groups endpoints that you can integrate with today to provision users into Microsoft Entra ID. Please note that Microsoft Entra ID doesn't support writing those users back into Active Directory.

-> [!NOTE]

-> Microsoft has a provisioning service that pulls in data from HR applications such as Workday and SuccessFactors. These integrations are built and managed by Microsoft. For onboarding a new HR application to our service, you can request it on [UserVoice](https://feedback.azure.com/d365community/forum/22920db1-ad25-ec11-b6e6-000d3a4f0789).

-## Related articles

-description: This tutorial describes how to use the Microsoft Entra SCIM Validator to validate that your provisioning server is compatible with the Azure SCIM client.

-# Tutorial: Validate a SCIM endpoint

-This tutorial describes how to use the Microsoft Entra SCIM Validator to validate that your provisioning server is compatible with the Azure SCIM client. The tutorial is intended for developers who want to build a SCIM compatible server to manage their identities with the Microsoft Entra provisioning service.

-In this tutorial, you learn how to:

-> [!div class="checklist"]

-> * Select a testing method

-> * Configure the testing method

-> * Validate your SCIM endpoint

-## Prerequisites

-## Select a testing method

-The first step is to select a testing method to validate your SCIM endpoint.

-1. Open your web browser and navigate to the SCIM Validator: [https://scimvalidator.microsoft.com/](https://scimvalidator.microsoft.com/).

-1. Select one of the three test options. You can use default attributes, automatically discover the schema, or upload a schema.

- :::image type="content" source="./media/scim-validator-tutorial/scim-validator.png" alt-text="Screenshot of SCIM Validator main page." lightbox="./media/scim-validator-tutorial/scim-validator.png":::

-**Use default attributes** - The system provides the default attributes, and you modify them to meet your need.

-**Discover schema** - If your end point supports /Schema, this option lets the tool discover the supported attributes. We recommend this option as it reduces the overhead of updating your app as you build it out.

-**Upload Microsoft Entra Schema** - Upload the schema you've downloaded from your sample app on Microsoft Entra ID.

-## Configure the testing method

-Now that you've selected a testing method, the next step is to configure it.

-1. If you're using the default attributes option, then fill in all of the indicated fields.

-2. If you're using the discover schema option, then enter the SCIM endpoint URL and token.

-3. If you're uploading a schema, then select your .json file to upload. The option accepts a .json file exported from your sample app on the Microsoft Entra admin center. To learn how to export a schema, see [How-to: Export provisioning configuration and roll back to a known good state](export-import-provisioning-configuration.md#export-your-provisioning-configuration).

-> [!NOTE]

-> To test *group attributes*, make sure to select **Enable Group Tests**.

-4. Edit the list attributes as desired for both the user and group types using the ΓÇÿAdd AttributeΓÇÖ option at the end of the attribute list and minus (-) sign on the right side of the page.

-5. Select the joining property from both the user and group attributes list.

-> [!NOTE]

-> The joining property, also known as matching attribute, is an attribute that user and group resources can be uniquely queried on at the source and matched in the target system.

-## Validate your SCIM endpoint

-Finally, you need to test and validate your endpoint.

-1. Select **Test Schema** to begin the test.

-1. Review the results with a summary of passed and failed tests.

-1. Select the **show details** tab and review and fix issues.

-1. Continue to test your schema until all tests pass.

- :::image type="content" source="./media/scim-validator-tutorial/scim-validator-results.png" alt-text="Screenshot of SCIM Validator results page." lightbox="./media/scim-validator-tutorial/scim-validator-results.png":::

-### Use Postman to test endpoints (optional)

-In addition to using the SCIM Validator tool, you can also use Postman to validate an endpoint. This example provides a set of tests in Postman. The example validates create, read, update, and delete (CRUD) operations. The operations are validated on users and groups, filtering, updates to group membership, and disabling users.

-The endpoints are in the `{host}/scim/` directory, and you can use standard HTTP requests to interact with them. To modify the `/scim/` route, see *ControllerConstant.cs* in **AzureADProvisioningSCIMreference** > **ScimReferenceApi** > **Controllers**.

-> [!NOTE]

-> You can only use HTTP endpoints for local tests. The Microsoft Entra provisioning service requires that your endpoint support HTTPS.

-1. Download [Postman](https://www.postman.com/downloads/) and start the application.

-1. Copy and paste this link into Postman to import the test collection: `https://aka.ms/ProvisioningPostman`.

- 

-1. Create a test environment that has these variables:

- |Environment|Variable|Value|

- |-|-|-|

- |Run the project locally by using IIS Express|||

- ||**Server**|`localhost`|

- ||**Port**|`:44359` *(don't forget the **`:`**)*|

- ||**Api**|`scim`|

- |Run the project locally by using Kestrel|||

- ||**Server**|`localhost`|

- ||**Port**|`:5001` *(don't forget the **`:`**)*|

- ||**Api**|`scim`|

- |Host the endpoint in Azure|||

- ||**Server**|*(input your SCIM URL)*|

- ||**Port**|*(leave blank)*|

- ||**Api**|`scim`|

-1. Use **Get Key** from the Postman collection to send a **GET** request to the token endpoint and retrieve a security token to be stored in the **token** variable for subsequent requests.

- 

- > [!NOTE]

- > To make a SCIM endpoint secure, you need a security token before you connect. The tutorial uses the `{host}/scim/token` endpoint to generate a self-signed token.

-That's it! You can now run the **Postman** collection to test the SCIM endpoint functionality.

-## Clean up resources

-If you created any Azure resources in your testing that are no longer needed, don't forget to delete them.

-<a name='known-issues-with-azure-ad-scim-validator'></a>

-## Known Issues with Microsoft Entra SCIM Validator

-## Next steps

-description: Learn how to override the default behavior of deprovisioning out of scope users in Microsoft Entra ID.

-# Skip deletion of user accounts that go out of scope in Microsoft Entra ID

-By default, the Microsoft Entra provisioning engine soft deletes or disables users that go out of scope. However, for certain scenarios like Workday to AD User Inbound Provisioning, this behavior may not be the expected and you may want to override this default behavior.

-This article describes how to use the Microsoft Graph API and the Microsoft Graph API explorer to set the flag ***SkipOutOfScopeDeletions*** that controls the processing of accounts that go out of scope.

-* If ***SkipOutOfScopeDeletions*** is set to 0 (false), accounts that go out of scope are disabled in the target.

-* If ***SkipOutOfScopeDeletions*** is set to 1 (true), accounts that go out of scope aren't disabled in the target. This flag is set at the *Provisioning App* level and can be configured using the Graph API.

-Because this configuration is widely used with the *Workday to Active Directory user provisioning* app, the following steps include screenshots of the Workday application. However, the configuration can also be used with *all other apps*, such as ServiceNow, Salesforce, and Dropbox. To successfully complete this procedure, you must have first set up app provisioning for the app. Each app has its own configuration article. For example, to configure the Workday application, see [Tutorial: Configure Workday to Microsoft Entra user provisioning](../saas-apps/workday-inbound-cloud-only-tutorial.md). SkipOutOfScopeDeletions does not work for cross-tenant synchronization.

-## Step 1: Retrieve your Provisioning App Service Principal ID (Object ID)

-1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least a [Application Administrator](../roles/permissions-reference.md#application-administrator).

-1. Browse to **Identity** > **Applications** > **Enterprise applications**.

-1. Select your application and go to Properties section of your provisioning app. In this example we are using Workday.

-1. Copy the GUID value in the *Object ID* field. This value is also called the **ServicePrincipalId** of your app and it's used in Graph Explorer operations.

- 

-## Step 2: Sign into Microsoft Graph Explorer

-1. Launch [Microsoft Graph Explorer](https://developer.microsoft.com/graph/graph-explorer)

-1. Click on the "Sign-In with Microsoft" button and sign-in using Microsoft Entra Global Administrator or App Admin credentials.

- 

-1. Upon successful sign-in, the user account details appear in the left-hand pane.

-## Step 3: Get existing app credentials and connectivity details

-In the Microsoft Graph Explorer, run the following GET query replacing [servicePrincipalId] with the **ServicePrincipalId** extracted from the [Step 1](#step-1-retrieve-your-provisioning-app-service-principal-id-object-id).

-```http

- GET https://graph.microsoft.com/beta/servicePrincipals/[servicePrincipalId]/synchronization/secrets

-```

- 

-Copy the Response into a text file. It looks like the JSON text shown, with values highlighted in yellow specific to your deployment. Add the lines highlighted in green to the end and update the Workday connection password highlighted in blue.

- 

-Here's the JSON block to add to the mapping.

-```json

-{

- "key": "SkipOutOfScopeDeletions",

- "value": "True"

-}

-```

-## Step 4: Update the secrets endpoint with the SkipOutOfScopeDeletions flag

-In the Graph Explorer, run the command to update the secrets endpoint with the ***SkipOutOfScopeDeletions*** flag.

-In the URL, replace [servicePrincipalId] with the **ServicePrincipalId** extracted from the [Step 1](#step-1-retrieve-your-provisioning-app-service-principal-id-object-id).

-```http

- PUT https://graph.microsoft.com/beta/servicePrincipals/[servicePrincipalId]/synchronization/secrets

-```

-Copy the updated text from Step 3 into the "Request Body".

- 

-Click on ΓÇ£Run QueryΓÇ¥.

-You should get the output as "Success ΓÇô Status Code 204". If you receive an error, you may need to check that your account has Read/Write permissions for ServicePrincipalEndpoint. You can find this permission by clicking on the *Modify permissions* tab in Graph Explorer.

- 

-## Step 5: Verify that out of scope users donΓÇÖt get disabled

-You can test this flag results in expected behavior by updating your scoping rules to skip a specific user. In the example, we're excluding the employee with ID 21173 (who was earlier in scope) by adding a new scoping rule:

- 

-In the next provisioning cycle, the Microsoft Entra provisioning service identifies that the user 21173 has gone out of scope. If the `SkipOutOfScopeDeletions` property is enabled, then the synchronization rule for that user displays a message as shown:

- 

-description: This tutorial describes how to provision users from Microsoft Entra ID into a SQL database.

-# Configuring Microsoft Entra ID to provision users into a SQL database

-## Next steps

-description: Learn to develop a SCIM endpoint, integrate your SCIM API with Microsoft Entra ID, and automatically provision users and groups into your cloud applications.

-# Tutorial: Develop a sample SCIM endpoint in Microsoft Entra ID

-This tutorial describes how to deploy the SCIM [reference code](https://aka.ms/scimreferencecode) with [Azure App Service](/azure/app-service/). Then, test the code by using Postman or by integrating with the Microsoft Entra provisioning service. The tutorial is intended for developers who want to get started with SCIM, or anyone interested in testing a [SCIM endpoint](./use-scim-to-provision-users-and-groups.md).

-In this tutorial, you learn how to:

-> [!div class="checklist"]

->

-> * Deploy your SCIM endpoint in Azure.

-> * Test your SCIM endpoint.

-## Deploy your SCIM endpoint in Azure

-The steps here deploy the SCIM endpoint to a service by using [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) and [Visual Studio Code](https://code.visualstudio.com/) with [Azure App Service](/azure/app-service/). The SCIM reference code can run locally, hosted by an on-premises server, or deployed to another external service.

-### Get and deploy the sample app

-Go to the [reference code](https://github.com/AzureAD/SCIMReferenceCode) from GitHub and select **Clone or download**. Select **Open in Desktop**, or copy the link, open Visual Studio, and select **Clone or check out code** to enter the copied link and make a local copy. Save the files into a folder where the total length of the path is 260 or fewer characters.

-# [Visual Studio](#tab/visual-studio)

-1. In Visual Studio, make sure to sign in to the account that has access to your hosting resources.

-1. In Solution Explorer, open *Microsoft.SCIM.sln* and right-click the *Microsoft.SCIM.WebHostSample* file. Select **Publish**.

- 

- > [!NOTE]

- > To run this solution locally, double-click the project and select **IIS Express** to launch the project as a webpage with a local host URL.

-1. Select **Create profile** and make sure that **App Service** and **Create new** are selected.

- 

-1. Step through the dialog options and rename the app to a name of your choice. This name is used in both the app and the SCIM endpoint URL.

- 

-1. Select the resource group to use and select **Publish**.

- 

-# [Visual Studio Code](#tab/visual-studio-code)

-1. In Visual Studio Code, make sure to sign in to the account that has access to your hosting resources.

-1. In Visual Studio Code, open the folder that contains the *Microsoft.SCIM.sln* file.

-1. Open the Visual Studio Code integrated [terminal](https://code.visualstudio.com/docs/terminal/basics) and run the [dotnet restore](/nuget/consume-packages/install-use-packages-dotnet-cli#restore-packages) command. This command restores the packages listed in the project files.

-1. In the terminal, change the directory using the `cd Microsoft.SCIM.WebHostSample` command

-1. To run your app locally, in the terminal, run the .NET CLI command. The [dotnet run](/dotnet/core/tools/dotnet-run) runs the Microsoft.SCIM.WebHostSample project using the [development environment](/aspnet/core/fundamentals/environments#set-environment-on-the-command-line).

- ```dotnetcli

- dotnet run --environment Development

- ```

-1. If not installed, add [Azure App Service for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice) extension.

-1. To deploy the Microsoft.SCIM.WebHostSample app to Azure App Services, [create a new App Services](/azure/app-service/quickstart-dotnetcore?tabs=net60&pivots=development-environment-vscode#2-publish-your-web-app).

-1. In the Visual Studio Code terminal, run the .NET CLI command. This command generates a deployable publish folder for the app in the bin/debug/publish directory.

- ```dotnetcli

- dotnet publish -c Debug

- ```

-1. In the Visual Studio Code explorer, right-click on the generated **publish** folder, and select Deploy to Web App.

-1. A new workflow opens in the command palette at the top of the screen. Select the **Subscription** you would like to publish your app to.

-1. Select the **App Service** web app you created earlier.

-1. If Visual Studio Code prompts you to confirm, select **Deploy**. The deployment process may take a few moments. When the process completes, a notification should appear in the bottom right corner prompting you to browse to the deployed app.

-### Configure the App Service

-Go to the application in **Azure App Service** > **Configuration** and select **New application setting** to add the *Token__TokenIssuer* setting with the value `https://sts.windows.net/<tenant_id>/`. Replace `<tenant_id>` with your Microsoft Entra tenant ID. If you want to test the SCIM endpoint by using [Postman](https://github.com/AzureAD/SCIMReferenceCode/wiki/Test-Your-SCIM-Endpoint), add an *ASPNETCORE_ENVIRONMENT* setting with the value `Development`.

-

-When you test your endpoint with an enterprise application in the [Microsoft Entra admin center](use-scim-to-provision-users-and-groups.md#integrate-your-scim-endpoint-with-the-azure-ad-provisioning-service), you have two options. You can keep the environment in `Development` and provide the testing token from the `/scim/token` endpoint, or you can change the environment to `Production` and leave the token field empty.

-That's it! Your SCIM endpoint is now published, and you can use the Azure App Service URL to test the SCIM endpoint.

-## Test your SCIM endpoint

-Requests to a SCIM endpoint require authorization. The SCIM standard has multiple options available. Requests can use cookies, basic authentication, TLS client authentication, or any of the methods listed in [RFC 7644](https://tools.ietf.org/html/rfc7644#section-2).

-Be sure to avoid methods that aren't secure, such as username and password, in favor of a more secure method such as OAuth. Microsoft Entra ID supports long-lived bearer tokens (for gallery and non-gallery applications) and the OAuth authorization grant (for gallery applications).

-> [!NOTE]

-> The authorization methods provided in the repo are for testing only. When you integrate with Microsoft Entra ID, you can review the authorization guidance. See [Plan provisioning for a SCIM endpoint](use-scim-to-provision-users-and-groups.md).

-The development environment enables features that are unsafe for production, such as reference code to control the behavior of the security token validation. The token validation code uses a self-signed security token, and the signing key is stored in the configuration file. See the **Token:IssuerSigningKey** parameter in the *appsettings.Development.json* file.

-```json

-"Token": {

- "TokenAudience": "Microsoft.Security.Bearer",

- "TokenIssuer": "Microsoft.Security.Bearer",

- "IssuerSigningKey": "A1B2C3D4E5F6A1B2C3D4E5F6",

- "TokenLifetimeInMins": "120"

-}

-```

-> [!NOTE]

-> When you send a **GET** request to the `/scim/token` endpoint, a token is issued using the configured key. That token can be used as a bearer token for subsequent authorization.

-The default token validation code is configured to use a Microsoft Entra token and requires the issuing tenant be configured by using the **Token:TokenIssuer** parameter in the *appsettings.json* file.

-``` json

-"Token": {

- "TokenAudience": "8adf8e6e-67b2-4cf2-a259-e3dc5476c621",

- "TokenIssuer": "https://sts.windows.net/<tenant_id>/"

-}

-```

-## Next steps

-description: System for Cross-domain Identity Management (SCIM) standardizes automatic user provisioning. In this tutorial, you learn to develop a SCIM endpoint, integrate your SCIM API with Microsoft Entra ID, and start automating provisioning users and groups into your cloud applications.

-# Tutorial: Develop and plan provisioning for a SCIM endpoint in Microsoft Entra ID

-As an application developer, you can use the System for Cross-Domain Identity Management (SCIM) user management API to enable automatic provisioning of users and groups between your application and Microsoft Entra ID. This article describes how to build a SCIM endpoint and integrate with the Microsoft Entra provisioning service. The SCIM specification provides a common user schema for provisioning. When used with federation standards like SAML or OpenID Connect, SCIM gives administrators an end-to-end, standards-based solution for access management.

-

-SCIM 2.0 is a standardized definition of two endpoints: a `/Users` endpoint and a `/Groups` endpoint. It uses common REST API endpoints to create, update, and delete objects. The SCIM consists of a predefined schema for common attributes like group name, username, first name, last name and email.

-Apps that offer a SCIM 2.0 REST API can reduce or eliminate the pain of working with a proprietary user management API. For example, any compliant SCIM client knows how to make an HTTP POST of a JSON object to the `/Users` endpoint to create a new user entry. Instead of needing a slightly different API for the same basic actions, apps that conform to the SCIM standard can instantly take advantage of pre-existing clients, tools, and code.

-The standard user object schema and rest APIs for management defined in SCIM 2.0 (RFC [7642](https://tools.ietf.org/html/rfc7642), [7643](https://tools.ietf.org/html/rfc7643), [7644](https://tools.ietf.org/html/rfc7644)) allow identity providers and apps to more easily integrate with each other. Application developers that build a SCIM endpoint can integrate with any SCIM-compliant client without having to do custom work.

-To automate provisioning to an application, it requires building and integrating a SCIM endpoint that is access by the Microsoft Entra provisioning service. Use the following steps to start provisioning users and groups into your application.

-1. [Design your user and group schema](#design-your-user-and-group-schema) - Identify the application's objects and attributes to determine how they map to the user and group schema supported by the Microsoft Entra SCIM implementation.

-1. [Understand the Microsoft Entra SCIM implementation](#understand-the-azure-ad-scim-implementation) - Understand how the Microsoft Entra provisioning service is implemented to model your SCIM protocol request handling and responses.

-1. [Build a SCIM endpoint](#build-a-scim-endpoint) - An endpoint must be SCIM 2.0-compatible to integrate with the Microsoft Entra provisioning service. As an option, use Microsoft Common Language Infrastructure (CLI) libraries and code samples to build your endpoint. These samples are for reference and testing only; we recommend against using them as dependencies in your production app.

-1. [Integrate your SCIM endpoint](#integrate-your-scim-endpoint-with-the-azure-ad-provisioning-service) with the Microsoft Entra provisioning service. Microsoft Entra ID supports several third-party applications that implement SCIM 2.0. If you use one of these apps, then you can quickly automate both provisioning and deprovisioning of users and groups.

-1. [Optional] [Publish your application to the Microsoft Entra application gallery](#publish-your-application-to-the-azure-ad-application-gallery) - Make it easy for customers to discover your application and easily configure provisioning.

-

-## Design your user and group schema

-Each application requires different attributes to create a user or group. Start your integration by identifying the required objects (users, groups) and attributes (name, manager, job title, etc.) that your application needs.

-The SCIM standard defines a schema for managing users and groups.

-The **core** user schema only requires three attributes (all other attributes are optional):

-In addition to the **core** user schema, the SCIM standard defines an **enterprise** user extension with a model for extending the user schema to meet your application's needs.

-For example, if your application requires both a user's email and user's manager, use the **core** schema to collect the user's email and the **enterprise** user schema to collect the user's manager.

-To design your schema, follow these steps:

-1. List the attributes your application requires, then categorize as attributes needed for authentication (for example, loginName and email). Attributes are needed to manage the user lifecycle (for example, status / active), and all other attributes needed for the application to work (for example, manager, tag).

-1. Check if the attributes are already defined in the **core** user schema or **enterprise** user schema. If not, you must define an extension to the user schema that covers the missing attributes. See example for an extension to the user to allow provisioning a user `tag`.

-1. Map SCIM attributes to the user attributes in Microsoft Entra ID. If one of the attributes you've defined in your SCIM endpoint doesn't have a clear counterpart on the Microsoft Entra user schema, guide the tenant administrator to extend their schema, or use an extension attribute as shown in the example for the `tags` property.

-The following table lists an example of required attributes:

-|Required app attribute|Mapped SCIM attribute|Mapped Microsoft Entra attribute|

-|--|--|--|

-|loginName|userName|userPrincipalName|

-|firstName|name.givenName|givenName|

-|lastName|name.familyName|surName|

-|workMail|emails[type eq "work"].value|Mail|

-|manager|manager|manager|

-|tag|`urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag`|extensionAttribute1|

-|status|active|isSoftDeleted (computed value not stored on user)|

-The following JSON payload shows an example SCIM schema:

-```json

-{

- "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",

- "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User"],

- "userName":"bjensen@testuser.com",

- "id": "48af03ac28ad4fb88478",

- "externalId":"bjensen",

- "name":{

- "familyName":"Jensen",

- "givenName":"Barbara"

- },

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

- "Manager": "123456"

- },

- "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User": {

- "tag": "701984",

- },

- "meta": {

- "resourceType": "User",

- "created": "2010-01-23T04:56:22Z",

- "lastModified": "2011-05-13T04:42:34Z",

- "version": "W\/\"3694e05e9dff591\"",

- "location":

- "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646"

- }

-}

-```

-> [!NOTE]

-> In addition to the attributes required for the application, the JSON representation also includes the required `id`, `externalId`, and `meta` attributes.

-It helps to categorize between `/User` and `/Group` to map any default user attributes in Microsoft Entra ID to the SCIM RFC, see [how customize attributes are mapped between Microsoft Entra ID and your SCIM endpoint](customize-application-attributes.md).

-The following table lists an example of user attributes:

-| Microsoft Entra user | `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User` |

-| | |

-| IsSoftDeleted |active |

-|department| `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department`|

-| displayName |displayName |

-|employeeId|`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber`|

-| Facsimile-TelephoneNumber |phoneNumbers[type eq "fax"].value |

-| givenName |name.givenName |

-| jobTitle |title |

-| mail |emails[type eq "work"].value |

-| mailNickname |externalId |

-| manager |`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager` |

-| mobile |phoneNumbers[type eq "mobile"].value |

-| postalCode |addresses[type eq "work"].postalCode |

-| proxy-Addresses |emails[type eq "other"].Value |

-| physical-Delivery-OfficeName |addresses[type eq "other"].Formatted |

-| streetAddress |addresses[type eq "work"].streetAddress |

-| surname |name.familyName |

-| telephone-Number |phoneNumbers[type eq "work"].value |

-| user-PrincipalName |userName |

-The following table lists an example of group attributes:

-| Microsoft Entra group | `urn:ietf:params:scim:schemas:core:2.0:Group` |

-| | |

-| displayName |displayName |

-| members |members |

-| objectId |externalId |

-> [!NOTE]

-> You are not required to support both users and groups, or all the attributes shown here, it's only a reference on how attributes in Microsoft Entra ID are often mapped to properties in the SCIM protocol.

-There are several endpoints defined in the SCIM RFC. You can start with the `/User` endpoint and then expand from there. The following table lists some of the SCIM endpoints:

-|Endpoint|Description|

-|--|--|

-|/User|Perform CRUD operations on a user object.|

-|/Group|Perform CRUD operations on a group object.|

-|/Schemas|The set of attributes supported by each client and service provider can vary. One service provider might include `name`, `title`, and `emails`, while another service provider uses `name`, `title`, and `phoneNumbers`. The schemas endpoint allows for discovery of the attributes supported.|

-|/Bulk|Bulk operations allow you to perform operations on a large collection of resource objects in a single operation (for example, update memberships for a large group).|

-|/ServiceProviderConfig|Provides details about the features of the SCIM standard that are supported, for example, the resources that are supported and the authentication method.|

-|/ResourceTypes|Specifies metadata about each resource.|

-> [!NOTE]

-> Use the `/Schemas` endpoint to support custom attributes or if your schema changes frequently as it enables a client to retrieve the most up-to-date schema automatically. Use the `/Bulk` endpoint to support groups.

-<a name='understand-the-azure-ad-scim-implementation'></a>

-## Understand the Microsoft Entra SCIM implementation

-The Microsoft Entra provisioning service is designed to support a SCIM 2.0 user management API.

-> [!IMPORTANT]

-> The behavior of the Microsoft Entra SCIM implementation was last updated on December 18, 2018. For information on what changed, see [SCIM 2.0 protocol compliance of the Microsoft Entra user provisioning service](application-provisioning-config-problem-scim-compatibility.md).

-Within the SCIM 2.0 protocol specification, your application must support these requirements:

-|Requirement|Reference notes (SCIM protocol)|

-|||

-|Create users, and optionally also groups|[Section 3.3](https://tools.ietf.org/html/rfc7644#section-3.3)|

-|Modify users or groups with PATCH requests|[Section 3.5.2](https://tools.ietf.org/html/rfc7644#section-3.5.2). Supporting ensures that groups and users are provisioned in a performant manner.|

-|Retrieve a known resource for a user or group created earlier|[Section 3.4.1](https://tools.ietf.org/html/rfc7644#section-3.4.1)|

-|Query users or groups|[Section 3.4.2](https://tools.ietf.org/html/rfc7644#section-3.4.2). By default, users are retrieved with their `id` and queried with their `username` and `externalId`, and groups are queried with `displayName`.|

-|The filter [excludedAttributes=members](#get-group) when querying the group resource|Section [3.4.2.2](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2)|

-|Support listing users and paginating|[Section 3.4.2.4](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4).|

-|Soft-deleting a user `active=false` and restoring the user `active=true`|The user object should be returned in a request whether or not the user is active. The only time the user shouldn't be returned is when it's hard deleted from the application.|

-|Support the /Schemas endpoint|[Section 7](https://tools.ietf.org/html/rfc7643#page-30) The schema discovery endpoint is used to discover more attributes.|

-|Accept a single bearer token for authentication and authorization of Microsoft Entra ID to your application.||

-Use the general guidelines when implementing a SCIM endpoint to ensure compatibility with Microsoft Entra ID:

-### General:

-* `id` is a required property for all resources. Every response that returns a resource should ensure each resource has this property, except for `ListResponse` with zero elements.

-* Values sent should be stored in the same format they were sent. Invalid values should be rejected with a descriptive, actionable error message. Transformations of data shouldn't happen between data from Microsoft Entra ID and data stored in the SCIM application. (for example. A phone number sent as 55555555555 shouldn't be saved/returned as +5 (555) 555-5555)

-* It isn't necessary to include the entire resource in the **PATCH** response.

-* Don't require a case-sensitive match on structural elements in SCIM, in particular **PATCH** `op` operation values, as defined in [section 3.5.2](https://tools.ietf.org/html/rfc7644#section-3.5.2). Microsoft Entra ID emits the values of `op` as **Add**, **Replace**, and **Remove**.

-* Microsoft Entra ID makes requests to fetch a random user and group to ensure that the endpoint and the credentials are valid. It's also done as a part of the **Test Connection** flow.

-* Support HTTPS on your SCIM endpoint.

-* Custom complex and multivalued attributes are supported but Microsoft Entra ID doesn't have many complex data structures to pull data from in these cases. Name/value attributes can be mapped to easily, but flowing data to complex attributes with three or more subattributes isn't supported.

-* The "type" subattribute values of multivalued complex attributes must be unique. For example, there can't be two different email addresses with the "work" subtype.

-* The header for all the responses should be of content-Type: application/scim+json

-### Retrieving Resources:

-* Response to a query/filter request should always be a `ListResponse`.

-* Microsoft Entra-only uses the following operators: `eq`, `and`

-* The attribute that the resources can be queried on should be set as a matching attribute on the application, see [Customizing User Provisioning Attribute Mappings](customize-application-attributes.md).

-### /Users:

-* The entitlements attribute isn't supported.

-* Any attributes that are considered for user uniqueness must be usable as part of a filtered query. (for example, if user uniqueness is evaluated for both userName and emails[type eq "work"], a GET to /Users with a filter must allow for both _userName eq "user@contoso.com"_ and _emails[type eq "work"].value eq "user@contoso.com"_ queries.

-### /Groups:

-* Groups are optional, but only supported if the SCIM implementation supports **PATCH** requests.

-* Groups must have uniqueness on the 'displayName' value to match with Microsoft Entra ID and the SCIM application. The uniqueness isn't a requirement of the SCIM protocol, but is a requirement for integrating a SCIM endpoint with Microsoft Entra ID.

-### /Schemas (Schema discovery):

-* [Sample request/response](#schema-discovery)

-* Schema discovery is being used on certain gallery applications. Schema discovery is the sole method to add more attributes to the schema of an existing gallery SCIM application. Schema discovery isn't currently supported on custom non-gallery SCIM application.

-* If a value isn't present, don't send null values.

-* Property values should be camel cased (for example, readWrite).

-* Must return a list response.

-* The Microsoft Entra provisioning service makes the /schemas request when you save the provisioning configuration. The request is also made when you open the edit provisioning page. Other attributes discovered are surfaced to customers in the attribute mappings under the target attribute list. Schema discovery only leads to more target attributes being added. Attributes aren't removed.

-### User provisioning and deprovisioning

-The following diagram shows the messages that Microsoft Entra ID sends to a SCIM endpoint to manage the lifecycle of a user in your application's identity store.

-[](media/use-scim-to-provision-users-and-groups/scim-figure-4.png#lightbox)

-### Group provisioning and deprovisioning

-Group provisioning and deprovisioning are optional. When implemented and enabled, the following illustration shows the messages that Microsoft Entra ID sends to a SCIM endpoint to manage the lifecycle of a group in your application's identity store. Those messages differ from the messages about users in two ways:

-* Requests to retrieve groups specify that the members attribute is to be excluded from any resource provided in response to the request.

-* Requests to determine whether a reference attribute has a certain value are requests about the members attribute.

-The following diagram shows the group deprovisioning sequence:

-[](media/use-scim-to-provision-users-and-groups/scim-figure-5.png#lightbox)

-### SCIM protocol requests and responses

-This article provides example SCIM requests emitted by the Microsoft Entra provisioning service and example expected responses. For best results, you should code your app to handle these requests in this format and emit the expected responses.

-> [!IMPORTANT]

-> To understand how and when the Microsoft Entra user provisioning service emits the operations described in the example, see the section [Provisioning cycles: Initial and incremental](how-provisioning-works.md#provisioning-cycles-initial-and-incremental) in [How provisioning works](how-provisioning-works.md).

-[User Operations](#user-operations)

-[Group Operations](#group-operations)

-[Schema discovery](#schema-discovery)

-### User Operations

-* Use `userName` or `emails[type eq "work"]` attributes to query users.

-#### Create User

-##### Request

-*POST /Users*

-```json

-{

- "schemas": [

- "urn:ietf:params:scim:schemas:core:2.0:User",

- "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],

- "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",

- "userName": "Test_User_ab6490ee-1e48-479e-a20b-2d77186b5dd1",

- "active": true,

- "emails": [{

- "primary": true,

- "type": "work",

- "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@testuser.com"

- }],

- "meta": {

- "resourceType": "User"

- },

- "name": {

- "formatted": "givenName familyName",

- "familyName": "familyName",

- "givenName": "givenName"

- },

- "roles": []

-}

-```

-##### Response

-*HTTP/1.1 201 Created*

-```json

-{

- "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],

- "id": "48af03ac28ad4fb88478",

- "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",

- "meta": {

- "resourceType": "User",

- "created": "2018-03-27T19:59:26.000Z",

- "lastModified": "2018-03-27T19:59:26.000Z"

- },

- "userName": "Test_User_ab6490ee-1e48-479e-a20b-2d77186b5dd1",

- "name": {

- "formatted": "givenName familyName",

- "familyName": "familyName",

- "givenName": "givenName",

- },

- "active": true,

- "emails": [{

- "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@testuser.com",

- "type": "work",

- "primary": true

- }]

-}

-```

-#### Get User

-###### <a name="request-1"></a>Request

-*GET /Users/5d48a0a8e9f04aa38008*

-###### <a name="response-1"></a>Response (User found)

-*HTTP/1.1 200 OK*

-```json

-{

- "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],

- "id": "5d48a0a8e9f04aa38008",

- "externalId": "58342554-38d6-4ec8-948c-50044d0a33fd",

- "meta": {

- "resourceType": "User",

- "created": "2018-03-27T19:59:26.000Z",

- "lastModified": "2018-03-27T19:59:26.000Z"

- },

- "userName": "Test_User_feed3ace-693c-4e5a-82e2-694be1b39934",

- "name": {

- "formatted": "givenName familyName",

- "familyName": "familyName",

- "givenName": "givenName",

- },

- "active": true,

- "emails": [{</