使用 Microsoft Graph API 設定布建

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 總管
  2. 選取 [使用 Microsoft 登入] 按鈕,然後使用 Microsoft Entra Global 管理員 istrator 或 App 管理員 認證登入。
  3. 成功登入時,您會在左側窗格中看到使用者帳戶詳細數據。

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": "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:根據範本建立布建作業

擷取布建連接器的範本

資源庫中已啟用布建的應用程式具有範本來簡化設定。 使用下列要求來 擷取布建組態的範本。 請注意,您必須提供識別碼。 標識元是在上一個步驟中建立的 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": "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"
            }
            ]
       }
    ]
}

另請參閱