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

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

许多应用的设置记录为可以使用 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

为应用程序创建服务主体

最低特权委托权限: 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')

此外,还可以对应用程序对象唯一其 uniqueName 进行寻址。 可以使用此属性创建具有唯一名称的应用程序(如果不存在),或者更新它(如果存在);称为“Upsert”的操作。

如果不存在,则创建具有指定 uniqueName 的应用程序,否则请对其进行更新。

PATCH https://graph.microsoft.com/v1.0/applications(uniqueName='{uniqueName}')
Content-Type: application/json
Prefer: create-if-missing

{
  "displayName": "Display name"
}

为应用配置其他基本属性

最低特权委托权限: 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 管理中心向应用分配权限,但也可以通过更新应用对象的 requiredResourceAccess 属性通过 Microsoft Graph 分配权限。 必须传入现有权限和新权限。 仅传入新权限会覆盖并删除尚未同意的现有权限。

分配 权限不会自动向他们授予应用。 你仍必须使用 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"
                }
            ]
        }
    ]
}

创建应用角色

在应用程序对象上创建应用角色

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

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 引用服务主体。 或者,可以使用模式 ../servicePrincipals/{bject ID}/owners/$ref中的对象 ID 来引用它。 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
    }
}

为应用配置受信任的证书颁发机构

可以将租户中应用的证书凭据使用情况限制为仅受信任的证书颁发机构颁发的证书。 向应用添加证书时会强制实施此策略,除非轮换现有证书,否则不会影响现有证书。 当应用尝试轮换其证书凭据时,它会经历策略评估,以确保添加的凭据符合受信任的证书颁发机构限制。

步骤 1:创建信任证书链

最低特权委派权限: AppCertTrustConfiguration.Read.All 最低特权Microsoft Entra 角色: Application Administrator

POST https://graph.microsoft.com/beta/certificateAuthorities/certificateBasedApplicationConfigurations

{
    "displayName": "Trusted Certificate Chain of Trust for Contoso",
    "description": "The Trusted Certificate Chain of Trust containing a certificate chain used by app policy, to only allow application certificates from selected issuer.",
    "trustedCertificateAuthorities": [
        {
            "isRootAuthority": true,
            "certificate": "MIIFVjCCAz6gAwIBAgIQJdrL...UyNDIyNTcwM1owPDE …="
        },
        {
            "isRootAuthority": false,
            "certificate": QAAAAAAWjABAQsFADA8M...UyNDIyNTcwM1o …="
        }
    ]
}

请求会返回 200 OK 响应对象。 响应包括信任对象的证书链的 ID。 假设 ID 为 eec5ba11-2fc0-4113-83a2-ed986ed13743

步骤 2:将证书信任链分配给应用程序管理策略

以下示例设置一个策略,以确保只能将上一步中定义的中间证书颁发机构颁发的证书添加到租户中的应用。 applicationRestrictions>keyCredentials 对象使用 值 trustedCertificateAuthority定义一个 restrictionType,该值引用创建的 ID。 由于此策略应用于默认租户级应用管理策略,因此将对租户中创建的所有应用强制实施此策略,并拒绝尝试添加不合规证书作为应用的证书凭据的一部分。

此策略确保只能将来自指定中间证书颁发机构的证书添加到应用。 applicationRestrictions>keyCredentials 对象将 restrictionType 设置为 trustedCertificateAuthority,引用创建的 ID。 此策略适用于租户中的所有应用,拒绝任何不符合要求的证书。

最低特权委派权限: Policy.Read.ApplicationConfiguration 最低特权Microsoft Entra 角色: Security Administrator

PATCH https://graph.microsoft.com/v1.0/policies/defaultAppManagementPolicy

{
  "id": "d015220e-9789-4e8e-bbcc-270fe419229d",
  "description": "Lorem ipsum",
  "displayName": "Credential management policy",
  "isEnabled": true,
  "applicationRestrictions": {
    "passwordCredentials": [
      {
        "restrictionType": "passwordLifetime",
        "maxLifetime": "P14D",
        "restrictForAppsCreatedAfterDateTime": "2020-01-01T07:00:00Z"
      }
    ],
    "keyCredentials": [
      {
        "restrictionType": "certificateLifetime",
        "restrictForAppsCreatedAfterDateTime": "2020-01-01T10:37:00Z",
        "maxLifetime": "P90D"
      },
      {
        "restrictionType": "trustedCertificateAuthority",
        "certificateBasedApplicationConfigurationIds": [
          "eec5ba11-2fc0-4113-83a2-ed986ed13743"
        ],
        "restrictForAppsCreatedAfterDateTime": "2019-10-19T10:37:00Z"
      }
    ]
  }
}