Manage provisioning object connections using Microsoft Graph (Preview)

When the Microsoft Entra provisioning service provisions an object, it stores an object connection that associates the source object with the corresponding target object. The service uses this connection during later provisioning cycles to update the correct target object.

This article is for application owners and administrators who need to inspect a connection for a known source or target object or remove an incorrect or stale connection. Before you begin, have the service principal and synchronization job IDs, a known object identifier, and the required authorization and Microsoft Graph permissions.

Removing an object connection doesn't delete the source or target object. It deletes only the provisioning service's stored association between them.

Note

Managing provisioning object connections is currently in preview. We make previews available to our customers under the terms applicable to previews. These terms are outlined in the overall Microsoft product terms for online services.

Prerequisites

• The object ID of the application's service principal.

• The ID of the synchronization job.

• A known source or target identifier for the object connection.

• The following Microsoft Graph permissions for object-connection operations:

  Operation	Delegated permission	Application permission
  Get an object connection	SynchronizationMetadata.Read.All	SynchronizationMetadata.Read.OwnedBy or SynchronizationMetadata.Read.All
  Delete an object connection	SynchronizationMetadata.ReadWrite.All	SynchronizationMetadata.ReadWrite.OwnedBy or SynchronizationMetadata.ReadWrite.All

For delegated access, the signed-in user needs both the delegated Microsoft Graph permission and authorization for the provisioning scenario:

Provisioning scenario	Signed-in user authorization
Standard application and HR provisioning	An owner of the application's service principal, or a user assigned Application Administrator, Cloud Application Administrator, or Hybrid Identity Administrator.
Cross-tenant synchronization	An owner of the application's service principal, or a user assigned Hybrid Identity Administrator.
Microsoft Entra Cloud Sync	A user assigned Hybrid Identity Administrator. Service-principal ownership alone isn't sufficient.

The table lists the least-privileged supported administrator roles. A role or service-principal ownership doesn't replace the delegated permission requirement.

For application access, the *.OwnedBy permissions apply only when the calling application owns the service principal for the provisioning job. Use the corresponding *.All permission to access provisioning jobs across the organization. All four permissions require administrator consent.

Permissions for job-management operations

The object-connection permissions don't authorize the job-management API calls used in the recovery procedure. If you use Microsoft Graph to perform those operations, also obtain the permissions for the operations that you call.

Operation	Least-privileged delegated permission	Least-privileged application permission
Read job status	Synchronization.Read.All	Application.ReadWrite.OwnedBy
Pause, start, or provision on demand	Synchronization.ReadWrite.All	Application.ReadWrite.OwnedBy

The application permission in this table requires the calling application to own the service principal. For other supported permissions, see each operation's API reference. You don't need these additional API permissions if you perform the job-management operations in the Microsoft Entra admin center.

Important

The object connections API is available only in the Microsoft Graph beta endpoint. APIs in the beta endpoint are subject to change. Use of these APIs in production applications isn't supported.

Find the required identifiers

Find the service principal, synchronization job, and object identifiers before you inspect or delete an object connection.

1. In the Microsoft Entra admin center, browse to Entra ID > Enterprise apps.
2. Select the application.
3. Open Provisioning, and then select the Overview tab on the provisioning Overview page.
4. Under Basic information, copy Service principal object id and Job ID. Use these values for {servicePrincipalId} and {jobId} in the requests in this article. The service principal object ID isn't the application (client) ID.
5. Find the exact source or target identifier for the object that you want to inspect. See Object connection identifiers by provisioning scenario for the attributes and formats to use.

Provisioning logs can help you identify the source and target objects involved in an operation. For more information, see Provisioning logs in Microsoft Entra ID.

Get an object connection

Get an object connection to inspect the stored association before you remove it. The synchronization job can be active, paused, or disabled.

1. Send the following request. The API first searches for the supplied identifier as a source identifier. If it doesn't find a connection, it searches for the identifier as a target identifier.

   GET https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/objectConnections('{objectId}')
   Authorization: Bearer {token}
   

2. Review the 200 OK response:

   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
     "@odata.context": "https://graph.microsoft.com/beta/$metadata#objectConnection/$entity",
     "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
     "sourceAnchor": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
     "targetAnchor": "701984",
     "displayName": "Adele Vance",
     "objectTypeName": "user"
   }
   

   The response contains the following properties:

   Property	Description
   objectId	The object identifier used to retrieve the connection.
   sourceAnchor	The identifier of the object in the source system.
   targetAnchor	The identifier of the corresponding object in the target system.
   displayName	The display name stored for the object, when available.
   objectTypeName	The object type, such as user or group.

3. If the API returns 404 Not Found, verify the object identifier and synchronization job ID.

You must supply a known object identifier. Listing, filtering, or enumerating the object connections for a synchronization job isn't supported. A request to the collection returns 400 Bad Request:

GET https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/objectConnections
Authorization: Bearer {token}

Delete an object connection

Delete an object connection when the stored association is incorrect or no longer valid. Correct the source data or matching configuration first so that a later provisioning cycle doesn't recreate the same connection.

Caution

Deleting an object connection changes durable provisioning state. Use GET to verify the sourceAnchor and targetAnchor before you delete the connection.

1. Pause the synchronization job:

   POST https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/pause
   Authorization: Bearer {token}
   Content-Length: 0
   

   Alternatively, in the Microsoft Entra admin center, browse to Entra ID > Enterprise apps > your application > Provisioning. Set Provisioning Status to Off, and then select Save.

2. Get the synchronization job and confirm that schedule.state is Paused or Disabled. A DELETE request for an active job returns 409 Conflict. For API details, see Pause synchronizationJob and Get synchronizationJob.

3. Send the DELETE request:

   DELETE https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/objectConnections('{objectId}')
   Authorization: Bearer {token}
   

4. Confirm that the API returns 204 No Content:

   HTTP/1.1 204 No Content
   

DELETE is idempotent. If no connection contains the supplied identifier, the API also returns 204 No Content. Because a missing connection and a successful deletion have the same response, use GET to verify the identifier before you send the DELETE request.

Repair an incorrect object connection

After you delete an incorrect connection, provision the object again to validate the corrected matching behavior.

1. Review the provisioning logs and identify the source and target objects in the incorrect connection.

2. Correct the source data, target data, attribute mappings, or matching configuration that caused the incorrect association.

3. Use GET to retrieve the object connection and verify its sourceAnchor and targetAnchor.

4. Pause or disable the synchronization job.

5. Confirm that the job's schedule.state is Paused or Disabled.

6. Use DELETE to remove the incorrect object connection.

7. Provision the object on demand to validate the corrected matching behavior.

   To use Microsoft Graph instead, see Provision on demand.

8. Use GET or review the provisioning logs to verify the new connection.

9. Start the synchronization job:

   POST https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/start
   Authorization: Bearer {token}
   Content-Length: 0
   

   For API details, see Start synchronizationJob.

Example: Repair an incorrect Workday-to-Microsoft Entra ID connection

Suppose a Workday-to-Microsoft Entra ID provisioning job linked a Workday worker to the wrong Microsoft Entra user. Use the worker's Workday WID to inspect and remove the stored connection, and then validate a new connection to the intended user.

The following values are illustrative:

Object	Identifier
Workday worker WID	4f3c2b1a0e9d8c7b6a5f403122334455
Incorrectly linked Microsoft Entra user object ID	aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
Intended Microsoft Entra user object ID	bbbbbbbb-1111-2222-3333-cccccccccccc

1. Find the service principal and job IDs for the Workday provisioning application.

2. Send a GET request with the worker's WID as the object identifier. Replace the sample WID with the value for your worker.

   GET https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/objectConnections('4f3c2b1a0e9d8c7b6a5f403122334455')
   Authorization: Bearer {token}
   

3. Check sourceAnchor and targetAnchor in the GET response. In this example, sourceAnchor is the worker's WID, 4f3c2b1a0e9d8c7b6a5f403122334455. The incorrect targetAnchor is aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb. Don't delete the connection if it isn't the association that you intend to remove.

4. Pause or disable the job and confirm that schedule.state is Paused or Disabled.

5. Correct the source data, target data, attribute mappings, or matching configuration that caused the worker to match the wrong user. Deleting the connection alone doesn't correct the matching behavior.

6. Send a DELETE request with the same worker WID, and confirm a 204 No Content response.

   DELETE https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/objectConnections('4f3c2b1a0e9d8c7b6a5f403122334455')
   Authorization: Bearer {token}
   

   This request removes only the stored connection. It doesn't delete either user.

7. Provision the worker on demand by using the worker's WID.

8. Repeat the GET request. Confirm that sourceAnchor is still the worker's WID. Verify that targetAnchor is now the intended user's object ID, bbbbbbbb-1111-2222-3333-cccccccccccc in this example. Review the provisioning logs if the expected connection isn't established.

9. Start the synchronization job only after you verify the corrected connection.

Troubleshoot HTTP responses

Use the following table to troubleshoot GET and DELETE requests. For broader provisioning issues, see Troubleshoot provisioning to a Microsoft Entra gallery application.

Status code	Meaning
200 OK	GET found and returned the object connection.
204 No Content	DELETE removed the object connection, or the connection was already absent.
400 Bad Request	An identifier is invalid, or the request tries to list the object connections collection.
401 Unauthorized	The request doesn't contain a valid access token.
403 Forbidden	The caller doesn't have the required Microsoft Graph permission, Microsoft Entra role, or application authorization.
404 Not Found	The synchronization job or requested object connection wasn't found, or the API isn't available for the job.
409 Conflict	DELETE was requested while the synchronization job was active. Pause or disable the job and try again.

Known limitations

• The API is available only in Microsoft Graph beta.
• You can retrieve only one known object connection at a time.
• Listing, filtering, and enumerating all object connections isn't supported.
• You can't directly create or update an object connection.
• Deleting a connection doesn't delete or modify the source or target object.
• A later provisioning operation can create a new connection for the object.

Related content

• Microsoft Entra synchronization API overview
• Configure provisioning using Microsoft Graph APIs
• On-demand provisioning in Microsoft Entra ID