Azure Active Directory 应用清单Azure Active Directory app manifest

应用程序清单包含 Microsoft 标识平台中的某个应用程序对象的所有属性的定义。The application manifest contains a definition of all the attributes of an application object in the Microsoft identity platform. 它还充当用于更新应用程序对象的机制。It also serves as a mechanism for updating the application object. 有关应用程序实体及其架构的详细信息,请参阅图形 API 应用程序实体文档For more info on the Application entity and its schema, see the Graph API Application entity documentation.

可以通过 Azure 门户或者使用 REST APIPowerShell 以编程方式配置应用的属性。You can configure an app's attributes through the Azure portal or programmatically using REST API or PowerShell. 但是,在某些情况下,需要编辑应用清单来配置应用的属性。However, there are some scenarios where you'll need to edit the app manifest to configure an app's attribute. 这些方案包括:These scenarios include:

  • 如果已将应用注册为 Azure AD 多租户,则无法在 UI 中更改支持的 Microsoft 帐户。If you registered the app as Azure AD multi-tenant, you can't change the supported Microsoft accounts in the UI. 而是必须使用应用程序清单编辑器来更改支持的帐户类型。Instead, you must use the application manifest editor to change the supported account type.
  • 如果需要定义你的应用支持的权限和角色,则必须修改应用程序清单。If you need to define permissions and roles that your app supports, you must modify the application manifest.

配置应用清单Configure the app manifest

若要配置应用程序清单,请执行以下操作:To configure the application manifest:

  1. 登录到 Azure 门户Sign in the Azure portal.
  2. 选择“Azure Active Directory”服务 ,然后选择“应用注册”。 Select the Azure Active Directory service, and then select App registrations.
  3. 选择要配置的应用。Select the app you want to configure.
  4. 在应用的“概览”页中,选择“清单”部分。 From the app's Overview page, select the Manifest section. 此时会打开一个基于 Web 的清单编辑器,可在其中编辑门户中的清单。A web-based manifest editor opens, allowing you to edit the manifest within the portal. (可选)可以选择“下载”以在本地编辑清单,然后使用“上传”将清单重新应用于应用程序。 Optionally, you can select Download to edit the manifest locally, and then use Upload to reapply it to your application.

清单参考Manifest reference

Note

如果看不到“说明”后的“示例值”列,请最大化浏览器窗口并滚动/轻扫,直至看到“示例值”列。 If you can't see the Example value column after the Description, maximize your browser window and scroll/swipe until you see the Example value column.

Key 值类型Value type 说明Description 示例值Example value
accessTokenAcceptedVersion 可为 Null 的 Int32Nullable Int32 指定资源所需的访问令牌版本。Specifies the access token version expected by the resource. 这会更改独立于用于请求访问令牌的终结点或客户端生成的 JWT 的版本和格式。This changes the version and format of the JWT produced independent of the endpoint or client used to request the access token.

使用的端点 v1.0 或 v2.0 由客户端选择,仅影响 id_tokens 的版本。The endpoint used, v1.0 or v2.0, is chosen by the client and only impacts the version of id_tokens. 资源需要显式配置 accesstokenAcceptedVersion 以指示受支持的访问令牌格式。Resources need to explicitly configure accesstokenAcceptedVersion to indicate the supported access token format.

accesstokenAcceptedVersion 的可能值为 1、2 或为 null。Possible values for accesstokenAcceptedVersion are 1, 2, or null. 如果值为 null,则默认为 1,这对应于 v1.0 终结点。If the value is null, this defaults to 1, which corresponds to the v1.0 endpoint.
2
addIns 集合Collection 定义使用方服务在特定上下文中调用某个应用时可以使用的自定义行为。Defines custom behavior that a consuming service can use to call an app in specific contexts. 例如,呈现文件流的应用程序可以设置其“FileHandler”功能的 addIns 属性。For example, applications that can render file streams may set the addIns property for its "FileHandler" functionality. 这样,Office 365 等服务便可以在用户正在处理的文档上下文中调用该应用程序。This will let services like Office 365 call the application in the context of a document the user is working on. {
   "id":"968A844F-7A47-430C-9163-07AE7C31D407"
   "type": "FileHandler",
   "properties": [
      {"key": "version", "value": "2" }
   ]
}
allowPublicClient 布尔Boolean 指定回退应用程序类型。Specifies the fallback application type. 默认情况下,Azure AD 基于 replyUrlsWithType 推断应用程序类型。Azure AD infers the application type from the replyUrlsWithType by default. 某些情况下,Azure AD 无法确定客户端应用类型(例如,其中发生了没有 URL 重定向的 HTTP 请求的 ROPC 流)。There are certain scenarios where Azure AD cannot determine the client app type (e.g. ROPC flow where HTTP request happens without a URL redirection). 在这种情况下,Azure AD 将基于此属性的值解释应用程序类型。In those cases Azure AD will interpret the application type based on the value of this property. 如果此值设置为 true,则回退应用程序类型设置为公共客户端,例如在移动设备上运行的已安装应用。If this value is set to true the fallback application type is set as public client, such as an installed app running on a mobile device. 默认值为 false,这意味着,回退应用程序类型为机密,例如 Web 应用。The default value is false which means the fallback application type is confidential client such as web app. false
availableToOtherTenants 布尔Boolean 如果应用程序与其他租户共享,则为 true;否则为 false。true if the application is shared with other tenants; otherwise, false.

注意:仅在应用注册(旧版)体验中可用。此功能已由应用注册体验中的 signInAudience 取代。Note: This is available only in App registrations (Legacy) experience. Replaced by signInAudience in the App registrations experience.
appId StringString 指定由 Azure AD 分配给应用的应用唯一标识符。Specifies the unique identifier for the app that is assigned to an app by Azure AD. "601790de-b632-4f57-9523-ee7cb6ceba95"
appRoles 集合Collection 指定应用可以声明的角色集合。Specifies the collection of roles that an app may declare. 可将这些角色分配给用户、组或服务主体。These roles can be assigned to users, groups, or service principals. 有关更多示例和信息,请参阅在应用程序中添加应用角色并在令牌中接收它们For more examples and info, see Add app roles in your application and receive them in the token [
  {
   "allowedMemberTypes": [
    "User"
   ],
   "description":"Read-only access to device information",
   "displayName":"Read Only",
   "id":guid,
   "isEnabled":true,
   "value":"ReadOnly"
  }
]
displayName StringString 应用的显示名称。The display name for the app.

注意:仅在应用注册(旧版)体验中可用。此功能已由应用注册体验中的 name 取代。Note: This is available only in App registrations (Legacy) experience. Replaced by name in the App registrations experience.
"MyRegisteredApp"
errorUrl StringString 不支持。Unsupported.
groupMembershipClaims StringString 配置应用所需的用户访问令牌或 OAuth 2.0 访问令牌中颁发的 groups 声明。Configures the groups claim issued in a user or OAuth 2.0 access token that the app expects. 若要设置此属性,请使用以下有效的字符串值之一:To set this attribute, use one of the following valid string values:

- "None"
- "SecurityGroup"(适用于安全组和 Azure AD 角色)- "SecurityGroup" (for security groups and Azure AD roles)
- "All"(此项将获取登录用户所属的所有安全组、通讯组和 Azure AD 目录角色)。- "All" (this will get all of the security groups, distribution groups, and Azure AD directory roles that the signed-in user is a member of.
"SecurityGroup"
homepage StringString 应用程序主页的 URL。The URL to the application's homepage.

注意:仅在应用注册(旧版)体验中可用。此功能已由应用注册体验中的 signInUrl 取代。Note: This is available only in App registrations (Legacy) experience. Replaced by signInUrl in the App registrations experience.
"https://MyRegisteredApp"
objectId StringString 应用在目录中的唯一标识符。The unique identifier for the app in the directory.

注意:仅在应用注册(旧版)体验中可用。此功能已由应用注册体验中的 id 取代。Note: This is available only in App registrations (Legacy) experience. Replaced by id in the App registrations experience.
"f7f9acfc-ae0c-4d6c-b489-0a81dc1652dd"
optionalClaims StringString 此特定应用的安全令牌服务在令牌中返回的可选声明。The optional claims returned in the token by the security token service for this specific app.
目前有。At this time. 但是,使用 v2.0 终结点仅为 Azure AD 注册的应用可以获取它们在清单中请求的可选声明。However, apps registered for just Azure AD using the v2.0 endpoint can get the optional claims they requested in the manifest. 有关详细信息,请参阅可选声明For more info, see optional claims.
null
id StringString 应用在目录中的唯一标识符。The unique identifier for the app in the directory. 此 ID 不是用于在任何协议事务中标识应用的标识符。This ID is not the identifier used to identify the app in any protocol transaction. 用于引用目录查询中的对象。It's used for the referencing the object in directory queries. "f7f9acfc-ae0c-4d6c-b489-0a81dc1652dd"
identifierUris String ArrayString Array 用户定义的 URI,用于在 Web 应用的 Azure AD 租户中唯一标识该应用程序;如果应用是多租户的,则用于在已验证的自定义域中唯一标识该应用。User-defined URI(s) that uniquely identify a Web app within its Azure AD tenant, or within a verified custom domain if the app is multi-tenant. [
  "https://MyRegisteredApp"
]
informationalUrls StringString 指定应用服务条款和隐私声明的链接。Specifies the links to the app's terms of service and privacy statement. 服务条款和隐私声明通过用户同意体验展示给用户。The terms of service and privacy statement are surfaced to users through the user consent experience. 有关详细信息,请参阅如何:为已注册的 Azure AD 应用添加服务条款和隐私声明For more info, see How to: Add Terms of service and privacy statement for registered Azure AD apps. {
   "marketing":"https://MyRegisteredApp/marketing",
   "privacy":"https://MyRegisteredApp/privacystatement",
   "support":"https://MyRegisteredApp/support",
   "termsOfService":"https://MyRegisteredApp/termsofservice"
}
keyCredentials 集合Collection 包含对应用所分配的凭据、基于字符串的共享机密和 X.509 证书的引用。Holds references to app-assigned credentials, string-based shared secrets and X.509 certificates. 在请求访问令牌时,可使用这些凭据(如果应用充当客户端而不是资源)。These credentials are used when requesting access tokens (when the app is acting as a client rather that as resource). [
 {
   "customKeyIdentifier":null,
   "endDate":"2018-09-13T00:00:00Z",
   "keyId":"<guid>",
   "startDate":"2017-09-12T00:00:00Z",
   "type":"AsymmetricX509Cert",
   "usage":"Verify",
   "value":null
  }
]
knownClientApplications String ArrayString Array 如果解决方案包含两个部分:客户端应用和自定义 Web API 应用,则该值用于捆绑许可。Used for bundling consent if you have a solution that contains two parts: a client app and a custom web API app. 如果在此值中输入客户端应用的 appID,则用户只需许可该客户端应用一次。If you enter the appID of the client app into this value, the user will only have to consent once to the client app. Azure AD 将知道许可客户端意味着隐式许可 Web API,并自动为客户端和 Web API 同时预配服务主体。Azure AD will know that consenting to the client means implicitly consenting to the web API and will automatically provision service principals for both the client and web API at the same time. 客户端和 Web API 应用都必须在同一个租户中注册。Both the client and the web API app must be registered in the same tenant. ["f7f9acfc-ae0c-4d6c-b489-0a81dc1652dd"]
logoUrl StringString 只读值,指向已在门户中上传的徽标的 CDN URL。Read only value that points to the CDN URL to logo that was uploaded in the portal. "https://MyRegisteredAppLogo"
logoutUrl StringString 用于注销应用的 URL。The URL to log out of the app. "https://MyRegisteredAppLogout"
name StringString 应用的显示名称。The display name for the app. "MyRegisteredApp"
oauth2AllowImplicitFlow 布尔Boolean 指定此 Web 应用是否可以请求 OAuth2.0 隐式流访问令牌。Specifies whether this web app can request OAuth2.0 implicit flow access tokens. 默认值为 false。The default is false. 此标志用于基于浏览器的应用,例如 Javascript 单页应用。This flag is used for browser-based apps, like Javascript single-page apps. 若要了解详细信息,请在目录中输入 OAuth 2.0 implicit grant flow,并查看有关隐式流的主题。To learn more, enter OAuth 2.0 implicit grant flow in the table of contents and see the topics about implicit flow. false
oauth2AllowIdTokenImplicitFlow 布尔Boolean 指定此 Web 应用是否可以请求 OAuth2.0 隐式流 ID 令牌。Specifies whether this web app can request OAuth2.0 implicit flow ID tokens. 默认值为 false。The default is false. 此标志用于基于浏览器的应用,例如 Javascript 单页应用。This flag is used for browser-based apps, like Javascript single-page apps. false
oauth2Permissions 集合Collection 指定 Web API(资源)应用向客户端应用公开的 OAuth 2.0 权限范围集合。Specifies the collection of OAuth 2.0 permission scopes that the web API (resource) app exposes to client apps. 在许可期间,可将这些权限范围授予客户端应用。These permission scopes may be granted to client apps during consent. [
  {
   "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 布尔Boolean 指定在 OAuth 2.0 令牌请求过程中,Azure AD 是否允许与 GET 请求相反的 POST 请求。Specifies whether, as part of OAuth 2.0 token requests, Azure AD will allow POST requests, as opposed to GET requests. 默认值为 false,即指定只允许 GET 请求。The default is false, which specifies that only GET requests will be allowed. false
parentalControlSettings StringString countriesBlockedForMinors 指定禁止未成年人使用该应用的国家/地区。countriesBlockedForMinors specifies the countries in which the app is blocked for minors.
legalAgeGroupRule 指定适用于应用用户的法定年龄组规则。legalAgeGroupRule specifies the legal age group rule that applies to users of the app. 可设置为 AllowRequireConsentForPrivacyServicesRequireConsentForMinorsRequireConsentForKidsBlockMinorsCan be set to Allow, RequireConsentForPrivacyServices, RequireConsentForMinors, RequireConsentForKids, or BlockMinors.
{
   "countriesBlockedForMinors":[],
   "legalAgeGroupRule":"Allow"
}
}
passwordCredentials 集合Collection 请参阅 keyCredentials 属性的说明。See the description for the keyCredentials property. [
  {
   "customKeyIdentifier":null,
   "endDate":"2018-10-19T17:59:59.6521653Z",
   "keyId":"<guid>",
   "startDate":"2016-10-19T17:59:59.6521653Z",
   "value":null
   }
]
]
preAuthorizedApplications 集合Collection 列出了应用程序和针对隐式同意的所请求权限。Lists applications and requested permissions for implicit consent. 要求管理员已针对应用程序表示同意。Requires an admin to have provided consent to the application. preAuthorizedApplications 不要求用户同意所请求的权限。preAuthorizedApplications do not require the user to consent to the requested permissions. preAuthorizedApplications 中列出的权限不要求用户同意。Permissions listed in preAuthorizedApplications do not require user consent. 但是,preAuthorizedApplications 中未列出的任何其他所请求权限都要求用户同意。However, any additional requested permissions not listed in preAuthorizedApplications require user consent. [
  {
    "appId": "abcdefg2-000a-1111-a0e5-812ed8dd72e8",
    "permissionIds": [
      "8748f7db-21fe-4c83-8ab5-53033933c8f1"
    ]
  }
]
publicClient 布尔Boolean 指定此应用程序是否为公共客户端(例如在移动设备上运行的已安装应用程序)。Specifies whether this application is a public client (such as an installed application running on a mobile device).

注意:仅在应用注册(旧版)体验中可用。此功能已由应用注册体验中的 allowPublicClient 取代。Note: This is available only in App registrations (Legacy) experience. Replaced by allowPublicClient in the App registrations experience.
publisherDomain StringString 应用程序的已验证发布者域。The verified publisher domain for the application. 只读。Read-only. https://www.contoso.com
replyUrls 字符串数组String array 此多值属性保存 Azure AD 在返回令牌时接受用作目标的已注册 redirect_uri 值列表。This multi-value property holds the list of registered redirect_uri values that Azure AD will accept as destinations when returning tokens.

注意:仅在应用注册(旧版)体验中可用。此功能已由应用注册体验中的 replyUrlsWithType 取代。Note: This is available only in App registrations (Legacy) experience. Replaced by replyUrlsWithType in the App registrations experience.
replyUrlsWithType 集合Collection 此多值属性保存 Azure AD 在返回令牌时接受用作目标的已注册 redirect_uri 值列表。This multi-value property holds the list of registered redirect_uri values that Azure AD will accept as destinations when returning tokens. 每个 URI 值都应当包含一个关联的应用类型值。Each uri value should contain an associated app type value. 支持的类型值为:WebInstalledClientSupported type values are: Web, InstalledClient. "replyUrlsWithType": [
  {
     "url": "https://localhost:4400/services/office365/redirectTarget.html",
     "type": "InstalledClient"   
  }
]
requiredResourceAccess 集合Collection requiredResourceAccess 可以使用动态许可来驱动管理员许可体验,并驱动使用静态许可的用户的用户许可体验。With dynamic consent, requiredResourceAccess drives the admin consent experience and the user consent experience for users who are using static consent. 但是,它无法驱动常规性的用户许可体验。However, this does not drive the user consent experience for the general case.
resourceAppId 是应用需要访问的资源的唯一标识符。resourceAppId is the unique identifier for the resource that the app requires access to. 此值应等于目标资源应用中声明的 appId。This value should be equal to the appId declared on the target resource app.
resourceAccess 是一个数组,列出应用在指定的资源中所需的 OAuth2.0 权限范围和应用角色。resourceAccess is an array that lists the OAuth2.0 permission scopes and app roles that the app requires from the specified resource. 包含指定的资源的 idtype 值。Contains the id and type values of the specified resources.
[
  {
    "resourceAppId":"00000002-0000-0000-c000-000000000000",
    "resourceAccess":[
      {
        "id":"311a71cc-e848-46a1-bdf8-97ff7156d8e6",
        "type":"Scope"
      }
    ]
  }
]
]
samlMetadataUrl StringString 应用的 SAML 元数据 URL。The URL to the SAML metadata for the app. https://MyRegisteredAppSAMLMetadata
signInUrl StringString 指定应用主页的 URL。Specifies the URL to the app's home page. https://MyRegisteredApp
signInAudience StringString 指定当前应用程序支持哪些 Microsoft 帐户。Specifies what Microsoft accounts are supported for the current application. 支持的值是:Supported values are:
  • AzureADMyOrg - 在我的组织的 Azure AD 租户(即,单租户)中具有 Microsoft 工作或学校帐户的用户AzureADMyOrg - Users with a Microsoft work or school account in my organization’s Azure AD tenant (i.e. single tenant)
  • AzureADMultipleOrgs - 在任何组织的 Azure AD 租户(即,多租户)中具有 Microsoft 工作或学校帐户的用户AzureADMultipleOrgs - Users with a Microsoft work or school account in any organization’s Azure AD tenant (i.e. multi-tenant)
  • AzureADandPersonalMicrosoftAccount - 在任何组织的 Azure AD 租户中具有工作或学校帐户的用户AzureADandPersonalMicrosoftAccount - Users with a work or school account in any organization’s Azure AD tenant
AzureADandPersonalMicrosoftAccount
tags String ArrayString Array 可用来对应用程序进行分类和标识的自定义字符串。Custom strings that can be used to categorize and identify the application. [
  "ProductionApp"
]

常见问题Common issues

清单限制Manifest limits

应用程序清单包含多个称为集合的属性,例如 approles、keycredentials、knownClientApplications、identifierUris、rediretUris、requiredResourceAccess 和 oauth2Permissions。An application manifest has multiple attributes that are referred to as collections; for example, approles, keycredentials, knownClientApplications, identifierUris, rediretUris, requiredResourceAccess, and oauth2Permissions. 在任一应用程序的完整应用程序清单中,所有合并集合中的条目总数不能超过 1200 个。Within the complete application manifest for any application, the total number of entries in all the collections combined has been capped at 1200. 如果已在应用程序清单指定了 100 个重定向 URI,则在构成该清单的其他所有合并集合中,只剩下 1100 个条目可供使用。If you already have 100 redirect URIs specified in the application manifest, then you're only left with 1100 remaining entries to use across all other collections combined that make up the manifest.

Note

如果尝试在应用程序清单中添加 1200 个以上的条目,可能会看到错误 “无法更新应用程序 xxxxxx。错误详细信息: 清单大小已超过其限制。请减少值数,然后重试请求。”In case you try to add more than 1200 entries in the application manifest, you may see an error "Failed to update application xxxxxx. Error details: The size of the manifest has exceeded its limit. Please reduce the number of values and retry your request."

不支持的属性Unsupported attributes

应用程序清单代表 Azure AD 中底层应用程序模型的架构。The application manifest represents the schema of the underlying application model in Azure AD. 随着底层架构的不断演进,清单编辑器将不时地更新,以反映新的架构。As the underlying schema evolves, the manifest editor will be updated to reflect the new schema from time to time. 因此,你可能会在应用程序清单中看到新的属性。As a result, you may notice new attributes showing up in the application manifest. 在极少数情况下,可能会注意现有属性中出现了语法或语义的更改,或者以前存在的某个属性不再受支持。In rare occasions, you may notice a syntactic or semantic change in the existing attributes or you may find an attribute that existed previously are not supported anymore. 例如,你会在应用注册中看到新的属性,而这些属性在应用注册(旧版)体验中使用不同的名称。For example, you will see new attributes in the App registrations which are known with a different name in the App registrations (Legacy) experience.

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

有关这些属性的说明,请参阅清单参考部分。For descriptions for these attributes, see the manifest reference section.

尝试上传以前下载的清单时,可能会看到以下错误之一。When you try to upload a previously downloaded manifest, you may see one of the following errors. 可能的原因是清单编辑器现在支持更新版本的架构,而该架构与你尝试上传的架构不匹配。This is likely because the manifest editor now supports a newer version of the schema, which doesn't match with the one you're trying to upload.

  • 无法更新 xxxxxx 应用程序。错误详细信息:无效的对象标识符 'undefined'。[]"Failed to update xxxxxx application. Error detail: Invalid object identifier 'undefined'. []."
  • 无法更新 xxxxxx 应用程序。错误详细信息:指定的一个或多个属性值无效。[]"Failed to update xxxxxx application. Error detail: One or more property values specified are invalid. []."
  • 无法更新 xxxxxx 应用程序。错误详细信息:不允许在此 api 版本中设置要更新的 availableToOtherTenants。[]"Failed to update xxxxxx application. Error detail: Not allowed to set availableToOtherTenants in this api version for update. []."
  • 无法更新 xxxxxx 应用程序。错误详细信息:不允许更新此应用程序的 'replyUrls' 属性。请改用 'replyUrlsWithType' 属性。[]"Failed to update xxxxxx application. Error detail: Updates to 'replyUrls' property is not allowed for this application. Use 'replyUrlsWithType' property instead. []."
  • 无法更新 xxxxxx 应用程序。错误详细信息:找到了没有类型名称的值,且没有预期的类型可用。如果指定该模型,则有效负载中的每个值都必须具有可在有效负载中指定、显式由调用方调用或隐式从父值推断的类型。[]"Failed to update xxxxxx application. Error detail: A value without a type name was found and no expected type is available. When the model is specified, each value in the payload must have a type which can be either specified in the payload, explicitly by the caller or implicitly inferred from the parent value. []"

如果看到以下错误之一,我们建议采取以下措施:When you see one of these errors, we recommend the following:

  1. 单独在清单编辑器中编辑属性,而不要上传以前下载的清单。Edit the attributes individually in the manifest editor instead of uploading a previously downloaded manifest. 使用清单参考表来了解旧属性和新属性的语法与语义,以便能够成功编辑所需的属性。Use the manifest reference table to understand the syntax and semantics of old and new attributes so that you can successfully edit the attributes you're interested in.
  2. 如果工作流要求在源存储库中保存清单供以后使用,我们建议使用应用注册体验中显示的清单来变基存储库中保存的清单。If your workflow requires you to save the manifests in your source repository for use later, we suggest rebasing the saved manifests in your repository with the one you see in the App registrations experience.

后续步骤Next steps

使用以下评论部分提供反馈,帮助我们改进和组织内容。Use the following comments section to provide feedback that helps refine and shape our content.