使用 Microsoft Graph API 設定布建

發行項
04/06/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 將布建設定自動化的步驟概觀

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

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

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

啟動 Microsoft Graph 總管。
選取 [使用 Microsoft 登入] 按鈕，並使用應用程式管理員 istrator 角色的使用者登入。
成功登入時，您會在左側窗格中看到使用者帳戶詳細數據。

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

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

回應

HTTP/1.1 204 No Content

儲存您的認證

設定布建需要建立 Microsoft Entra 識別符與應用程式之間的信任，才能授權 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"
            }
            ]
       }
    ]
}

Share via

使用 Microsoft Graph API 設定布建

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

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

要求

回應

建立資源庫應用程式

要求

回應

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

擷取布建連接器的範本

要求

回應

建立布建作業

要求

回應

步驟 3：授權存取權

測試應用程式的連線

要求

回應

儲存您的認證

要求

回應

步驟 4：啟動布建作業

要求

回應

步驟 5：監視布建

監視布建作業狀態

要求

回應

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

要求

回應

另請參閱

其他資源

Share via

使用 Microsoft Graph API 設定布建

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

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

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

要求

回應

建立資源庫應用程式

要求

回應

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

擷取布建連接器的範本

要求

回應

建立布建作業

要求

回應

步驟 3：授權存取權

測試應用程式的連線

要求

回應

儲存您的認證

要求

回應

步驟 4：啟動布建作業

要求

回應

步驟 5：監視布建

監視布建作業狀態

要求

回應

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

要求

回應

另請參閱

其他資源