Microsoft Entra 应用部件清单（Azure AD Graph 格式）

Artículo
10/06/2024

应用程序清单包含 Microsoft 标识平台中的某个应用程序对象的所有属性的定义。它还充当用于更新应用程序对象的机制。有关应用程序实体及其架构的详细信息，请参阅图形 API 应用程序实体文档。

可以通过 Microsoft Entra 管理中心配置应用属性，或使用 Microsoft Graph API 或 Microsoft Graph PowerShell SDK 以编程方式配置。但是，在某些情况下，需要编辑应用清单来配置应用的属性。这些方案包括：

如果已将应用注册为 Microsoft Entra 多租户，则无法在 UI 中更改支持的 Microsoft 帐户。而是必须使用应用程序清单编辑器来更改支持的帐户类型。
若要定义你的应用支持的权限和角色，则必须修改应用程序清单。

配置应用清单

若要配置应用程序清单，请执行以下操作：

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

清单参考

本部分介绍在应用程序清单中找到的属性。

ID 属性

键	值类型
id	字符串

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

示例：

    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",

acceptMappedClaims 属性

密钥	值类型
acceptMappedClaims	可为空的布尔值

如 apiApplication 资源类型中所述，这样可以让应用程序使用声明映射，而无需指定自定义签名密钥。接收令牌的应用程序依赖于这样一个事实：即声明值是由 Microsoft Entra ID 权威颁发的，不能篡改。但当你通过声明映射策略修改令牌内容时，上述事实可能不再适用。应用程序必须明确承认令牌已被声明映射策略的创建者修改，才能防止被恶意参与者创建的声明映射策略破坏。

警告

对于多租户应用，请勿将 acceptMappedClaims 属性设置为 true，这可能会允许恶意参与者为应用创建声明映射策略。

示例：

    "acceptMappedClaims": true,

accessTokenAcceptedVersion 属性

密钥	值类型
accessTokenAcceptedVersion	可为 Null 的 Int32

指定资源所需的访问令牌版本。此参数会更改独立于用于请求访问令牌的终结点或客户端生成的 JWT 的版本和格式。

使用的端点 v1.0 或 v2.0 由客户端选择，仅影响 id_tokens 的版本。资源需要显式配置 accesstokenAcceptedVersion 以指示受支持的访问令牌格式。

accesstokenAcceptedVersion 的可能值为 1、2 或为 null。如果值为 null，则此参数默认为 1，这对应于 v1.0 终结点。

addIns 属性

密钥	值类型
addIns	集合

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

示例：

    "addIns": [
       {
        "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "type":" FileHandler",
        "properties": [
           {
              "key": "version",
              "value": "2"
           }
        ]
       }
    ],

allowPublicClient 属性

密钥	值类型
allowPublicClient	Boolean

指定回退应用程序类型。默认情况下，Microsoft Entra ID 基于 replyUrlsWithType 推断应用程序类型。某些情况下，Microsoft Entra ID 无法确定客户端应用类型。例如，这样的一种情况是 ROPC 流，其中发生了没有 URL 重定向的 HTTP 请求。在这种情况下，Microsoft Entra ID 将基于此属性的值解释应用程序类型。如果此值设置为 true，则回退应用程序类型设置为公共客户端，例如在移动设备上运行的已安装应用。默认值为 false，这意味着，回退应用程序类型为机密客户端，例如 Web 应用。

示例：

    "allowPublicClient": false,

appId 属性

密钥	值类型
appId	字符串

指定由 Microsoft Entra ID 分配给应用的应用唯一标识符。

示例：

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

appRoles 属性

键	值类型
appRoles	集合

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

示例：

    "appRoles": [
        {
           "allowedMemberTypes": [
               "User"
           ],
           "description": "Read-only access to device information",
           "displayName": "Read Only",
           "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
           "isEnabled": true,
           "value": "ReadOnly"
        }
    ],

errorUrl 属性

密钥	值类型
errorUrl	字符串

不支持。

groupMembershipClaims 属性

密钥	值类型
groupMembershipClaims	字符串

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

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

示例：

    "groupMembershipClaims": "SecurityGroup",

optionalClaims 属性

密钥	值类型
optionalClaims	字符串

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

使用 v2.0 终结点仅为 Microsoft Entra 注册的应用可以获取它们在清单中请求的可选声明。有关详细信息，请参阅可选声明。

示例：

    "optionalClaims": null,

identifierUris 属性

密钥	值类型
identifierUris	String Array

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

支持以下基于 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>.partner.onmschina.cn/<string>	`https://contoso.partner.onmschina.cn/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 生成的用于表示 Azure 中的租户的 GUID。
<tenantInitialDomain> - <tenantInitialDomain>.partner.onmschina.cn，其中 <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.partner.onmschina.cn/00001111-aaaa-2222-bbbb-3333cccc4444",

informationalUrls 属性

密钥	值类型
informationalUrls	字符串

指定应用服务条款和隐私声明的链接。服务条款和隐私声明通过用户同意体验展示给用户。有关详细信息，请参阅如何：为已注册的 Microsoft Entra 应用添加服务条款和隐私声明。

示例：

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

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
        }
    ],

knownClientApplications 属性

密钥	值类型
knownClientApplications	String Array

如果解决方案包含两个部分：客户端应用和自定义 Web API 应用，则该值用于捆绑许可。如果在此值中输入客户端应用的 appID，则用户只需许可该客户端应用一次。 Microsoft Entra ID 将知道，许可客户端意味着隐式许可 Web API。它会同时为客户端和 Web API 自动预配服务主体。客户端和 Web API 应用都必须在同一个租户中注册。

示例：

    "knownClientApplications": ["00001111-aaaa-2222-bbbb-3333cccc4444"],

logoUrl 属性

密钥	值类型
logoUrl	字符串

只读值，指向已上传的徽标的 CDN URL。

示例：

    "logoUrl": "https://MyRegisteredAppLogo",

logoutUrl 属性

密钥	值类型
logoutUrl	字符串

用于注销应用的 URL。

示例：

    "logoutUrl": "https://MyRegisteredAppLogout",

name 属性

密钥	值类型
name	字符串

应用的显示名称。

示例：

    "name": "MyRegisteredApp",

oauth2AllowImplicitFlow 属性

密钥	值类型
oauth2AllowImplicitFlow	Boolean

指定此 Web 应用是否可以请求 OAuth2.0 隐式流访问令牌。默认值为 false。此标志用于基于浏览器的应用，例如 JavaScript 单页应用。若要了解详细信息，请在目录中输入 OAuth 2.0 implicit grant flow，并查看有关隐式流的主题。但是，我们不建议在 SPA 中使用隐式授权，而是建议在 PKCE 中使用授权代码流。

示例：

    "oauth2AllowImplicitFlow": false,

oauth2AllowIdTokenImplicitFlow 属性

密钥	值类型
oauth2AllowIdTokenImplicitFlow	Boolean

指定此 Web 应用是否可以请求 OAuth2.0 隐式流 ID 令牌。默认值为 false。此标志用于基于浏览器的应用，例如 JavaScript 单页应用。但是，我们不建议在 SPA 中使用隐式授权，而是建议在 PKCE 中使用授权代码流。

示例：

    "oauth2AllowIdTokenImplicitFlow": false,

oauth2Permissions 属性

密钥	值类型
oauth2Permissions	集合

指定 Web API（资源）应用向客户端应用公开的 OAuth 2.0 权限范围集合。在许可期间，可将这些权限范围授予客户端应用。

示例：

    "oauth2Permissions": [
       {
          "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"
        }
    ],

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"
      }
    ],

preAuthorizedApplications 属性

密钥	值类型
preAuthorizedApplications	集合

列出了应用程序和针对隐式同意的所请求权限。要求管理员同意应用程序。 preAuthorizedApplications 不要求用户同意所请求的权限。 preAuthorizedApplications 中列出的权限不要求用户同意。但是，preAuthorizedApplications 中未列出的任何其他所请求权限都要求用户同意。

示例：

    "preAuthorizedApplications": [
       {
          "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
          "permissionIds": [
             "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
            ]
        }
    ],

publisherDomain 属性

密钥	值类型
publisherDomain	字符串

应用程序的已验证发布者域。只读。

示例：

    "publisherDomain": "{tenant}.partner.onmschina.cn",

replyUrlsWithType 属性

密钥	值类型
replyUrlsWithType	集合

此多值属性保存 Microsoft Entra ID 在返回令牌时接受用作目标的已注册 redirect_uri 值列表。每个 URI 值都应当包含一个关联的应用类型值。支持的类型值为：

Web
InstalledClient
Spa

若要了解详细信息，请参阅 replyUrl 限制和局限性。

示例：

    "replyUrlsWithType": [
       {
          "url": "https://localhost:4400/services/office365/redirectTarget.html",
          "type": "InstalledClient"
       }
    ],

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",

signInUrl 属性

密钥	值类型
signInUrl	字符串

指定应用主页的 URL。

示例：

    "signInUrl": "https://MyRegisteredApp",

signInAudience 属性

密钥	值类型
signInAudience	字符串

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

AzureADMyOrg - 在我的组织的 Microsoft Entra 租户（例如单租户）中具有 Microsoft 工作或学校帐户的用户
AzureADMultipleOrgs - 在任何组织的 Microsoft Entra 租户（例如多租户）中具有 Microsoft 工作或学校帐户的用户

示例：

    "signInAudience": "AzureADMyOrg",

tags 属性

密钥	值类型
标记	String Array

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

示例：

    "tags": [
       "ProductionApp"
    ],

常见问题

清单限制

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

注意

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

不支持的属性

应用程序清单表示 Microsoft Entra ID 中基础应用程序模型的架构。随着底层架构的不断演进，清单编辑器会不时地更新，以反映新的架构。因此，你可能会在应用程序清单中看到新的属性。在极少数情况下，可能会注意现有属性中出现了语法或语义的更改，或者以前存在的某个属性不再受支持。例如，你会在应用注册中看到新的属性，而这些属性在应用注册（旧版）体验中使用不同的名称。

应用注册(旧版)	应用注册
`availableToOtherTenants`	`signInAudience`
`displayName`	`name`
`errorUrl`	-
`homepage`	`signInUrl`
`objectId`	`Id`
`publicClient`	`allowPublicClient`
`replyUrls`	`replyUrlsWithType`

有关这些属性的说明，请参阅清单参考部分。

尝试上传之前下载的清单时，可能会出现以下错误之一。此错误很可能是因为清单编辑器现在支持较新版本的架构，该架构与你尝试上传的清单不匹配。

“无法更新 xxxxxx 应用程序。错误详细信息：无效的对象标识符 'undefined'。 []。"
“无法更新 xxxxxx 应用程序。错误详细信息：指定的一个或多个属性值无效。 []。"
“无法更新 xxxxxx 应用程序。错误详细信息：不允许在此 api 版本中设置要更新的 availableToOtherTenants。 []。"
“无法更新 xxxxxx 应用程序。错误详细信息：不允许对此应用程序的 replyUrls 属性进行更新。请改用 'replyUrlsWithType' 属性。 []。"
“无法更新 xxxxxx 应用程序。错误详细信息：找到了没有类型名称的值，并且没有可用的预期类型。如果指定该模型，则有效负载中的每个值都必须具有可在有效负载中指定、显式由调用方调用或隐式从父值推断的类型。 []"

显示这些错误之一时，建议执行以下操作：

在清单编辑器中逐个编辑属性，而不是上传之前下载的清单。使用清单参考表来了解旧属性和新属性的语法与语义，以便能够成功编辑所需的属性。
如果工作流要求在源存储库中保存清单供以后使用，我们建议使用应用注册体验中显示的清单来变基存储库中保存的清单。

后续步骤

有关应用的应用程序与服务主体对象之间的关系的详细信息，请参阅 Microsoft Entra ID 中的应用程序和服务主体对象。
参阅 Microsoft 标识平台开发人员词汇表，了解某些 Microsoft 标识平台开发人员核心概念的定义。

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

Compartir a través de