在代理中为 API 插件配置身份验证

2025-05-20

可以使用四种受支持的身份验证方案中的任何一种来无缝连接到后端 API，为在智能 Microsoft 365 Copilot 副驾驶® 中运行的代理中的 API 插件配置身份验证：

OAuth 2.0 授权代码授予流
Microsoft Entra ID单一登录 (SSO) 身份验证
API 密钥身份验证
无身份验证 (匿名)

OAuth 2.0 授权代码授予流

插件可以使用通过 OAuth 2.0 授权代码流获取的持有者令牌访问 API，以及可选的代码交换证明密钥 (PKCE) 支持。

在开始之前，需要向 OAuth 2.0 提供程序注册以获取客户端 ID 和机密。如果 OAuth 提供程序要求你在应用注册期间指定允许的重定向 URI，请确保包含在 https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect 列表中。

重要

对 OAuth 2.0 的 API 插件支持具有以下限制。

API 插件仅支持 OAuth 2.0 的授权代码流。
不支持从令牌终结点返回 307 Temporary Redirect HTTP 状态代码的 OAuth 2.0 服务器。

可以在 OpenAPI 文档的属性中 securitySchemes 定义此方案。有关详细信息，请参阅 OAuth 2.0。

securitySchemes:
  OAuth2:
    type: oauth2
    flows:
      authorizationCode:
        authorizationUrl: <authorization_url>
        tokenUrl: <token_url>
        refreshUrl: <refresh_url>
        scopes:
          scope: description

若要启用 OAuth 2.0 身份验证，需要在 Teams 开发人员门户中注册 OAuth 客户端。可以使用 Microsoft 365 代理工具包注册 OAuth 客户端， (Visual Studio Code中的 Teams 工具包) 演变，也可以在 Teams 开发人员门户中手动注册。

使用代理工具包注册 OAuth 客户端

从现有 OpenAPI 文档使用 API 插件创建代理时，代理工具包会注册 OAuth 客户端并更新应用包。必须在 securitySchemes OpenAPI 文档中定义属性。

如果 OAuth 提供程序支持 PKCE，请在预配代理项目m365agents.yml中取消注释以下代码行。

# isPKCEEnabled: true

在 Teams 开发人员门户中注册 OAuth 客户端

打开 Teams 开发人员门户。选择 “工具 ”->OAuth 客户端注册”。
如果没有现有注册，请选择“ 注册客户端”。如果有现有注册，请选择“ 新建 OAuth 客户端注册”。
填写以下字段。
- 注册名称：注册的友好名称。
- 基 URL：API 的基 URL。此值应对应于 OpenAPI 文档中数组中的servers条目。
- 客户端 ID：OAuth 2.0 提供程序颁发的客户端 ID 或应用程序 ID。
- 客户端密码：OAuth 2.0 提供程序颁发的客户端密码。
- 授权终结点：应用用于请求授权代码的 OAuth 2.0 提供程序的 URL
- 令牌终结点：来自 OAuth 2.0 提供程序的 URL，应用用于兑换访问令牌的代码
- 刷新终结点：应用用于刷新访问令牌的 OAuth 2.0 提供程序的 URL
- 范围：由允许访问的 API 定义的权限范围。
- 为代码交换启用证明密钥 (PKCE) ：如果 OAuth 提供程序支持 PKCE，请启用此设置。
选择“保存”。
完成注册会生成 OAuth 客户端注册 ID。

将客户端注册 ID 添加到插件清单

若要对 API 插件使用 OAuth 2.0 身份验证，请将运行时身份验证对象的属性设置为 OAuthPluginVaulttype ，并从 Teams 开发人员门户将设置为reference_id客户端注册 ID。

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "auth registration ID"
},

Microsoft Entra ID SSO 身份验证

Microsoft Entra ID SSO 身份验证允许无缝单一登录 (SSO) 集成，使用户能够使用其现有Microsoft Entra ID凭据进行身份验证。此集成简化了访问管理，并确保与 API 建立安全连接，而无需额外的凭据。 API 必须使用Microsoft Entra ID来控制访问。

在 Teams 开发人员门户中注册 SSO 客户端

打开 Teams 开发人员门户。选择“工具”->Microsoft Entra SSO 客户端 ID 注册。
如果没有现有注册，请选择“ 注册客户端 ID”。如果有现有注册，请选择“ 新建客户端注册”。
填写以下字段。
- 注册名称：注册的友好名称。
- 基 URL：API 的基 URL。此值应对应于 OpenAPI 文档中数组中的servers条目。
- 按组织限制使用：选择哪些Microsoft 365 组织有权访问应用以访问 API 终结点。
- 按应用限制使用：如果你不知道最终应用 ID，请选择“ 任何 Teams 应用”。发布应用后，将此注册与已发布的应用 ID 绑定。
- 客户端 ID：在 Microsoft Entra 中注册的应用的客户端 ID。
选择“保存”。
完成注册会生成Microsoft Entra SSO 注册 ID 和应用程序 ID URI。

更新Microsoft Entra应用注册

打开Microsoft Entra 管理中心。使用 Teams 开发人员门户生成的应用程序 ID URI 更新保护 API 的Microsoft Entra应用注册。如果现有应用程序 ID URI 映射到应用注册，则可以使用清单编辑器在 identifierUris 节中添加另一个 URI。
```
"identifierUris": [
  "<<URI1>>"
  "<<URI2>>"
]
```
注意

不支持通过Microsoft Entra 管理中心的 UI 添加多个 URI。 UI 仅显示列表中的第一个 URI。添加多个 URI 不会影响现有的 URI 和范围，即使它们在 UI 中的显示方式不同。
选择“管理”下的“身份验证”。添加到 https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirectWeb 平台中的重定向 URI。
在“管理”下选择“公开 API”。选择“ 添加客户端应用程序 ”，并添加Microsoft企业令牌存储 ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b的客户端 ID。

将 SSO 注册 ID 添加到插件清单

从 type Teams 开发人员门户将运行时身份验证对象的属性设置为 OAuthPluginVault，并将设置为 reference_idMicrosoft Entra SSO 注册 ID。

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "SSO registration ID"
},

将新的令牌受众添加到 API

更新 API 以允许新的标识符 URI 作为令牌受众。如果 API 验证客户端应用程序 ID，请确保将Microsoft企业令牌存储的客户端 ID (ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b) 添加为允许的客户端应用程序。

提示

如果 API 使用代理流来访问另一个需要用户授予同意的 Web API，则返回错误 401 Unauthorized ，使代理提示用户登录以授予许可。

API 密钥身份验证

某些 API 使用 API 密钥进行授权。 API 密钥是客户端在 API 请求中包括的共享机密，用于进行身份验证和获取访问权限。 API 插件支持通过三种方式发送 API 密钥：

作为标头中的 Authorization 持有者令牌
作为自定义标头中的值
作为查询参数

将 API 密钥添加到 OpenAPI 文档

智能 Microsoft 365 Copilot 副驾驶®确定如何根据 OpenAPI 文档中的securitySchemes条目发送 API 密钥。

持有者令牌

如果 API 接受 API 密钥作为持有者令牌，请在 OpenAPI 文档中启用持有者身份验证。有关详细信息，请参阅持有者身份验证。

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

自定义标头

如果 API 接受自定义标头中的 API 密钥，请在 OpenAPI 文档中 in 启用 API 密钥身份验证，并将属性设置为 headername 标头名称。有关详细信息，请参阅 API 密钥。

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-KEY

查询参数

如果 API 接受查询参数中的 API 密钥，请在 OpenAPI 文档中in启用 API 密钥身份验证，并将属性queryname设置为查询参数的名称。有关详细信息，请参阅 API 密钥。

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: query
    name: api_key

注册 API 密钥

若要启用 API 密钥身份验证，需要在 Teams 开发人员门户中注册 API 密钥。可以在 Visual Studio Code 中向代理工具包注册 API 密钥，也可以在 Teams 开发人员门户中手动注册。

向代理工具包注册 API 密钥

从现有 OpenAPI 文档使用 API 插件创建代理时，代理工具包会注册 API 密钥并更新应用包。必须在 securitySchemes OpenAPI 文档中定义属性。

在 Teams 开发人员门户中注册 API 密钥

打开 Teams 开发人员门户。选择“工具”->“API 密钥注册”
如果没有现有注册，请选择“ 创建 API 密钥”。如果有现有注册，请选择“ 新建 API 密钥”。
选择“ 添加机密 ”并输入 API 密钥。
填写以下字段。
- API 密钥名称：注册的友好名称。
- 基 URL：API 的基 URL。此值应对应于 OpenAPI 文档中数组中的servers条目。
- 目标租户：是否限制对主租户的 API 访问。
- 目标 Teams 应用：如果你不知道最终应用 ID，请选择 “任何 Teams 应用”。发布应用后，将此注册与已发布的应用 ID 绑定。
选择“保存”。
完成注册会生成 API 密钥注册 ID。

将 API 密钥注册 ID 添加到插件清单

在插件清单文件中，将运行时身份验证对象的属性设置为 ApiKeyPluginVaulttype ，并从 Teams 开发人员门户将设置为 reference_id API 密钥注册 ID。

"auth": {
  "type": "ApiKeyPluginVault",
  "reference_id": "app key registration ID"
},

无身份验证 (匿名)

对于不需要任何身份验证的 API，或者对于尚未实现身份验证的开发人员环境，插件可以匿名访问 API。在这种情况下，请将运行时身份验证对象的属性设置为 Nonetype 。

"auth": {
  "type": "None"
},

通过