了解应用部件清单（Microsoft Graph 格式）

项目
01/15/2025

应用程序清单包含 Microsoft 标识平台中应用注册的所有特性及其值。

Microsoft Graph 应用部件清单是表示应用注册的 JSON 对象。它还被称为 Microsoft Graph 应用程序资源类型或 Microsoft Graph 应用对象（应用程序对象）。它包含应用注册的所有特性及其值。

使用 Microsoft Graph Get Application 方法收到的应用程序对象与在 Microsoft Entra 管理中心的应用注册清单页中看到的 JSON 对象相同。

注意

使用个人 Microsoft 帐户（MSA 帐户）注册的应用将继续在 Microsoft Entra 管理中心显示 Azure AD Graph 格式的应用部件清单，直至另行通知。了解更多信息，请参阅 Microsoft Entra 应用部件清单（Azure AD Graph 格式）。

配置 Microsoft Graph 应用部件清单

若要以编程方式配置 Microsoft Graph 应用部件清单，则可以使用 Microsoft Graph API 或 Microsoft Graph PowerShell SDK。

还可以通过 Microsoft Entra 管理中心配置应用部件清单。大多数特性都可以在应用注册中通过 UI 元素进行配置。但是，需要通过直接在清单页中编辑应用部件清单来配置某些特性。

在 Microsoft Entra 管理中心配置应用部件清单

配置 Microsoft Graph 应用部件清单：

至少以应用程序开发人员的身份登录到 Microsoft Entra 管理中心。
浏览到“标识”>“应用程序”>“应用注册”。
选择要配置的应用。
在应用的“概览”页中，选择“清单”部分。此时会打开一个基于 Web 的清单编辑器，可在其中编辑清单。（可选）可以选择“下载”以在本地编辑清单，然后使用“上传”将清单重新应用于应用程序。

清单参考

本部分介绍 Microsoft Graph 应用部件清单中的特性。

ID 属性

键	值类型
id	字符串

此属性在 Microsoft Entra 管理中心称为对象 ID。它是目录中应用程序对象的唯一标识符。

此 ID 不是用于在任何协议事务中标识应用的标识符。用于引用目录查询中的对象。

它是不可为 null 且只读的特性。

示例：

    "id": "f7f9acfc-ae0c-4d6c-b489-0a81dc1652dd",

appId 属性

键	值类型
appId	字符串

此属性在 Microsoft Entra 管理中心称为应用程序（客户端）ID。它是目录中应用程序对象的唯一标识符。

此 ID 是用于在任何协议事务中标识应用的标识符。

它是不可为 null 且只读的特性。

示例：

"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",

addIns 属性

键	值类型
addIns	集合

定义自定义行为，供消耗型服务在特定上下文中调用应用。例如，呈现文件流的应用程序可以设置其“FileHandler”功能的 addIns 属性。 Microsoft 365 等服务可以通过此参数在用户正在处理的文档上下文中调用该应用程序。

示例：

    "addIns": [
       {
        "id": "968A844F-7A47-430C-9163-07AE7C31D407",
        "type":" FileHandler",
        "properties": [
           {
              "key": "version",
              "value": "2"
           }
        ]
       }
    ],

appRoles

键	值类型
appRoles	集合

指定应用可以声明的角色集合。可将这些角色分配给用户、组或服务主体。有关更多示例和信息，请参阅在应用程序中添加应用角色并在令牌中接收它们。

示例：

    "appRoles": [
        {
           "allowedMemberTypes": [
               "User"
           ],
           "description": "Read-only access to device information",
           "displayName": "Read Only",
           "id": "00001111-aaaa-2222-bbbb-3333cccc4444",
           "isEnabled": true,
           "value": "ReadOnly"
        }
    ],

groupMembershipClaims

键	值类型
groupMembershipClaims	字符串

配置应用所需的用户访问令牌或 OAuth 2.0 访问令牌中颁发的 groups 声明。若要设置此属性，请使用以下有效的字符串值之一：

None
SecurityGroup（适用于安全组和 Microsoft Entra 角色）
ApplicationGroup（此选项仅包括分配给应用程序的组）
DirectoryRole（获取用户所属的 Microsoft Entra 目录角色）
All（它会获取已登录用户所属的所有安全组、通讯组和 Microsoft Entra 目录角色）。

示例：

    "groupMembershipClaims": "SecurityGroup",

optionalClaims 属性

键	值类型
optionalClaims	字符串

此特定应用的安全令牌服务在令牌中返回的可选声明。

同时支持个人帐户和 Microsoft Entra ID 的应用无法使用可选声明。但是，使用 v2.0 终结点仅为 Microsoft Entra ID 注册的应用可以获取它们在清单中请求的可选声明。有关详细信息，请参阅可选声明。

示例：

    "optionalClaims":{
"idToken": [{"@odata.type": "microsoft.graph.optionalClaim"}],
"accessToken": [{"@odata.type": "microsoft.graph.optionalClaim"}],
"saml2Token": [{"@odata.type": "microsoft.graph.optionalClaim"}]
}

identifierUris 属性

键	值类型
identifierUris	String Array

用户定义的 URI，用于在 Microsoft Entra 租户或已验证的客户拥有的域中唯一标识 Web 应用。当应用程序用作资源应用时，identifierUri 值用于唯一标识和访问资源。

支持以下基于 API 和 HTTP 方案的应用程序 ID URI 格式。替换表后列表中描述的占位符值。

支持的应用程序 ID URI 格式	示例应用 ID URI
api://<appId>	api://00001111-aaaa-2222-bbbb-3333cccc4444
api://<tenantId>/<appId>	api://aaaabbbb-0000-cccc-1111-dddd2222eeee/00001111-aaaa-2222-bbbb-3333cccc4444
api://<tenantId>/<string>	api://aaaabbbb-0000-cccc-1111-dddd2222eeee/api
api://<string>/<appId>	api://productapi/00001111-aaaa-2222-bbbb-3333cccc4444
https://<tenantInitialDomain>.onmicrosoft.com/<string>	`https://contoso.onmicrosoft.com/productsapi`
https://<verifiedCustomDomain>/<string>	`https://contoso.com/productsapi`
https://<string>.<verifiedCustomDomain>	`https://product.contoso.com`
https://<string>.<verifiedCustomDomain>/<string>	`https://product.contoso.com/productsapi`

<appId> - 应用程序对象的应用程序标识符 (appId) 属性。
<string> - 主机或 API 路径段的字符串值。
<tenantId> - Azure 生成的 GUID，用于表示 Azure 中的租户。
<tenantInitialDomain> - tenantInitialDomain<.onmicrosoft.com，其中 >tenantInitialDomain 是租户创建者在创建租户时指定的初始域名<>。
<verifiedCustomDomain> - 为 Microsoft Entra 租户配置的已验证的自定义域。

注意

如果使用 api:// 方案，则直接在“api://”之后添加一个字符串值。例如，api://<string>。该字符串值可以是 GUID 或任意字符串。如果添加 GUID 值，值必须与应用 ID 或租户 ID 匹配。应用程序 ID URI 值对于租户必须是唯一的。如果将 api://<tenantId> 添加为应用程序 ID URI，其他人将无法在任何其他应用程序中使用该 URI。建议改用 api://<appId> 或 HTTP 方案。

重要

应用程序 ID URI 值不能以斜杠“/”字符结尾。

示例：

    "identifierUris": "https://contoso.onmicrosoft.com/fc4d2d73-d05a-4a9b-85a8-4f2b3a5f38ed",

keyCredentials 属性

键	值类型
keyCredentials	集合

包含对应用所分配的凭据、基于字符串的共享机密和 X.509 证书的引用。在请求访问令牌时，可使用这些凭据（如果应用充当客户端而不是资源）。

示例：

    "keyCredentials": [
        {
           "customKeyIdentifier":null,
           "endDateTime":"2018-09-13T00:00:00Z",
           "keyId":"<guid>",
           "startDateTime":"2017-09-12T00:00:00Z",
           "type":"AsymmetricX509Cert",
           "usage":"Verify",
           "value":null
        }
    ],

displayName 属性

键	值类型
displayName	字符串

应用的显示名称。

示例：

" displayName": "MyRegisteredApp",

oauth2RequiredPostResponse 属性

键	值类型
oauth2RequiredPostResponse	布尔

指定在 OAuth 2.0 令牌请求中，Microsoft Entra ID 是否允许与 GET 请求相反的 POST 请求。默认值为 false，即指定只允许 GET 请求。

示例：

    "oauth2RequirePostResponse": false,

parentalControlSettings 属性

键	值类型
parentalControlSettings	字符串

countriesBlockedForMinors 指定禁止未成年人使用该应用的国家/地区。
legalAgeGroupRule 指定适用于应用用户的法定年龄组规则。可设置为 Allow、RequireConsentForPrivacyServices、RequireConsentForMinors、RequireConsentForKids 或 BlockMinors。

示例：

    "parentalControlSettings": {
        "countriesBlockedForMinors": [],
        "legalAgeGroupRule": "Allow"
    },

passwordCredentials 属性

键	值类型
passwordCredentials	集合

请参阅 keyCredentials 属性的说明。

示例：

    "passwordCredentials": [
      {
        "customKeyIdentifier": null,
        "displayName": "Generated by App Service",
        "endDateTime": "2022-10-19T17:59:59.6521653Z",
        "hint": "Nsn",
        "keyId": "<guid>",
        "secretText": null,        
        "startDateTime":"2022-10-19T17:59:59.6521653Z"
      }
    ],

publisherDomain 属性

键	值类型
publisherDomain	字符串

应用程序的已验证发布者域。只读。若要编辑应用注册的发布者域，请按照配置应用的发布者域中列出的步骤操作。

示例：

"publisherDomain": "{tenant}.onmicrosoft.com",

requiredResourceAccess 属性

键	值类型
requiredResourceAccess	集合

requiredResourceAccess 可以使用动态许可来驱动管理员许可体验，并驱动使用静态许可的用户的用户许可体验。但是，此参数无法驱动常规性的用户许可体验。

resourceAppId 是应用需要访问的资源的唯一标识符。此值应等于目标资源应用中声明的 appId。
resourceAccess 是一个数组，列出应用在指定的资源中所需的 OAuth2.0 权限范围和应用角色。包含指定的资源的 id 和 type 值。

示例：

    "requiredResourceAccess": [
        {
            "resourceAppId": "00000002-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
                    "type": "Scope"
                }
            ]
        }
    ],

samlMetadataUrl 属性

键	值类型
samlMetadataUrl	字符串

应用的 SAML 元数据 URL。

示例：

    "samlMetadataUrl": "https://MyRegisteredAppSAMLMetadata",

signInAudience 属性

键	值类型
signInAudience	字符串

指定当前应用程序支持哪些 Microsoft 帐户。支持的值是：

AzureADMyOrg - 在我的组织的 Microsoft Entra 租户（例如单租户）中具有 Microsoft 工作或学校帐户的用户
AzureADMultipleOrgs - 在任何组织的 Microsoft Entra 租户（例如多租户）中具有 Microsoft 工作或学校帐户的用户
AzureADandPersonalMicrosoftAccount - 在任何组织的 Microsoft Entra 租户中具有个人 Microsoft 帐户、工作或学校帐户的用户
PersonalMicrosoftAccount - 用于登录 Xbox 和 Skype 等服务的个人帐户。

示例：

    "signInAudience": "AzureADandPersonalMicrosoftAccount",

tags 属性

键	值类型
标记	String Array

可用来对应用程序进行分类和标识的自定义字符串。

单个标记必须介于 1 到 256 个字符之间（含）。不允许使用空格或重复标记。可以添加的标记数没有特定的限制，但受常规清单大小限制的约束。

示例：

    "tags": [
       "ProductionApp"
    ],

isFallbackPublicClient 特性

键	值类型
isFallbackPublicClient	布尔

将回退应用程序类型指定为公共客户端，例如在移动设备上运行的已安装应用程序。此特性的默认值为 false，这意味着，回退应用程序类型为机密客户端，例如 Web 应用。在某些情况下，Microsoft Entra ID 无法确定客户端应用程序类型。例如，配置时未指定重定向 URI 的 ROPC 流。在这些情况下，Microsoft Entra ID 会根据此属性的值解释应用程序类型。

示例：

"isFallbackPublicClient ": "false",

info 特性

键	值类型
info	informationalUrl

指定应用程序的基本配置文件信息，包括应用的营销、支持、服务条款、隐私声明和徽标 URL。

请注意：

“logoUrl”是只读属性。无法在应用部件清单中编辑它。导航到所需应用注册中的“品牌和属性”页面，然后使用“上传新徽标”来上传新徽标。
服务条款和隐私声明通过用户同意体验展示给用户。有关详细信息，请参阅如何：为已注册的 Microsoft Entra 应用添加服务条款和隐私声明。

示例：

Info: { 
"termsOfService": "https://MyRegisteredApp/termsofservice",
"support": "https://MyRegisteredApp/support",
"privacy": "https://MyRegisteredApp/privacystatement",
"marketing": "https://MyRegisteredApp/marketing"
"logoUrl": "https://MyRegisteredApp/logoUrl",
}

api 特性

键	值类型
api	apiApplication 资源类型

指定实现 Web API 的应用程序的设置。它包括五个属性：

properties	类型	描述
acceptMappedClaims	布尔	如果设置为 true，则允许应用程序使用声明映射，而无需指定自定义的签名密钥。接收令牌的应用程序依赖于这样一个事实：声明值是由 Microsoft Entra ID 权威颁发的，不能篡改。但当你通过声明映射策略修改令牌内容时，上述事实可能不再适用。应用程序必须明确承认令牌已被声明映射策略的创建者修改，才能防止被恶意参与者创建的声明映射策略破坏。警告：不要将 multitenant 应用的 acceptMappedClaims 属性设置为 true，这会让恶意参与者为应用创建声明映射策略。
knownClientApplications	collection	如果解决方案包含两个部分：客户端应用和自定义 Web API 应用，则该值用于捆绑许可。如果将客户端应用的 appID 设置为此值，则用户仅向客户端应用授予同意一次。 Microsoft Entra ID 知道，向客户端授予同意意味着向 Web API 隐式授予同意，并同时自动为这两个 API 预配服务主体。客户端和 Web API 应用都必须在同一个租户中注册。
oauth2PermissionScopes	permissionScope 集合	由此应用程序注册表示的 Web API 公开的委托权限的定义。这些委派权限可由客户端应用程序请求，并且可在同意期间由用户或管理员授予。委派权限有时称为 OAuth 2.0 范围。
preAuthorizedApplications	preAuthorizedApplication 集合	列出使用指定委派权限预授权的客户端应用程序，以访问此应用程序的 API。用户无需同意任何预授权的应用程序（针对指定的权限）。但是，preAuthorizedApplications 中未列出的任何其他权限（例如，通过增量同意请求的）都需要用户同意。
requestedAccessTokenVersion	Int32	指定此资源所需的访问令牌版本。这会更改独立于用于请求访问令牌的终结点或客户端生成的 JWT 的版本和格式。使用的端点 v1.0 或 v2.0 由客户端选择，仅影响 id_tokens 的版本。资源需要显式配置 requestedAccessTokenVersion 以指示支持的访问令牌格式。 requestedAccessTokenVersion 可能的值为 1、2 或 null。如果值为 null，则默认为 1，这对应于 v1.0 终结点。如果应用程序的 signInAudience 配置为 AzureADandPersonalMicrosoftAccount 或 PersonalMicrosoftAccount，则此属性的值必须为 2。

示例：

Api:{
    "acceptMappedClaims": true,
    "knownClientApplications": ["f7f9acfc-ae0c-4d6c-b489-0a81dc1652dd"],
    "oauth2PermissionScopes": [
        {
        "adminConsentDescription": "Allow the app to access resources on behalf of the signed-in user.",
        "adminConsentDisplayName": "Access resource1",
        "id": "<guid>",
        "isEnabled": true,
        "type": "User",
        "userConsentDescription": "Allow the app to access resource1 on your behalf.",
        "userConsentDisplayName": "Access resources",
        "value": "user_impersonation"
        }
    ],
    "preAuthorizedApplications": [{
        "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "permissionIds": [
        "8748f7db-21fe-4c83-8ab5-53033933c8f1"
        ]
    }],
    "requestedAccessTokenVersion": 2
}

Web 特性

键	值类型
web	webApplication 资源类型

指定 Web 应用程序的设置。它包括四个属性。

properties	类型	描述
homePageUrl	字符串	应用程序的主页或登陆页。
implicitGrantSettings	implicitGrantSettings	指定此 Web 应用程序能否使用 OAuth 2.0 隐式流来请求令牌。
logoutUrl	字符串	指定由 Microsoft 的授权服务使用，通过前通道、后通道或 SAML 退出登录协议使用户退出登录的 URL。
redirectUris	字符串集合	指定发送用户令牌以用于登录的 URL，或在 Web 平台中发送 OAuth 2.0 授权代码和访问令牌的重定向 URI。

示例：

web: {
    "homePageUrl": "String",
    "implicitGrantSettings": {
    "enableIdTokenIssuance": "Boolean",
    "enableAccessTokenIssuance": "Boolean"}
    "logoutUrl": "String",
    "redirectUris": ["String"]
}

spa 特性

键	值类型
温泉疗养中心	spaApplication 资源类型

指定单页应用程序的设置，包括用于授权代码和访问令牌的退出登录 URL 和重定向 URI。

properties	类型	描述
redirectUris	字符串集合	指定发送用户令牌以用于登录的 URL，或发送 OAuth 2.0 授权代码和访问令牌的重定向 URI。

示例：

spa: {
    "redirectUris": ["String"]
}

publicClient 属性

键	值类型
publicClient	publicClientApplication 资源类型

指定非 Web 应用或非 Web API 的设置（例如 iOS、Android、移动或其他公共客户端，例如在桌面设备上运行的已安装应用程序）。

properties	类型	描述
redirectUris	字符串集合	指定发送用户令牌以用于登录的 URL，或发送 OAuth 2.0 授权代码和访问令牌的重定向 URI。

示例：

publicClient: {
"redirectUris": ["String"]
}

常见问题

清单限制

应用程序清单包含多个称为集合的属性，例如 appRoles、keyCredentials、knownClientApplications、identifierUris、redirectUris、requiredResourceAccess 和 oauth2PermissionScopes。在任何应用程序的完整应用程序清单中，所有合并集合中的条目总数的上限为 1200。如果以前在应用程序清单中指定了 100 个 appRoles，则在构成该清单的其他所有合并集合中，只剩下 1,100 个条目可供使用。

注意

如果你尝试在应用程序清单中添加超过 1200 个条目，则可能会显示错误“未能更新应用程序 xxxxxx 。错误详细信息: 清单的大小已超出其限制。请减少值数，然后重试请求。”

从 Azure AD Graph 格式迁移到 Microsoft Graph 格式的疑难解答清单

以 Azure AD Graph 格式上传以前下载的应用部件清单时，可能会收到以下错误：

未能更新 {app name} 应用程序。错误详细信息：无效属性“{property name}”。

这可能是由于从 Azure AD Graph 到 Microsoft Graph 应用部件清单的迁移导致的。首先，应检查应用部件清单是否属于 Azure AD Graph 格式。如果是，则应将应用部件清单转换为 Microsoft Graph 格式。

找不到 trustedCertificateSubjects 属性

trustedCertificateSubjects 属性是 Microsoft 的内部属性。 Microsoft Entra 管理中心显示 Microsoft Graph 应用清单版本 1.0，trustedCertificateSubjects 属性仅以应用清单的 beta 版本（Microsoft Graph 格式）显示。继续使用Microsoft Entra 管理中心中的应用清单（Azure AD Graph 格式）编辑此属性。

错误：找不到应用程序。如果应用程序刚刚创建，请等待几分钟并刷新页面。**

如果应用程序刚刚创建，则可能收到此错误，因为已在 Microsoft Graph 应用清单中添加了无效属性。请查看 Azure AD Graph 和 Microsoft Graph 格式之间的属性差异，并查看是否已添加在门户中显示的 Microsoft Graph 格式 v1.0 版本中不支持的属性。

后续步骤

有关应用的应用程序与服务主体对象之间的关系的详细信息，请参阅 Microsoft Entra ID 中的应用程序和服务主体对象。

参阅 Microsoft 标识平台开发人员词汇表，了解某些 Microsoft 标识平台开发人员核心概念的定义。

使用以下评论部分提供反馈，帮助我们改进和组织内容。

通过