使用 Microsoft Graph API 設定佈建

發行項
07/30/2024

Microsoft Entra 系統管理中心是一種針對個別應用程式逐一設定佈建的便利方式。但是，如果您要建立數個 (或甚至數百個) 應用程式執行個體，或將應用程式設定從某個環境移轉至另一個環境，則使用 Microsoft Graph API 來將應用程式建立和設定自動化會比較容易。此文章概述如何透過 API 來將佈建設定自動化。此方法通常用於 Amazon Web Services 之類的應用程式。

本文說明 Microsoft Graph 搶鮮版 (Beta) 端點和 Microsoft Graph 總管中使用 API 的程序；Microsoft Graph v1.0 端點中也提供類似的 API。如需使用 Graph v1.0 和 PowerShell 設定佈建的範例，請參閱使用 PowerShell 或 Microsoft Graph API 設定跨租用戶同步處理的步驟 6-13。

使用 Microsoft Graph API 來將佈建設定自動化的步驟概觀

Step	詳細資料
步驟 1：建立資源庫應用程式	登入 API 用戶端擷取資源庫應用程式範本建立資源庫應用程式
步驟 2。根據範本建立佈建作業	擷取適用於佈建連接器的範本建立佈建作業
步驟 3：授權存取	測試與應用程式的連線儲存認證
步驟 4. 開始佈建作業	啟動工作
步驟 5：監視佈建	檢查佈建作業的狀態擷取佈建記錄

如果您要佈建至內部部署應用程式，則也需要安裝和設定佈建代理程式，並將佈建代理程式指派給應用程式。

步驟 1：建立資源庫應用程式

啟動 Microsoft Graph 總管 \(英文\)。
選取 [使用 Microsoft 登入] 按鈕，並使用具有應用程式系統管理員角色的使用者登入。
成功登入時，您會在左側窗格中看到使用者帳戶詳細資料。

擷取資源庫應用程式範本識別碼

Microsoft Entra 應用程式資源庫中的應用程式各有一個應用程式範本，可說明該應用程式的中繼資料。使用此範本，您可以在租用戶中建立應用程式和服務主體的執行個體以進行管理。擷取適用於 AWS 單一帳戶存取的應用程式範本識別碼，並從回應中，記錄 id 屬性的值，以便稍後在此教學課程中使用。

要求

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

回應

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."    

}

建立資源庫應用程式

使用在前一個步驟中針對應用程式擷取的範本識別碼，在您的租用戶中建立應用程式和服務主體的執行個體。

要求

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

{
  "displayName": "AWS Contoso"
}

回應

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：根據範本建立佈建作業

擷取適用於佈建連接器的範本

已在資源庫中啟用來進行佈建的應用程式，具有可簡化設定的範本。使用下方要求來擷取用於佈建設定的範本。請注意，您將需提供識別碼。識別碼是在上一個步驟中建立的 servicePrincipal 資源識別碼。

要求

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

回應

HTTP/1.1 200 OK

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

建立佈建作業

若要啟用佈建，您將需要先建立作業。使用下列要求來建立佈建作業。指定要用於作業的範本時，請使用前一個步驟中的 templateId。

要求

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

{ 
    "templateId": "aws"
}

回應

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。在 Microsoft Entra 系統管理中心中，BaseAddress 稱為租用戶 URL。

要求

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

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

回應

HTTP/1.1 204 No Content

儲存認證

設定佈建需要建立 Microsoft Entra ID 與應用程式之間的信任，才能授權 Microsoft Entra 能夠呼叫第三方應用程式。下列範例專屬於需要用戶端密碼和祕密權杖的應用程式。每個應用程式都有自己的需求。檢閱 API 文件，以查看可用選項。

要求

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

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

回應

HTTP/1.1 204 No Content

步驟 4：啟動佈建作業

現在已設定佈建作業，請使用下列命令來啟動作業。

要求

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

回應

HTTP/1.1 204 No Content

步驟 5：監視佈建

監視佈建作業狀態

既然佈建工作正在執行，請使用下列命令來追蹤進度。回應中的每個同步處理工作都會包括目前佈建週期的狀態，以及到目前為止的統計資料，例如已在目標系統中建立的使用者和群組數目。

要求

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

回應

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"
      }
    ]
}
]
}

使用佈建記錄監視佈建事件

除了監視佈建作業的狀態之外，您還可以使用佈建記錄來查詢所有發生的事件。例如，查詢特定使用者並判斷其是否已成功佈建。

要求

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

回應

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"
            }
            ]
       }
    ]
}

共用方式為

使用 Microsoft Graph API 設定佈建

步驟 1：建立資源庫應用程式

擷取資源庫應用程式範本識別碼

要求

回應

建立資源庫應用程式

要求

回應

步驟 2：根據範本建立佈建作業

擷取適用於佈建連接器的範本

要求

回應

建立佈建作業

要求

回應

步驟 3：授權存取

測試與應用程式的連線

要求

回應

儲存認證

要求

回應

步驟 4：啟動佈建作業

要求

回應

步驟 5：監視佈建

監視佈建作業狀態

要求

回應

使用佈建記錄監視佈建事件

要求

回應

另請參閱

意見反應

其他資源

共用方式為

使用 Microsoft Graph API 設定佈建

步驟 1：建立資源庫應用程式

登入 Microsoft Graph 總管 （建議），或任何其他您使用的 API 用戶端

擷取資源庫應用程式範本識別碼

要求

回應

建立資源庫應用程式

要求

回應

步驟 2：根據範本建立佈建作業

擷取適用於佈建連接器的範本

要求

回應

建立佈建作業

要求

回應

步驟 3：授權存取

測試與應用程式的連線

要求

回應

儲存認證

要求

回應

步驟 4：啟動佈建作業

要求

回應

步驟 5：監視佈建

監視佈建作業狀態

要求

回應

使用佈建記錄監視佈建事件

要求

回應

另請參閱

意見反應

其他資源

登入 Microsoft Graph 總管（建議），或任何其他您使用的 API 用戶端