On-Premises Application Provisioning Connectors

On-premises application provisioning extends the Entra provisioning platform to systems that lack cloud APIs. Through the provisioning agent and ECMA connector host, Entra ID can provision users to LDAP directories, SQL databases, REST/SOAP web services, and custom targets using ECMA2 connectors. This lets you manage identity lifecycle for on-premises applications using the same provisioning engine, attribute mappings, scoping filters, and monitoring tools that you use for cloud SaaS applications.

Architecture

The on-premises provisioning architecture has three components that form a relay chain between the cloud and on-premises targets:

architecture-beta
    group cloud(cloud)[Entra Cloud Services]
    service prov(server)[Provisioning Service] in cloud
    service graph(server)[Graph API] in cloud

    group onprem(cloud)[On-Premises Server]
    service agent(server)[Provisioning Agent] in onprem
    service ecma(server)[ECMA2Host] in onprem

    group targets(cloud)[Target Systems]
    service ldap(disk)[LDAP Directory] in targets
    service sql(database)[SQL Database] in targets
    service web(server)[Web Service] in targets
    service custom(server)[Custom App] in targets

    graph:B --> T:prov
    prov:R --> L:agent
    agent:R --> L:ecma
    ecma:R --> L:ldap
    ecma:R --> L:sql
    ecma:R --> L:web
    ecma:R --> L:custom

Provisioning Agent

The provisioning agent is a lightweight Windows service installed on a domain-joined server (or a server with network connectivity to your target systems). Key characteristics:

• Outbound-only connections. The agent initiates connections to Azure Service Bus over HTTPS (port 443). No inbound firewall rules are required.
• Shared binary with Cloud Sync. The same agent installer supports both Cloud Sync (AD-to-Entra and Entra-to-AD sync) and on-premises application provisioning. These are different “extensions” within the agent. However, you should not run both Cloud Sync and on-premises application provisioning on the same agent instance in production; use separate agents for each workload.
• Auto-update. The agent supports automatic updates, but auto-update is only enabled for the Cloud Sync extension. On-premises application provisioning agent updates require manual installation.
• gMSA support. The agent can run under a group Managed Service Account (gMSA) for least-privilege access to on-premises resources.

ECMA Connector Host (ECMA2Host)

The ECMA2Host is a Windows service that runs alongside the provisioning agent. It converts SCIM-based provisioning requests from the cloud into the protocol required by the target application:

1. The cloud provisioning service sends SCIM operations (create user, update user, delete user) to the agent.
2. The agent forwards these to the ECMA2Host over a local HTTPS endpoint.
3. The ECMA2Host loads the configured connector (LDAP, SQL, web service, or custom ECMA) and translates the SCIM operation into the target protocol.
4. The connector executes the operation against the target system and returns the result.

ECMA2Host configuration includes:

• Connectivity settings. Connection string, credentials, and protocol-specific parameters for the target system.
• Schema discovery. The host discovers the target system’s schema (available attributes, object types) and presents them for attribute mapping.
• Anchor attribute. A unique, immutable identifier in the target system used to match provisioned objects. This is the on-premises equivalent of objectId.
• DN attribute. For LDAP targets, the distinguished name attribute that determines where objects are created in the directory tree.

Entra Provisioning Service

The cloud-side engine manages all configuration and scheduling. It holds the attribute mappings, scoping rules, matching logic, and provisioning policies. The agent and ECMA2Host are stateless relays; if you replace the on-premises server, you only need to reinstall the agent and point it at the same provisioning app.

Supported Connector Types

Generic LDAP Connector

Provisions users and groups to any LDAP v3 compliant directory. Configuration includes:

• Connection. LDAP server hostname, port (389/636), bind DN, and credentials. Supports LDAP over SSL (LDAPS) and StartTLS.
• Partitions and hierarchy. Base DN for the partition, plus the container DN where new objects are created.
• Object classes. Maps Entra users to LDAP object classes (e.g., inetOrgPerson, user). Supports auxiliary object classes.
• Attribute mapping. Maps SCIM attributes to LDAP attributes. The anchor attribute is typically objectGUID or entryUUID; the DN attribute is constructed from a naming attribute (e.g., cn).

Common use case: provisioning user accounts to AD LDS for applications that authenticate against a separate LDAP directory rather than the main AD forest.

Generic SQL Connector

Provisions user records to SQL database tables or views. Configuration includes:

• Connection. ODBC connection string to the target database.
• Table/view mapping. Which table stores user records, which columns map to identity attributes.
• Stored procedures (optional). Custom stored procedures for insert, update, delete, and query operations instead of direct table access.
• Anchor column. A unique, immutable column (e.g., auto-increment ID or GUID) used for matching.

Common use case: provisioning accounts to a legacy application that reads user records from a SQL database for authentication and authorization.

Web Services Connector

Provisions to REST or SOAP endpoints. This connector uses configurable request/response templates:

• Endpoint URL. The base URL of the web service.
• Authentication. Basic, OAuth, certificate, or custom header authentication.
• Request templates. JSON or XML templates for create, update, and delete operations with attribute placeholders.
• Response parsing. XPath (SOAP) or JSONPath (REST) expressions to extract results.

PowerShell Connector

For targets that lack a standard protocol, the PowerShell connector executes custom scripts:

• Import script. Reads existing objects from the target for matching.
• Export script. Creates, updates, or deletes objects in the target.
• The scripts receive structured parameter objects and return structured results.

Common use case: provisioning to flat-file systems, proprietary APIs, or mainframe systems that require custom command-line interaction.

Custom ECMA 2.0 Connectors

If you have existing ECMA 2.0 connectors built for Microsoft Identity Manager (MIM), you can migrate them to ECMA2Host:

1. Export the connector configuration from MIM.
2. Import the connector DLL and configuration into ECMA2Host.
3. Configure connectivity and schema mapping in the ECMA2Host wizard.
4. Test connectivity and perform a test export.

The ECMA 2.0 interface defines standard methods (OpenImportConnection, GetImportEntries, OpenExportConnection, PutExportEntries) that custom connectors implement. Any connector built to this interface works with ECMA2Host.

Agent Deployment

Prerequisites

• Windows Server 2016 or later (not Server Core).
• .NET Framework 4.7.2 or later.
• Network connectivity to the target system (LDAP port, SQL port, HTTPS endpoint, etc.).
• Outbound HTTPS (443) to Azure Service Bus and Microsoft login endpoints.
• TLS 1.2 enabled.
• If targeting Active Directory: domain-joined server with a gMSA configured.

Installation

1. Download the provisioning agent installer from the Entra admin center (On-premises provisioning > Download agent).
2. Run the installer and authenticate with a Hybrid Identity Administrator account.
3. During setup, select the on-premises application provisioning extension.
4. The agent registers with your Entra tenant and appears in the admin center under On-premises provisioning agents.

ECMA2Host Configuration

After agent installation:

1. Open the ECMA Connector Host Configuration wizard.
2. Create a new connector and select the connector type (LDAP, SQL, etc.).
3. Configure connectivity (server, credentials, connection string).
4. Run schema discovery to import the target system’s attribute list.
5. Map the anchor and DN attributes.
6. Test connectivity to verify the agent can reach the target system.
7. In the Entra admin center, create an enterprise application of type On-premises ECMA app and associate it with the agent and connector.
8. Configure attribute mappings and scoping in the provisioning app.

Testing

Use Provision on demand in the Entra admin center to test provisioning for a single user before enabling the full provisioning cycle:

1. Go to the provisioning app > Provision on demand.
2. Search for and select a user.
3. Select Provision and review the result.

The on-demand test shows the full processing pipeline: scoping evaluation, attribute mapping, matching, and the export operation to the target system.

High Availability

High availability patterns differ by connector type:

For ECMA-based connectors, deploy a second server with the agent and ECMA2Host installed and configured identically. If the primary fails, reassign the provisioning app to the standby agent in the admin center.

Attribute Mapping for On-Prem Targets

Attribute mapping for on-premises targets works the same as for cloud apps, with two additional considerations:

DN Construction

For LDAP targets, you must define how the distinguished name is constructed. Typically this uses an expression that combines a naming attribute with a container path:

• Example: CN= + [displayName] + ,OU=Users,DC=contoso,DC=local

Anchor Attribute

The anchor attribute must be immutable and unique in the target system. For LDAP this is typically objectGUID or entryUUID. For SQL databases, it is the primary key column. The provisioning service uses the anchor to track which Entra user maps to which target object across provisioning cycles.

Expression Functions

The same expression functions available for cloud app provisioning work for on-premises targets. Common patterns:

• Join("", "CN=", [displayName], ",OU=Users,DC=contoso,DC=local") - DN construction
• Switch([department], "OU=Default,...", "Engineering", "OU=Eng,...", "Sales", "OU=Sales,...") - OU routing by department
• IIF(IsPresent([manager]), [manager], "") - conditional manager assignment

For the full expression language reference, see the Cloud Sync expression language deep-dive, which covers the same expression engine used by application provisioning.

Troubleshooting

Agent Connectivity

If the agent cannot connect to the cloud service:

1. Verify outbound HTTPS (443) is open to *.servicebus.windows.net and login.microsoftonline.com.
2. Check that TLS 1.2 is enabled on the server.
3. If using a proxy, configure the agent’s proxy settings in the agent configuration wizard.
4. Review the agent event log: Applications and Services Logs > Microsoft > Azure AD Connect Provisioning Agent.

ECMA2Host Issues

The ECMA2Host maintains its own log:

• Log location: C:\Program Files\Microsoft ECMA2Host\Service\Logs\
• Common issues:
  • Connection timeout. The target system is unreachable. Verify network connectivity and credentials.
  • Schema mismatch. The target schema changed after initial configuration. Re-run schema discovery.
  • Anchor conflict. Two Entra users map to the same target anchor. Fix the matching rule or resolve the duplicate.

Provisioning Errors

Provisioning errors appear in the Entra admin center provisioning logs, the same as for cloud app provisioning:

• Export errors. The target system rejected the operation (e.g., constraint violation, duplicate attribute). Check the error details for the specific target system error code.
• Quarantine. If the provisioning service encounters repeated failures, it enters quarantine. Fix the root cause (connectivity, permissions, schema), then restart the provisioning cycle.

Testing Connectivity

Use the Test connection button in the ECMA2Host configuration wizard to verify end-to-end connectivity from the cloud to the target system. This sends a test SCIM request through the full chain (cloud service, agent, ECMA2Host, connector, target).

Relationship to Cloud Sync

On-premises application provisioning and Cloud Sync both use the same provisioning agent binary, but they serve different purposes and should run on separate agent instances:

Cloud Sync also supports group provisioning to Active Directory, which writes Entra ID security groups back to on-premises AD. This is a Cloud Sync capability, not an application provisioning feature, but uses the same agent infrastructure. The distinction: Cloud Sync writes groups to AD for Kerberos-based application access; on-prem connectors provision users (and potentially groups) to non-AD on-premises applications.

Next Steps

• What Is Provisioning - platform overview and architecture
• How Provisioning Works - provisioning cycles, scoping, matching, and mappings
• Inbound API Provisioning - API-driven inbound provisioning from external sources
• Troubleshooting - common error patterns and quarantine recovery
• Cloud Sync Group Provisioning to AD - Cloud Sync’s group writeback capability (distinct from on-prem connectors)
• Microsoft Learn: On-premises provisioning architecture