Azure AD synchronization API overview

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported.

Azure Active Directory (Azure AD) identity synchronization (also called "provisioning") allows you to automate the creation, maintenance, and removal of identities in cloud (software as a service, or SaaS) applications such as Dropbox, Salesforce, ServiceNow, and more. You can use the synchronization APIs in Microsoft Graph to manage identity synchronization programmatically, including:

  • Create, start, and stop synchronization jobs
  • Make changes to the synchronization schema for jobs
  • Verify the current synchronization status

For more information about synchronization in Azure AD, see:

You can also try the API in the Graph Explorer in a sample tenant or your own tenant.

Synchronization job

Synchronization jobs perform synchronization by periodically running in the background, polling for changes in one directory, and pushing them to another directory. The synchronization job is always specific to a particular instance of an application in your tenant. As part of the synchronization job setup, you need to give authorization to read and write objects in your target directory, and customize the job's synchronization schema.

For more information, see synchronization job.

Synchronization schema

The synchronization schema defines what objects will be synchronized and how they will be synchronized. The synchronization schema contains most of the setup information for a particular synchronization job. Typically, you will customize some of the attribute mappings, or add a scoping filter to synchronize only objects that satisfy a certain condition.

The synchronization schema includes the following components:

  • Directory definitions
  • Synchronization rules
  • Object mappings

For more information, see synchronization schema.

Synchronization template

The synchronization template provides pre-configured synchronization settings for a particular application. These settings (most importantly, synchronization schema) will be used by default for any synchronization job that is based on the template. Templates are specified by the application developer.

For more information, see synchronization template.

Working with the synchronization API

Working with synchronization API primarily involves accessing the synchronizationJob and synchronizationSchema resources. To find your synchronizationJob resource, you need to know the ID of the service principal object that the synchronization job belongs to. The following examples show you how to work with the synchronizationJob and synchronizationSchema resources.

Authorization

The Azure AD synchronization API uses OAuth 2.0 for authorization. Before making any requests to the API, you need to get an access token. For more information, see Get access tokens to call Microsoft Graph. To access synchronization resources, your application needs Directory.ReadWrite.All permissions. For more information, see Directory permissions.

Find the service principal object by display name

The following example shows how to find service principal object by display name.

Request

GET https://graph.microsoft.com/beta/servicePrincipals?$select=id,appId,displayName&$filter=startswith(displayName, 'salesforce')

Response

HTTP/1.1 200 OK
{
    "value": [
    {
        "id": "bc0dc311-87df-48ac-91b1-259bd2c3a31c",
        "appId": "f7808c5e-cb57-4e37-8094-406d302c0f8d",
        "displayName": "Salesforce"
    },
    {
        "id": "d813d7d7-0f41-4edc-b284-d0dfaf399d15",
        "appId": "219561ee-1480-4c67-9aa6-63d861fae3ef",
        "displayName": "salesforce 3"
    }
    ]
}

Find the service principal object by app ID

The following example shows how to find the service principal object by app ID.

Request

GET https://graph.microsoft.com/beta/servicePrincipals?$select=id,appId,displayName&$filter=AppId eq '219561ee-1480-4c67-9aa6-63d861fae3ef'

Response

HTTP/1.1 200 OK
{
    "value": [
        {
            "id": "d813d7d7-0f41-4edc-b284-d0dfaf399d15",
            "appId": "219561ee-1480-4c67-9aa6-63d861fae3ef",
            "displayName": "salesforce 3"
        }
    ]
}

List existing synchronization jobs

The following example shows you how to list existing synchronization jobs.

Request

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs
GET https://graph.microsoft.com/beta/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs

Response

HTTP/1.1 200 OK
{
    "value": [
        {
            "id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
            "templateId": "SfSandboxOutDelta",
            "schedule": {
                "expiration": null,
                "interval": "PT20M",
                "state": "Active"
            },
            "status": {}
        }
    ]
}

Get synchronization job status

The following example shows you how to get the status of a synchronization job.

Request

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

GET https://graph.microsoft.com/beta/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs/SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa

Response

    HTTP/1.1 200 OK
    {
        "id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
        "templateId": "SfSandboxOutDelta",
        "schedule": {
            "expiration": null,
            "interval": "PT20M",
            "state": "Active"
        },
        "status": {}
    }

Get synchronization schema

The following example shows you how to get the synchronization schema.

Request

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

Response

HTTP/1.1 200 OK
{
    "directories": [],
    "synchronizationRules": []
}

See also