使用 Microsoft Graph API 配置预配

项目
07/30/2024

Microsoft Entra 管理中心是一次为一个应用配置预配的便捷方法。但是，如果要创建多个甚至数百个应用程序实例，或者将应用程序配置从一个环境迁移到另一个环境，则使用 Microsoft Graph API 自动创建和配置应用可能更容易。本文概述如何通过 API 自动配置预配。此方法通常用于 Amazon Web Services 等应用程序。

本文演示了 Microsoft Graph beta 终结点和 Microsoft Graph Explorer 中的 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 Explorer。
选择“使用 Microsoft 登录”按钮，并使用具有“应用程序管理员”角色的用户登录。
成功登录后，你将在左侧窗格中看到用户帐户详细信息。

检索库应用程序模板标识符

Microsoft Entra 应用程序库中的每个应用程序都有一个应用程序模板，它描述了该应用程序的元数据。通过此模板，可在租户中创建应用程序和服务主体的实例以进行管理。检索 AWS Single-Account Access 的应用程序模板的标识符，然后从响应中记录 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."    

}

创建库应用程序

使用在上一步上为应用程序检索得到的模板 ID 在租户中创建应用程序和服务主体的实例。

请求

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：基于模板创建预配作业

检索预配连接器的模板

库中支持预配的应用程序具有简化配置的模板。使用以下请求检索预配配置的模板。请注意，你将需要提供 ID。此 ID 是在上一步中创建的 servicePrincipal 资源的 ID。

请求

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 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：监视预配

监视预配作业状态

请求

响应

使用预配日志监视预配事件

请求

响应

另请参阅

反馈

其他资源