次の方法で共有


Microsoft Graph API を使用してプロビジョニングを構成する

Microsoft Entra 管理センターは、個々のアプリのプロビジョニングを一度に 1 つずつ構成する便利な方法です。 しかし、アプリケーションのインスタンスを複数作成する場合 (または作成するインスタンスの数が数百にも及ぶ場合、アプリケーション構成をある環境から別の環境に移行する場合) は、Microsoft Graph API を使用してアプリの作成と構成を自動化すると、より簡単です。 この記事では、API を使用してプロビジョニングの構成を自動化する方法について説明します。 この方法は、アマゾン ウェブ サービスなどのアプリケーションで一般的に使用されています。

この記事では、Microsoft Graph ベータ エンドポイントと Microsoft Graph Explorer での API を使用したプロセスについて説明します。同様の API は、Microsoft Graph v1.0 エンドポイントでも使用できます。 Graph v1.0 と PowerShell を使用してプロビジョニングを構成する例については、「PowerShell または Microsoft Graph API を使用してテナント間同期を構成する」の手順 6 から 13 を参照してください。

Microsoft Graph API を使用してプロビジョニングの構成を自動化する手順の概要

手順 詳細
手順 1. ギャラリー アプリケーションを作成する API クライアントにサインインする
ギャラリー アプリケーション テンプレートを取得する
ギャラリー アプリケーションを作成する
手順 2. テンプレートに基づいてプロビジョニング ジョブを作成する プロビジョニング コネクタのテンプレートを取得する
プロビジョニング ジョブを作成する
手順 3. アクセスを承認する アプリケーションへの接続をテストする
資格情報を保存する
手順 4. プロビジョニング ジョブを開始する ジョブの開始
手順 5. プロビジョニングを監視する プロビジョニング ジョブの状態を確認する
プロビジョニング ログを取得する

オンプレミスのアプリケーションにプロビジョニングする場合は、プロビジョニング エージェントをインストールして構成し、プロビジョニング エージェントをアプリケーションに割り当てる必要もあります。

  1. Microsoft Graph エクスプローラーを開始します。
  2. [Microsoft アカウントでサインイン] ボタンを選択し、アプリケーション管理者ロールを持つユーザーでサインインします。
  3. サインインに成功すると、左側のペインにユーザー アカウントの詳細が表示されます。

Microsoft Entra アプリケーション ギャラリーのアプリケーションにはそれぞれ、そのアプリケーションのメタデータを記述するアプリケーション テンプレートがあります。 このテンプレートを使用して、管理用のテナントにアプリケーションとサービス プリンシパルのインスタンスを作成できます。 AWS Single-Account Access のアプリケーション テンプレートとその応答の識別子を取得し、id プロパティの値を記録します。これは、このチュートリアルの後の部分で使用します。

Request

GET https://graph.microsoft.com/beta/applicationTemplates?$filter=displayName eq 'AWS Single-Account Access'

Response

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
  {
    "id": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
        "displayName": "AWS Single-Account Access",
        "homePageUrl": "http://aws.amazon.com/",
        "supportedSingleSignOnModes": [
             "password",
             "saml",
             "external"
         ],
         "supportedProvisioningTypes": [
             "sync"
         ],
         "logoUrl": "https://az495088.vo.msecnd.net/app-logo/aws_215.png",
         "categories": [
             "developerServices"
         ],
         "publisher": "Amazon",
         "description": "Federate to a single AWS account and use SAML claims to authorize access to AWS IAM roles. If you have many AWS accounts, consider using the AWS Single Sign-On gallery application instead."    

}

前のステップで取得したアプリケーションのテンプレート ID を使用して、ご自身のテナント内にアプリケーションとサービス プリンシパルのインスタンスを作成します。

Request

POST https://graph.microsoft.com/beta/applicationTemplates/{applicationTemplateId}/instantiate
Content-type: application/json

{
  "displayName": "AWS Contoso"
}

Response

HTTP/1.1 201 OK
Content-type: application/json

{
    "application": {
        "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "applicationTemplateId": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
        "displayName": "AWS Contoso",
        "homepage": "https://signin.aws.amazon.com/saml?metadata=aws|ISV9.1|primary|z",
        "replyUrls": [
            "https://signin.aws.amazon.com/saml"
        ],
        "logoutUrl": null,
        "samlMetadataUrl": null,
    },
    "servicePrincipal": {
        "objectId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "appDisplayName": "AWS Contoso",
        "applicationTemplateId": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
        "appRoleAssignmentRequired": true,
        "displayName": "My custom name",
        "homepage": "https://signin.aws.amazon.com/saml?metadata=aws|ISV9.1|primary|z",
        "replyUrls": [
            "https://signin.aws.amazon.com/saml"
        ],
        "servicePrincipalNames": [
            "93653dd4-aa3a-4323-80cf-e8cfefcc8d7d"
        ],
        "tags": [
            "WindowsAzureActiveDirectoryIntegratedApp"
        ],
    }
}

手順 2. テンプレートに基づいてプロビジョニング ジョブを作成する

プロビジョニング コネクタのテンプレートを取得する

ギャラリー内の、プロビジョニングが有効になっているアプリケーションには、構成を効率化するためのテンプレートがあります。 次の要求を使用して、プロビジョニング構成のテンプレートを取得します。 ID を指定する必要があることに注意してください。 ID は、前のステップで作成した servicePrincipal リソースの ID です。

要求

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

Response

HTTP/1.1 200 OK

{
    "value": [
        {
            "id": "aws",
            "factoryTag": "aws",
            "schema": {
                    "directories": [],
                    "synchronizationRules": []
                    }
        }
    ]
}

プロビジョニング ジョブを作成する

プロビジョニングを有効にするには、まずジョブを作成する必要があります。 プロビジョニング ジョブを作成するには、次の要求を使用します。 ジョブに使用するテンプレートを指定するときは、前の手順の templateId を使用します。

Request

POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs
Content-type: application/json

{ 
    "templateId": "aws"
}

Response

HTTP/1.1 201 OK
Content-type: application/json

{
    "id": "{jobId}",
    "templateId": "aws",
    "schedule": {
        "expiration": null,
        "interval": "P10675199DT2H48M5.4775807S",
        "state": "Disabled"
    },
    "status": {
        "countSuccessiveCompleteFailures": 0,
        "escrowsPruned": false,
        "synchronizedEntryCountByType": [],
        "code": "NotConfigured",
        "lastExecution": null,
        "lastSuccessfulExecution": null,
        "lastSuccessfulExecutionWithExports": null,
        "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
        "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
        "quarantine": null,
        "troubleshootingUrl": null
    }
}

手順 3. アクセスを承認する

アプリケーションへの接続をテストする

サードパーティ アプリケーションとの接続をテストします。 クライアント シークレットとシークレット トークンを必要とするアプリケーションの例を次に示します。 アプリケーションにはそれぞれ独自の要件があります。 多くの場合、クライアント シークレットの代わりにベース アドレスがアプリケーションで使用されます。 アプリで必要な資格情報を確認するには、アプリケーションのプロビジョニング構成ページに移動し、開発者モードで [テスト接続] をクリックします。 ネットワーク トラフィックに、資格情報に使用されたパラメーターが表示されます。 資格情報の完全な一覧については、「synchronizationJob: validateCredentials」を参照してください。 Azure Databricks などのほとんどのアプリケーションは、BaseAddress と SecretToken に依存しています。 BaseAddress は、Microsoft Entra 管理センターではテナント URL と呼ばれます。

要求

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

{ 
    "credentials": [ 
        { 
            "key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx" 
        },
        {
            "key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

Response

HTTP/1.1 204 No Content

資格情報を保存する

プロビジョニングを構成するには、Microsoft Entra ID とアプリケーションの間に信頼を確立して、サードパーティのアプリケーションを呼び出す機能を持つことを Microsoft Entra に承認する必要があります。 クライアント シークレットとシークレット トークンを必要とするアプリケーションの例を次に示します。 アプリケーションにはそれぞれ独自の要件があります。 API ドキュメントを参照して、使用可能なオプションを確認してください。

Request

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

{ 
    "value": [ 
        { 
            "key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx"
        },
        {
            "key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

Response

HTTP/1.1 204 No Content

手順 4: プロビジョニング ジョブを開始する

プロビジョニング ジョブが構成されたので、次のコマンドを使用してジョブを開始します。

Request

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

Response

HTTP/1.1 204 No Content

手順 5: プロビジョニングを監視する

プロビジョニング ジョブの状態を監視する

プロビジョニング ジョブが実行されているので、次のコマンドを使って進行状況を追跡します。 応答の各同期ジョブには、現在のプロビジョニング サイクルの状態と共に、ターゲット システムで作成されたユーザーとグループの数など、現在までの統計情報が含まれます。

要求

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

Response

HTTP/1.1 200 OK
Content-type: application/json

{ "value": [
{
    "id": "{jobId}",
    "templateId": "aws",
    "schedule": {
        "expiration": null,
        "interval": "P10675199DT2H48M5.4775807S",
        "state": "Disabled"
    },
    "status": {
        "countSuccessiveCompleteFailures": 0,
        "escrowsPruned": false,
        "synchronizedEntryCountByType": [],
        "code": "Paused",
        "lastExecution": null,
        "lastSuccessfulExecution": null,
        "progress": [],
        "lastSuccessfulExecutionWithExports": null,
        "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
        "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
        "quarantine": null,
        "troubleshootingUrl": null
    },
    "synchronizationJobSettings": [
      {
          "name": "QuarantineTooManyDeletesThreshold",
          "value": "500"
      }
    ]
}
]
}

プロビジョニング ログを使用してプロビジョニング イベントを監視する

プロビジョニング ジョブの状態の監視に加えて、プロビジョニング ログを使用して、発生しているすべてのイベントについてクエリを実行できます。 たとえば、特定のユーザーについてクエリを実行し、正常にプロビジョニングされたかどうかを判断します。

Request

GET https://graph.microsoft.com/beta/auditLogs/provisioning

Response

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#auditLogs/provisioning",
    "value": [
        {
            "id": "gc532ff9-r265-ec76-861e-42e2970a8218",
            "activityDateTime": "2019-06-24T20:53:08Z",
            "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
            "cycleId": "44576n58-v14b-70fj-8404-3d22tt46ed93",
            "changeId": "eaad2f8b-e6e3-409b-83bd-e4e2e57177d5",
            "action": "Create",
            "durationInMilliseconds": 2785,
            "sourceSystem": {
                "id": "0404601d-a9c0-4ec7-bbcd-02660120d8c9",
                "displayName": "Azure Active Directory",
                "details": {}
            },
            "targetSystem": {
                "id": "cd22f60b-5f2d-1adg-adb4-76ef31db996b",
                "displayName": "AWS Contoso",
                "details": {
                    "ApplicationId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                    "ServicePrincipalId": "chc46a42-966b-47d7-9774-576b1c8bd0b8",
                    "ServicePrincipalDisplayName": "AWS Contoso"
                }
            },
            "initiatedBy": {
                "id": "",
                "displayName": "Azure AD Provisioning Service",
                "initiatorType": "system"
            }
            ]
       }
    ]
}

関連項目