使用 Microsoft Graph 管理Microsoft Entra应用程序

应用必须在 Microsoft Entra ID 中注册,Microsoft 标识平台才能授权其访问存储在 Microsoft Entra 或 Microsoft 365 租户中的数据。 此条件适用于你自己开发的应用、租户拥有的应用或通过活动订阅访问的应用。

许多应用的设置记录为对象,可以使用 Microsoft Graph 访问、更新或删除这些设置。 本文介绍如何使用 Microsoft Graph 管理应用和服务主体对象,包括属性、权限和角色分配。

先决条件

若要测试 API 操作,需要以下资源和特权:

  • 工作Microsoft Entra租户。
  • 以有权在租户中创建和管理应用程序的用户身份登录 Graph 资源管理器
  • 向自己授予为操作指示的最小特权委托权限。

使用 Microsoft Entra ID 注册应用程序

以下请求通过仅指定所需的 displayName 属性来创建应用。

最低特权委托权限: Application.ReadWrite.All

POST https://graph.microsoft.com/v1.0/applications
Content-type: application/json

{
  "displayName": "My application"
}

请求在响应正文中返回 201 Created 带有应用程序对象的响应。 为应用程序分配了一个对租户中应用唯一的 ID,以及一个在Microsoft Entra ID生态系统中全局唯一的 appId

Create应用程序的服务主体

最低特权委托权限: Application.ReadWrite.All

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json

{
  "appId": "fc876dd1-6bcb-4304-b9b6-18ddf1526b62"
}

请求返回响应 201 Created 正文中包含服务主体对象的响应。

寻址应用程序或服务主体对象

可以通过应用程序或服务主体的 ID 或其 appId 来寻址,其中 ID 称为“对象 ID”,appId 在Microsoft Entra 管理中心上称为“应用程序 (客户端) ID”。 应用程序和服务主体上的所有 HTTP CRUD 操作都支持这些语法。

按应用程序或服务主体 ID 寻址。

https://graph.microsoft.com/v1.0/applications/{applicationObjectId}
https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalObjectId}

appId 对应用程序或服务主体进行寻址。

https://graph.microsoft.com/v1.0/applications(appId='appId')
https://graph.microsoft.com/v1.0/servicePrincipals(appId='appId')

为应用配置其他基本属性

最低特权委托权限: Application.ReadWrite.All

为应用配置以下基本属性。

  • 在组织中添加用于分类的标记。 此外,使用 HideApp 标记对我的应用和 Microsoft 365 启动器隐藏应用。
  • 添加基本信息,包括徽标、服务条款和隐私声明。
  • 存储有关应用程序的联系人信息
PATCH https://graph.microsoft.com/v1.0/applications/0d0021e2-eaab-4b9f-a5ad-38c55337d63e/
Content-type: application/json

{
    "tags": [
        "HR",
        "Payroll",
        "HideApp"
    ],
    "info": {
        "logoUrl": "https://cdn.pixabay.com/photo/2016/03/21/23/25/link-1271843_1280.png",
        "marketingUrl": "https://www.contoso.com/app/marketing",
        "privacyStatementUrl": "https://www.contoso.com/app/privacy",
        "supportUrl": "https://www.contoso.com/app/support",
        "termsOfServiceUrl": "https://www.contoso.com/app/termsofservice"
    },
    "web": {
        "homePageUrl": "https://www.contoso.com/",
        "logoutUrl": "https://www.contoso.com/frontchannel_logout",
        "redirectUris": [
            "https://localhost"
        ]
    },
    "serviceManagementReference": "Owners aliases: Finance @ contosofinance@contoso.com; The Phone Company HR consulting @ hronsite@thephone-company.com;"
}

将应用登录限制为仅分配的标识

最低特权委托权限: Application.ReadWrite.All

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/89473e09-0737-41a1-a0c3-1418d6908bcd

{
    "appRoleAssignmentRequired": true
}

为应用分配权限

虽然可以通过Microsoft Entra 管理中心向应用分配权限,但也可以通过 Microsoft Graph 通过更新应用对象的 requiredResourceAccess 属性来分配权限。 必须传入现有权限和新权限。 仅传入新权限会覆盖并删除尚未同意的现有权限。

分配权限不会自动向他们授予应用。 你仍必须使用 Microsoft Entra 管理中心 授予管理员同意。 若要在没有交互式许可的情况下授予权限,请参阅 以编程方式授予或撤销 API 权限

最低特权委托权限: Application.ReadWrite.All

PATCH https://graph.microsoft.com/v1.0/applications/581088ba-83c5-4975-b8af-11d2d7a76e98
Content-Type: application/json

{
    "requiredResourceAccess": [
        {
            "resourceAppId": "00000002-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
                    "type": "Scope"
                },
                {
                    "id": "3afa6a7d-9b1a-42eb-948e-1650a849e176",
                    "type": "Role"
                }
            ]
        }
    ]
}

Create应用角色

在应用程序对象上Create应用角色

若要保留任何现有应用角色,请将其包含在请求中。 否则,它们将替换为新 对象。

PATCH https://graph.microsoft.com/v1.0/applications/bbd46130-e957-4c38-a116-d4d02afd1057
Content-Type: application/json

{
    "appRoles": [
        {
            "allowedMemberTypes": [
                "User",
                "Application"
            ],
            "description": "Survey.Read",
            "displayName": "Survey.Read",
            "id": "7a9ddfc4-cc8a-48ea-8275-8ecbffffd5a0",
            "isEnabled": false,
            "origin": "Application",
            "value": "Survey.Read"
        }
    ]
}

管理所有者

使用一个所有者标识无所有者服务主体和服务主体

最低特权委托权限: Application.ReadWrite.All

此请求要求将 ConsistencyLevel 标头设置为 eventual,因为在请求中有 $count。 有关使用 ConsistencyLevel$count的详细信息,请参阅 目录对象的高级查询功能

此请求还返回与筛选条件匹配的应用计数。

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=owners/$count eq 0 or owners/$count eq 1&$count=true
ConsistencyLevel: eventual

将所有者分配到应用

最低特权委托权限: Application.ReadWrite.All

在以下请求中, 8afc02cb-4d62-4dba-b536-9f6d73e9be26 是用户或服务主体的对象 ID。

POST https://graph.microsoft.com/v1.0/applications/7b45cf6d-9083-4eb2-92c4-a7e090f1fc40/owners/$ref
Content-Type: application/json

{
    "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/8afc02cb-4d62-4dba-b536-9f6d73e9be26"
}

将所有者分配到服务主体

最低特权委托权限: Application.ReadWrite.All

以下请求使用 其 appId 引用服务主体。 8afc02cb-4d62-4dba-b536-9f6d73e9be26 是用户或服务主体的对象 ID。

POST https://graph.microsoft.com/v1.0/servicePrincipals(appId='46e6adf4-a9cf-4b60-9390-0ba6fb00bf6b')/owners/$ref
Content-Type: application/json

{
    "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/8afc02cb-4d62-4dba-b536-9f6d73e9be26"
}

锁定服务主体的敏感属性

使用应用实例锁定功能,可以保护多租户应用的敏感属性免受未经授权的篡改。 可以锁定服务主体对象的以下属性:

  • keyCredentials ,其中使用类型为 SignVerify
  • passwordCredentials ,其中使用类型为 SignVerify
  • tokenEncryptionKeyId 属性。

可以通过多租户应用的应用程序对象的servicePrincipalLockConfiguration 属性管理应用实例锁定功能。

锁定服务主体的所有敏感属性

isEnabledallProperties 设置为 true时,即使 servicePrincipalLockConfiguration 对象的其他属性为 null,也会锁定服务主体的所有敏感属性。

PATCH https://graph.microsoft.com/beta/applications/a0b7f39e-3139-48aa-9397-f46fb63102f7

{
    "servicePrincipalLockConfiguration": {
        "isEnabled": true,
        "allProperties": true
    }
}

锁定服务主体的特定敏感属性

以下示例锁定服务主体的 keyCredentialspasswordCredentials 属性,并启用应用实例锁定功能。

PATCH https://graph.microsoft.com/beta/applications/a0b7f39e-3139-48aa-9397-f46fb63102f7

{
    "servicePrincipalLockConfiguration": {
        "isEnabled": true,
        "credentialsWithUsageSign": true,
        "credentialsWithUsageVerify": true
    }
}