MS Graph API を使用してクラウドの同期をプログラムで構成する方法

[アーティクル]
12/17/2024

次のドキュメントでは、MSGraph API のみを使用して 0 から同期プロファイルをレプリケートする方法について説明します。
同期プロファイルをレプリケートする方法の構造は、以下の手順で構成されます。これらは次のとおりです。

MS Graph API を使用してクラウドの同期をプログラムで構成する方法

これらの Microsoft Graph PowerShell のコマンドを使って、運用テナントの同期を有効にします。これは、そのテナントの管理 Web サービスを呼び出すための前提条件となっています。

基本的なセットアップ

テナントフラグを有効にする

Connect-MgGraph -Scopes "DeviceManagementConfiguration.ReadWrite.All" ('-Environment <AzureEnvironment>')
$organizationId = (Get-MgOrganization).Id
$params = @{
	onPremisesSyncEnabled = $true
}
Update-MgBetaOrganization -OrganizationId $organizationId -BodyParameter $params

このコマンドレットを実行すると、テナントの同期が有効になります。 Get-MgOrganization を使って組織の ID を取得しています。

サービスプリンシパルの作成

次に、AD2AAD アプリケーションまたはサービスプリンシパルを作成する必要があります

このアプリケーション ID 1a4721b3-e57f-4451-ae87-ef078703ec94 を使用する必要があります。 displayName は、ポータルで使用されている場合は AD ドメインの URL (たとえば contoso.com) ですが、他の名前を付けても構いません。

POST https://graph.microsoft.com/beta/applicationTemplates/1a4721b3-e57f-4451-ae87-ef078703ec94/instantiate
Content-type: application/json
{
    displayName: [your app name here]
}

同期ジョブを作成する

上記のコマンドの出力では、作成されたサービスプリンシパルの objectId が返されます。この例では、objectId は aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb です。このサービスプリンシパルに同期ジョブを追加するには、Microsoft Graph を使用します。

同期ジョブの作成に関するドキュメントについては、こちらを参照してください。

この ID をメモしなかった場合は、次の MS Graph 呼び出しを実行してサービスプリンシパルを確認できます。この呼び出しを行うには、Directory.Read.All アクセス許可が必要です。

GET https://graph.microsoft.com/beta/servicePrincipals

次に、出力からアプリ名を探します。

次の 2 つのコマンドを実行して、2 つのジョブを作成します。1 つはユーザーまたはグループのプロビジョニング用、もう 1 つはパスワードハッシュ同期用です。これは 2 回繰り返されている同じ要求ですが、テンプレート ID が異なります。

次の 2 つの要求を呼び出します。

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AD2AADProvisioning"
}

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AD2AADPasswordHash"
}

両方を作成する場合は、2 回呼び出す必要があります。

戻り値の例 (プロビジョニングの場合):

HTTP 201/Created
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals('aaaaaaaa-0000-1111-2222-bbbbbbbbbbbbc')/synchronization/jobs/$entity",
    "id": "AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da",
    "templateId": "ADDCInPassthrough",
    "schedule": {
        "expiration": null,
        "interval": "PT40M",
        "state": "Disabled"
    },
    "status": {
        "countSuccessiveCompleteFailures": 0,
        "escrowsPruned": false,
        "code": "Paused",
        "lastExecution": null,
        "lastSuccessfulExecution": null,
        "lastSuccessfulExecutionWithExports": null,
        "quarantine": null,
        "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
        "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
        "troubleshootingUrl": null,
        "progress": [],
        "synchronizedEntryCountByType": []
    }
}

ターゲットドメインを更新する

このテナントでは、サービスプリンシパルのオブジェクト識別子とアプリケーション識別子は次のようになります。

ObjectId: bbbbbbbb-1111-2222-3333-cccccccccccc
AppId: 00001111-aaaa-2222-bbbb-3333cccc4444
DisplayName: testApp

この構成の対象となるドメインを更新する必要があります。そのため、このドメインのシークレットを更新してください。

使用するドメイン名が、オンプレミスのドメインコントローラーに設定した URL と同じであることを確認します。

PUT – https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/secrets

実行しようとしている内容に基づいて、次の値配列に次のキーと値のペアを追加します。

PHS と同期テナントフラグの両方を有効にする { key:"AppKey", value: "{"appKeyScenario":"AD2AADPasswordHash"}" }
同期テナントフラグのみを有効にする (PHS を有効にしない) { key: "AppKey", value: "{"appKeyScenario":"AD2AADProvisioning"}" }

Request body –
{
   "value": [
              {
                "key": "Domain",
                "value": "{\"domain\":\"ad2aadTest.com\"}"
              }
            ]
}

予期される応答は次の通りです: HTTP 204/No content

ここで強調表示されている "Domain" 値は、オンプレミスの Active Directory ドメインの名前であり、エントリはそこから Microsoft Entra ID にプロビジョニングされます。

構成ブレードでパスワードハッシュの同期を有効にする

このセクションでは、特定の構成のパスワードハッシュの同期を有効にする方法について説明します。この状況は、テナントレベルの機能フラグを有効にする AppKey シークレットとは異なります。この手順は、1 つのドメインまたは構成のみに適用されます。この手順がエンドツーエンドで動作するようにするには、アプリケーションキーを PHS に設定する必要があります。

スキーマを取得する (非常に大容量):

GET –https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema

この CredentialData 属性のマッピングを取得する:

{
"defaultValue": null,
"exportMissingReferences": false,
"flowBehavior": "FlowWhenChanged",
"flowType": "Always",
"matchingPriority": 0,
"targetAttributeName": "CredentialData",
"source": {
"expression": "[PasswordHash]",
"name": "PasswordHash",
"type": "Attribute",
"parameters": []
}

スキーマで次の名前を持つ次のオブジェクトマッピングを検索する
- Active Directory Domain Services Users のプロビジョニング
- Active Directory Domain Services inetOrgPersons のプロビジョニング
オブジェクトマッピングは、schema.synchronizationRules[0].objectMappings 内にあります (現時点では、1 つの同期規則のみがあると想定)
手順 (2) から CredentialData マッピングを取得し、手順 (3) でオブジェクトマッピングに挿入します

オブジェクトマッピングは次のようになります。
```
{
"enabled": true,
"flowTypes": "Add,Update,Delete",
"name": "Provision Active Directory users",
"sourceObjectName": "user",
"targetObjectName": "User",
"attributeMappings": [
...
} 
```
AD2AADProvisioning ジョブと AD2AADPasswordHash ジョブの作成手順からのマッピングをコピーして attributeMappings 配列に貼り付けます。

この配列内の要素の順序は重要ではありません (バックエンドによって並べ替えられます)。名前が配列に既に存在する場合は、この属性マッピングの追加に注意してください。たとえば、attributeMappings に targetAttributeName CredentialData を含む項目が既にある場合、競合エラーが発生したり、既存のマッピングと新しいマッピングが組み合わされたりすることがあります。通常、これは望ましい結果ではありません。バックエンドでの重複除去は行われません。

このアクションは、Users と inetOrgpersons の両方に対して実行してください。

作成したスキーマを保存します。

PUT –
https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema

要求本文にスキーマを追加します。

Exchange ハイブリッドの書き戻し (パブリックプレビュー)

このセクションでは、Exchange ハイブリッドの書き戻しについて、プログラムでの有効化/無効化の方法と使用方法を説明します。

Exchange ハイブリッドの書き戻しをプログラムで有効化するには、2 つの手順が必要になります。

スキーマの検証
Exchange ハイブリッドの書き戻しジョブの作成

スキーマの検証

Exchange ハイブリッドライトバックを有効にして使用する前に、クラウド同期は、オンプレミスの Active Directory が Exchange スキーマを含むように拡張されたかどうかを判断する必要があります。

directoryDefinition:discover を使用してスキーマ検出を開始できます。

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/[AD2AADProvisioningJobId]/schema/directories/[ADDirectoryID]/discover

予期される応答は次の通りです: HTTP 200/OK

応答は、次の出力のようになります。

HTTP/1.1 200 OK
Content-type: application/json
{
  "objects": [
    {
      "name": "user",
      "attributes": [
        {
          "name": "mailNickName",
          "type": "String"
        },
        ...
      ]
    },
    ...
  ]
}

ここで、mailNickName 属性が存在するかどうかを確認します。存在していれば、スキーマは検証済みとなります。つまり、Exchange 属性が含まれています。存在していない場合は、Exchange ハイブリッドの書き戻しの前提条件を再確認してください。

Exchange ハイブリッドの書き戻しジョブの作成

スキーマを検証したら、ジョブを作成できます。

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AAD2ADExchangeHybridWriteback"
}

不注意による削除

このセクションでは、プログラムによる有効化または無効化、およびプログラムによる誤削除の使用方法について説明します。

しきい値の有効化と設定

ジョブの設定ごとに使用できるものには次の 2 つがあります。

DeleteThresholdEnabled - 'true' に設定されている場合は、ジョブの誤削除防止が有効になります。既定では 'true' に設定されます。
DeleteThresholdValue - 誤削除防止が有効になっている場合は、ジョブの各実行で許可される削除の最大数を定義します。既定では、値は 500 に設定されています。したがって、値が 500 に設定されている場合、各実行で許可される削除の最大数は 499 です。

削除のしきい値の設定は SyncNotificationSettings の一部であり、グラフを使用して変更できます。

この構成の対象となる SyncNotificationSettings を更新する必要があるため、シークレットを更新します。

PUT – https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/secrets

実行しようとしている内容に基づいて、次の値配列に次のキーと値のペアを追加します。

Request body -
{
  "value":[
    {
      "key":"SyncNotificationSettings",
      "value": "{\"Enabled\":true,\"Recipients\":\"foobar@xyz.com\",\"DeleteThresholdEnabled\":true,\"DeleteThresholdValue\":50}"
     }
  ]
}

例にある "Enabled" の設定は、ジョブが検疫されたときに通知メールを有効または無効にするためのものです。

現時点では、シークレットに対する PATCH 要求はサポートされていません。そのため、他の値を保持するには、例のように、PUT 要求の本文にすべての値を追加する必要があります。

すべてのシークレットの既存の値は、以下を使用して取得できます。

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

削除を許可する

ジョブが検疫された後に削除が通過できるようにするには、スコープとして "ForceDeletes" のみを使用して再起動を発行する必要があります。

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

Request Body:
{
  "criteria": {"resetScope": "ForceDeletes"}
}

同期ジョブを開始する

ジョブは、次のコマンドを使用して再度取得できます。

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

ジョブを取得するためのドキュメントについては、こちらを参照してください。

ジョブを開始するには、最初の手順で作成したサービスプリンシパルの objectId と、ジョブを作成した要求から返されたジョブ識別子を使用して、以下の要求を発行します。

ジョブを開始する方法のドキュメントについては、こちらを参照してください。

POST  https://graph.microsoft.com/beta/servicePrincipals/8895955e-2e6c-4d79-8943-4d72ca36878f/synchronization/jobs/AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da/start

予期される応答は次の通りです: HTTP 204/No content。

ジョブを制御するその他のコマンドについては、こちらに記載されています。

ジョブを再開するには、次を使用します。

POST  https://graph.microsoft.com/beta/servicePrincipals/8895955e-2e6c-4d79-8943-4d72ca36878f/synchronization/jobs/AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da/restart
{
  "criteria": {
    "resetScope": "Full"
  }
}

状態をレビューする

次を使用してジョブの状態を取得します。

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

関連する詳細については、返されたオブジェクトの 'status' セクションを参照してください。

次の方法で共有

MS Graph API を使用してクラウドの同期をプログラムで構成する方法

基本的なセットアップ

テナントフラグを有効にする

サービスプリンシパルの作成

同期ジョブを作成する

ターゲットドメインを更新する

構成ブレードでパスワードハッシュの同期を有効にする

Exchange ハイブリッドの書き戻し (パブリックプレビュー)

スキーマの検証

Exchange ハイブリッドの書き戻しジョブの作成

不注意による削除

しきい値の有効化と設定

削除を許可する

同期ジョブを開始する

状態をレビューする

次のステップ

フィードバック

その他のリソース

次の方法で共有

MS Graph API を使用してクラウドの同期をプログラムで構成する方法

基本的なセットアップ

テナント フラグを有効にする

サービス プリンシパルの作成

同期ジョブを作成する

ターゲット ドメインを更新する

構成ブレードでパスワード ハッシュの同期を有効にする

Exchange ハイブリッドの書き戻し (パブリック プレビュー)

スキーマの検証

Exchange ハイブリッドの書き戻しジョブの作成

不注意による削除

しきい値の有効化と設定

削除を許可する

同期ジョブを開始する

状態をレビューする

次のステップ

フィードバック

その他のリソース

テナントフラグを有効にする

サービスプリンシパルの作成

ターゲットドメインを更新する

構成ブレードでパスワードハッシュの同期を有効にする

Exchange ハイブリッドの書き戻し (パブリックプレビュー)