编辑Microsoft Entra清单

2025-06-05

Microsoft 365 Agents Toolkit (以前称为 Teams 工具包) 现在管理Microsoft Entra应用程序，在Microsoft Teams 应用程序开发生命周期中将应用清单文件作为事实来源。

自定义Microsoft Entra清单模板

可以自定义Microsoft Entra清单模板以更新Microsoft Entra应用程序。

在项目中打开 aad.template.json 。
直接更新模板或引用另一个文件中的值。下面是自定义方案：
添加应用程序权限

如果 Teams 应用程序需要更多权限来调用具有其他权限的 API，则需要更新requiredResourceAccessMicrosoft Entra清单模板中的属性。可以看到此属性的以下示例：
```
"requiredResourceAccess": [
    {
        "resourceAppId": "Microsoft Graph",
        "resourceAccess": [
            {
                "id": "User.Read", // For Microsoft Graph API, you can also use uuid for permission id
                "type": "Scope" // Scope is for delegated permission
            },
            {
                "id": "User.Export.All",
                "type": "Role" // Role is for application permission
            }
        ]
    },
    {
        "resourceAppId": "Office 365 SharePoint Online",
        "resourceAccess": [
            {
                    "id": "AllSites.Read",
            "type": "Scope"
            }
        ]
    }
]
```
以下列表提供了不同的属性 ID 及其用法：
- 属性 resourceAppId 用于不同的 API。对于 Microsoft Graph 和 Office 365 SharePoint Online，请直接输入名称而不是 UUID，对于其他 API，请使用 UUID。
- 属性 resourceAccess.id 用于不同的权限。对于 Microsoft Graph 和 Office 365 SharePoint Online，请直接输入权限名称而不是 UUID，对于其他 API，请使用 UUID。
- 属性 resourceAccess.type 用于委派权限或应用程序权限。 Scope 表示委托的权限，表示 Role 应用程序权限。
预授权客户端应用程序

可以使用 preAuthorizedApplications 属性来授权客户端应用程序，以指示 API 信任应用程序。客户端调用公开的 API 时，用户不同意。可以看到此属性的以下示例：
```
"api": {
   ...
   "preAuthorizedApplications": [
       {
           "appId": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
           "delegatedPermissionIds": [
               "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
           ]
       }
   ]
   ...
}
```
preAuthorizedApplications.appId 属性用于要授权的应用程序。如果不知道应用程序 ID，并且只知道应用程序名称，请使用以下步骤搜索应用程序 ID：
1. 转到Azure 门户并打开“应用程序注册”。
2. 选择“ 所有应用程序 ”并搜索应用程序名称。
3. 选择应用程序名称，并从概述页获取应用程序 ID。
更新身份验证响应的重定向 URL

身份验证成功后返回身份验证响应（例如令牌）时使用重定向 URL。可以使用、中的 webspapublicClient属性redirectUris自定义重定向 URL。例如，若要添加 https://www.examples.com/auth-end.html 为重定向 URL，可以将其添加为以下示例：
```
"publicClient": {
  "redirectUris": [
      "https://www.examples.com/auth-end.html"
  ]
},
"web": {
  "redirectUris": [
      "https://www.examples.com/auth-end.html"
  ],
  "implicitGrantSettings": {}
},
"spa": {
  "redirectUris": [
      "https://www.examples.com/auth-end.html",
  ]
}
```
更新本地或远程环境Microsoft Entra应用程序更改。
1. 在 aad.template.json中选择 CodeLensPreview。
2. 选择 “本地 ”或 “开发 环境”。
3. 在或 aad.dev.json中选择 Deploy Azure AD Manifestaad.local.json CodeLens。
4. 将部署在本地或开发环境中使用的Microsoft Entra应用程序的更改。
5. 此外，可以打开命令面板并选择“Teams：更新Microsoft Entra应用”以更新Microsoft Entra应用。

我遇到了问题

Microsoft Entra清单模板占位符

Microsoft Entra清单文件包含具有 {{...}} 的占位符参数语句，在针对不同环境生成期间会替换它。可以使用占位符参数引用环境变量。

Microsoft Entra清单模板中的引用环境变量

无需在Microsoft Entra清单模板中输入永久值，Microsoft Entra清单模板文件支持引用环境变量值。可以使用工具中的语法 ${{YOUR_ENV_VARIABLE_NAME}} 作为参数值来解析环境变量值。

使用 CodeLens 编辑和预览Microsoft Entra清单

Microsoft Entra清单模板文件包含用于查看和编辑代码的 CodeLens。

Microsoft Entra清单模板文件

Microsoft Entra清单模板文件的开头有一个预览版 CodeLens。选择 CodeLens 以根据环境生成Microsoft Entra清单。

屏幕截图显示了添加 codelens 的预览。

占位符参数 CodeLens

占位符参数 CodeLens 可帮助你查看本地调试和开发环境的值。如果将鼠标悬停在占位符参数上，则会显示所有环境值的工具提示框。

屏幕截图显示了添加参数。

所需的资源访问 CodeLens

代理工具包中的Microsoft Entra清单模板还支持和 Office 365 SharePoint Online 权限的用户可读字符串Microsoft Graph。官方Microsoft Entra清单架构，即 resourceAppId 和 resourceAccess 中的 requiredResourceAccess 属性仅支持 UUID。如果输入 UUID，CodeLens 将显示用户可读字符串，否则会显示 UUID。

屏幕截图显示了将资源添加到所需的资源访问权限。

预授权应用程序 CodeLens

CodeLens 显示 api 属性内属性的预授权应用程序 ID preAuthorizedApplications 的应用程序名称。

在Azure 门户上查看Microsoft Entra应用程序

从 .env.xxx 属性中的 () 文件AAD_APP_CLIENT_ID复制Microsoft Entra应用程序客户端 ID。

注意

客户端 ID 中的 xxx 指示部署Microsoft Entra应用程序的环境名称。
转到Azure 门户并登录到 Microsoft 365 帐户。

注意

确保 Teams 应用程序和 M365 帐户的登录凭据相同。
打开“应用注册”页，并使用之前复制的客户端 ID 搜索Microsoft Entra应用程序。
从搜索结果中选择Microsoft Entra应用程序以查看详细信息。
在“Microsoft Entra应用信息”页中，选择“清单”菜单以查看此应用程序的清单。清单的架构与文件中 aad.template.json 的架构相同。有关清单的详细信息，请参阅Microsoft Entra应用清单。
可以选择“其他菜单”，通过应用程序门户查看或配置Microsoft Entra应用程序。

我遇到了问题

使用现有Microsoft Entra应用程序

可以将现有的 Microsoft Entra 应用程序用于 Teams 项目。有关详细信息，请参阅为 Teams 应用程序使用现有的 Microsoft Entra 应用程序。

Teams 应用程序开发生命周期中的Microsoft Entra应用程序

需要在 Teams 应用程序开发生命周期的各个阶段与Microsoft Entra应用程序进行交互。

创建项目

可以使用 Agents Toolkit 创建项目，该项目附带单一登录 (SSO) 默认支持，例如 SSO-enabled tab。有关如何创建新应用的详细信息，请参阅使用代理工具包创建新的 Teams 应用程序。会在中aad.template.json自动创建Microsoft Entra清单文件。代理工具包在本地开发期间或将应用程序移动到云时创建或更新Microsoft Entra应用程序。
将 SSO 添加到机器人或选项卡

创建没有内置 SSO 的 Teams 应用程序后，Agents Toolkit 会逐步帮助你为项目添加 SSO。因此，会在中aad.template.json自动创建Microsoft Entra清单文件。

代理工具包在下一个本地开发会话期间或将应用程序移动到云时创建或更新Microsoft Entra应用程序。
在本地生成

代理工具包在本地开发期间执行以下功能：
- 读取文件.env.local以查找现有Microsoft Entra应用程序。如果Microsoft Entra应用程序已存在，则 Agents Toolkit 将重复使用现有的Microsoft Entra应用程序。否则，需要使用文件创建一个新应用程序 aad.template.json 。
- 最初忽略清单文件中需要更多上下文的某些属性，例如redirectUris，在创建具有清单文件的新Microsoft Entra应用程序期间需要本地开发终结点的属性。
- 在本地开发环境成功启动后，Microsoft Entra应用程序的 identifierUris、redirectUris、和其他在创建阶段不可用的属性将相应地更新。
- 在下一个本地开发会话期间，将加载对 Microsoft Entra 应用程序所做的更改。可以看到手动应用Microsoft Entra应用程序更改。
预配云资源

在将应用程序移动到云时，需要预配云资源并部署应用程序。在本地调试等阶段，代理工具包：
- 读取文件以.env.{env}查找现有Microsoft Entra应用程序。如果Microsoft Entra应用程序已存在，则 Agents Toolkit 将重复使用现有的Microsoft Entra应用程序。否则，需要使用文件创建一个新应用程序 aad.template.json 。
- 忽略清单文件中最初需要更多上下文（如属性） redirectUris 的某些属性。在创建包含清单文件的新Microsoft Entra应用程序期间，此属性需要前端或机器人终结点。
- 完成其他资源预配，然后Microsoft Entra应用程序的 identifierUris，并根据redirectUris正确的终结点进行更新。
生成应用程序
- 云命令将应用程序部署到预配的资源。它不包括部署Microsoft Entra你所做的更改的应用程序。
- Agents Toolkit 根据Microsoft Entra清单模板文件更新Microsoft Entra应用程序。

限制

代理工具包扩展不支持Microsoft Entra清单架构中列出的所有属性。

下表列出了代理工具包扩展中不支持的属性：

不支持的属性	原因
`passwordCredentials`	不允许在清单中
`createdDateTime`	只读且无法更改
`logoUrl`	只读且无法更改
`publisherDomain`	只读且无法更改

属性 requiredResourceAccess 用于用户可读的资源应用程序名称或权限名称字符串，仅适用于 Microsoft Graph 和 Office 365 SharePoint Online API。需要将 UUID 用于其他 API。执行以下步骤，从Azure 门户检索 ID：
1. 在 Azure 门户上注册新的Microsoft Entra应用程序。
2. 从“Microsoft Entra应用程序”页中选择API permissions。
3. 选择 add a permission 以添加所需的权限。
4. 从 requiredResourceAccess 属性中进行选择Manifest，可在其中找到 API 的 ID 和权限。