使用 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 總管(建議)、Postman 或任何其他您使用的 API 用戶端
- 啟動 Microsoft Graph 總管。
- 選取 [使用 Microsoft 登入] 按鈕,然後使用 Microsoft Entra Global 管理員 istrator 或 App 管理員 認證登入。
- 成功登入時,您會在左側窗格中看到使用者帳戶詳細數據。
擷取資源庫應用程式範本標識碼
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"
}
]
}
]
}