Introduction
One of the biggest challenges IT and HR teams face is ensuring that employee accounts are created, updated, and deactivated in a timely and accurate way. Traditional file-based imports and manual processes are slow, error-prone, and often disconnected from the source of truth, your HR system.With API-driven inbound provisioning in Microsoft Entra ID, you can integrate your HR system directly with Microsoft Graph. This allows authoritative HR data to automatically flow into Microsoft Entra ID and then into your on-premises Active Directory through the provisioning agent.
In this blog, I’ll guide you step by step through the configuration process for API-driven provisioning using Microsoft Graph Explorer, complemented with screenshots from my lab environment.
What is API-Driven Inbound Provisioning?
API-driven inbound provisioning is a modern mechanism where HR systems push identity data into Microsoft Entra ID using the Microsoft Graph API. Entra ID then provisions that data downstream to connected systems, such as on-premises AD, using the provisioning agent.
- Real-time automation – new hires, job changes, and terminations are reflected immediately.
- Flexibility – define custom attribute mappings, unique UPN formats, and filtering rules.
- Security – central audit logs, scoped provisioning, and better governance.
- Integration – works with any HR system capable of calling Graph APIs (Workday, SAP, or even a custom in-house system).
Prerequisites
Before configuring, ensure the following:
- Licenses: Microsoft Entra ID P1 or P2.
- Roles: Application Administrator + Hybrid Identity Administrator.
- On-prem server: Windows Server 2016+ with internet access and .NET 4.7.1+.
- Provisioning Agent installed on a domain-joined server with rights to create/update users.
- HR system or middleware capable of making API calls (e.g., Logic Apps, PowerShell, Graph Explorer or direct HRIS integration).
Step-by-Step Configuration
Step 1: Install & Register the Provisioning Agent
Download the Microsoft Entra provisioning agent from the portal.
Install the provisioning agent on an on-premises Windows Server that is domain-joined to Active Directory and has reliable internet access for communication with Microsoft Entra ID
Now select the extension you want to install ,HR-driven provisioning / Microsoft Entra Cloud Sync, or On-premises application provisioning (Microsoft Entra ID to application) based on your specific requirements. In our case, we will proceed with HR-driven provisioning.
Next, let’s configure the service account that will handle synchronization from Active Directory. For this, we’ll create a Group Managed Service Account (gMSA). To create the gMSA, provide the required domain credentials and then click Next.
Next, we need to connect to Active Directory. Enter the local AD domain name along with the required credentials to establish the connection.
Provisioning agent configuration completed. Verify that the agent is Active under On-Premises Provisioning Agents.
Now, if you navigate to Entra Connect → Cloud Sync and select Agents, you will see the newly installed agent listed there.
Step 2: Create the Enterprise Application
In Microsoft Entra Admin Center, navigate to Enterprise applications → New application.Search for “API-driven provisioning to on-premises Active Directory”.
Step 3: Configure Provisioning Settings
Open the new application → Provisioning blade.
Under Admin Credentials, select your Active Directory domain from the drop-down list and specify the distinguished name (DN) of the Organizational Unit (OU) where new user accounts should be created by default.
If your AD domain does not appear in the list, reload the provisioning app in the browser. Then click View on-premises agents to confirm that your agent status is healthy.
Next, click Test connection to verify that Microsoft Entra ID can successfully connect to the provisioning agent. Click Save to apply your changes.
Now, return to the Provisioning blade and enable the Provisioning status to activate the configuration.
Step 4: Push Data into Microsoft Entra Using Graph
You have several options to send HR data into Microsoft Entra\Local AD:
Option A: Graph Explorer (for this testing and validation)
Option B: PowerShell automation
Option C: Logic Apps integration
Additionally, if your HR application is available as an enterprise application in the Microsoft Entra app catalog, you can use that integration as well.
In this blog, I’ll be using Graph Explorer to demonstrate how to push the data.
Open a new browser tab or window. Navigate to Microsoft Graph Explorer
Click the user profile icon to sign in.
Log in using an account that has the User Administrator role(Least Privileged Role).
After successful login, verify that the Tenant information displays your tenant name.
You’re now ready to invoke the API. In the API request panel, set the HTTP method to POST.
Copy and paste the provisioning API endpoint from the Provisioning app overview page.
In the Request headers section, add a new key-value pair:
Content-Type = application/scim+json
In the Request body panel, copy and paste the bulk request that uses the SCIM Enterprise User Schema Mentioned below.
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
"Operations": [
{
"method": "POST",
"bulkId": "11aa22bb-cc33-dd44-ee55-66ff77gg88hh",
"path": "/Users",
"data": {
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"externalId": "801001",
"userName": "manwar.khan@acmebh.com",
"name": {
"formatted": "Mr. Mohammed Anwar Khan",
"familyName": "Khan",
"givenName": "Mohammed",
"middleName": "Anwar",
"honorificPrefix": "Mr."
},
"displayName": "Mohammed Anwar Khan",
"nickName": "Anwar",
"emails": [
{
"value": "manwar.khan@acmebh.com",
"type": "work",
"primary": true
}
],
"addresses": [
{
"type": "work",
"streetAddress": "Flat 22, Building 444",
"locality": "Manama",
"region": "Capital",
"postalCode": "6666",
"country": "Bahrain",
"formatted": "Flat 22, Building 444\nManama, Bahrain 6666",
"primary": true
}
],
"userType": "Employee",
"title": "Software Engineer",
"preferredLanguage": "en-US",
"locale": "en-US",
"timezone": "Asia/Bahrain",
"active": true,
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "801001",
"organization": "Contoso Ltd",
"division": "IT",
"department": "Development"
}
}
},
{
"method": "POST",
"bulkId": "22bb33cc-dd44-ee55-ff66-77gg88hh99ii",
"path": "/Users",
"data": {
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"externalId": "801002",
"userName": "smohan@acmebh.com",
"name": {
"formatted": "Mr. Satheesh Mohan",
"familyName": "Mohan",
"givenName": "Satheesh",
"honorificPrefix": "Mr."
},
"displayName": "Satheesh Mohan",
"nickName": "Satheesh",
"emails": [
{
"value": "smohan@acmebh.com",
"type": "work",
"primary": true
}
],
"addresses": [
{
"type": "work",
"streetAddress": "Flat 555, Building 7777",
"locality": "Manama",
"region": "Capital",
"postalCode": "0000",
"country": "Bahrain",
"formatted": "Flat 555, Building 7777\nManama, Bahrain",
"primary": true
}
],
"userType": "Employee",
"title": "Senior Developer",
"preferredLanguage": "en-US",
"locale": "en-US",
"timezone": "Asia/Bahrain",
"active": true,
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "801002",
"organization": "Contoso Ltd",
"division": "IT",
"department": "Development",
"manager": {
"value": "801001",
"displayName": "Mohammed Anwar Khan"
}
}
}
}
],
"failOnErrors": null
}
Click Run query to send the request to the provisioning API endpoint.
Step 5: Validate & Monitor Provisioning
This below URL points to the provisioning logs API endpoint, which you can query to check the provisioning status of the users included in your bulk request.
Below image shows the status
Verifying Processing from Microsoft Entra Admin Center
Sign in to the Microsoft Entra admin center with an account that has at least Application Administrator privileges.
Navigate to Entra ID → Enterprise applications.
In All applications, use the search box to locate and open your API-driven provisioning application.
Go to the Provisioning blade. The landing page will display the status of the most recent run.
To review detailed activity, select View provisioning logs.
API-driven provisioning status logs shown in the below image.
Alternatively, you can navigate through Monitor → Provisioning logs.
When we check our on-premises Active Directory, we can see that both users have been successfully created with the provided attributes.
HR-Driven Scenarios & Use Cases
Onboarding (Joiners): When HR creates a new employee record, an AD account is automatically provisioned with attributes such as name, department, and email etc.
Role Changes (Movers): Department transfers, promotions, or manager updates are instantly reflected in AD.
Offboarding (Leavers): HR-initiated terminations disable AD accounts the same day, reducing the risk of orphaned identities.
Re-hires: HR can reactivate a user record instead of creating duplicates, ensuring data consistency.
This HR-driven identity lifecycle improves accuracy, enhances compliance, and reduces IT overhead.
Advantages
Automation – Eliminates manual account creation.
Security – Prevents stale or orphaned accounts.
Efficiency – Reduces IT workload and accelerates onboarding.
Flexibility – Works with any HR system capable of calling APIs.
Governance – Provides full audit trails in Entra provisioning logs.
Conclusion
In this blog, I showcased how API-driven inbound provisioning works using Microsoft Graph Explorer as an example. This approach demonstrates the core flow of pushing HR data into Microsoft Entra and automatically provisioning accounts into on-premises Active Directory.
In real-world scenarios, organizations can integrate this process directly with their HR systems, or leverage Logic Apps and automation pipelines to seamlessly create and update users in local AD. By adopting this model, businesses can modernize their joiner-mover-leaver lifecycle, strengthen security posture, and optimize IT operations.
Stay tuned, I’ll be covering more configuration flow scenarios in my upcoming blogs.
0 Comments