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 エクスプローラー (推奨)、または使用しているその他の API クライアントにサインインする
- Microsoft Graph エクスプローラーを開始します。
- [Microsoft アカウントでサインイン] ボタンを選択し、アプリケーション管理者ロールを持つユーザーでサインインします。
- サインインに成功すると、左側のペインにユーザー アカウントの詳細が表示されます。
ギャラリー アプリケーション テンプレート識別子を取得する
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"
}
]
}
]
}