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

[アーティクル]
07/27/2022

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

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

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

手順 1:ギャラリーアプリケーションを作成する

Microsoft Graph エクスプローラーを開始します。
[Sign-In with Microsoft]\(Microsoft アカウントでサインイン\) ボタンを選択し、Azure AD 全体管理者またはアプリ管理者の資格情報を使用してサインインします。
サインインに成功すると、左側のペインにユーザーアカウントの詳細が表示されます。

ギャラリーアプリケーションテンプレート識別子を取得する

Azure AD アプリケーションギャラリーのアプリケーションにはそれぞれ、そのアプリケーションのメタデータを記述するアプリケーションテンプレートがあります。このテンプレートを使用して、管理用のテナントにアプリケーションとサービスプリンシパルのインスタンスを作成できます。 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/{id}/instantiate
Content-type: application/json

{
  "displayName": "AWS Contoso"
}

Response

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

{
    "application": {
        "objectId": "cbc071a6-0fa5-4859-8g55-e983ef63df63",
        "appId": "92653dd4-aa3a-3323-80cf-e8cfefcc8d5d",
        "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": "f47a6776-bca7-4f2e-bc6c-eec59d058e3e",
        "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 リソース) を示します。

Request

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 は、Azure portal でテナントの URL として表されます。

Request

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

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

Response

HTTP/1.1 204 No Content

資格情報を保存する

プロビジョニングを構成するには、Azure AD とアプリケーションの間に信頼を確立する必要があります。サードパーティアプリケーションへのアクセスを承認します。クライアントシークレットとシークレットトークンを必要とするアプリケーションの例を次に示します。アプリケーションにはそれぞれ独自の要件があります。 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: プロビジョニングを監視する

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

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

Request

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

Response

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

{
    "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": "7928d5b5-7442-4a97-ne2d-66f9j9972ecn",
            "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": "f2764360-e0ec-5676-711e-cd6fc0d4dd61",
                    "ServicePrincipalId": "chc46a42-966b-47d7-9774-576b1c8bd0b8",
                    "ServicePrincipalDisplayName": "AWS Contoso"
                }
            },
            "initiatedBy": {
                "id": "",
                "displayName": "Azure AD Provisioning Service",
                "initiatorType": "system"
            }
            ]
       }
    ]
}

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

手順 1:ギャラリー アプリケーションを作成する

Microsoft Graph エクスプローラー (推奨)、Postman、または使用しているその他の API クライアントにサインインする

ギャラリー アプリケーション テンプレート識別子を取得する

Request

Response

ギャラリー アプリケーションを作成する

Request

Response

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

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

Request

Response

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

Request

Response

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

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

Request

Response

資格情報を保存する

Request

Response

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

Request

Response

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

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

Request

Response

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

Request

Response

関連項目

手順 1:ギャラリーアプリケーションを作成する

ギャラリーアプリケーションテンプレート識別子を取得する

ギャラリーアプリケーションを作成する

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

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

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

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

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

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