API 密钥身份验证

项目
10/28/2024

API 密钥身份验证是一种方法，用于使用 API 对消息扩展应用的访问权限进行身份验证。它涉及使用唯一的 API 密钥，该密钥随每个 API 请求一起传递，以验证发起请求的用户或应用的标识。 API 密钥必须在 Microsoft Teams 中注册，当用户与消息扩展交互时，Teams 会使用该机密向 API 进行身份验证。

以下 API 密钥注册属性可帮助你保护密钥并确保它仅限于应用程序：

基 URL：Teams 将机密传输到以此字段中的值开头的 URL 终结点。
目标租户：限制对 Microsoft 365 租户或任何租户的 API 访问。
应用 ID：将密钥访问限制为特定应用或任何应用。
API 密钥：对应用的访问权限进行身份验证。

可以通过 Teams 开发人员门户注册 API 密钥，并生成 API 密钥注册 ID。使用具有属性的 apiSecretServiceAuthConfiguration 对象apiSecretRegistrationId更新应用清单。此属性必须包含通过 Teams 开发人员门户提交 API 密钥时返回的 API 密钥注册 ID。

注意

必须确保 API 密钥注册 ID 的安全，因为它可以从 Teams 应用清单中检索。有关保护 API 密钥的详细信息，请参阅最佳做法。

启动 API 请求时，系统会使用持有者令牌方案从加密的数据库检索 API 密钥，并将其包含在授权标头中。系统将带有 API 密钥的授权标头发送到应用清单中定义的终结点。

以下示例显示了使用持有者令牌方案的授权标头的有效负载：

GET https://example.com/search?myQuery=test
Accept-Language: en-US
Authorization: Bearer <MY_API_KEY>

注册 API 密钥

若要注册 API 密钥，请执行以下步骤：

转到 “工具 API>密钥注册”。
选择“ + 新建 API 密钥”。
在 “API 密钥注册 ”页中，选择“ + 添加机密”。此时会显示 “添加 API 密钥 ”对话框。
输入密钥的值，然后选择“ 保存”。

注意

最多可以维护两个 API 密钥。如果需要替换一个密钥，可以在不中断服务的情况下执行此操作，因为 Teams 在更新过程中会使用另一个配置的密钥。
在 “API 密钥名称”下，为 API 密钥添加有意义的名称。例如，Contoso 消息扩展的 API 密钥。
在“ 基 URL”下，为所有必须调用的 API 终结点指定通用基 URL。此 URL 必须以 https 开头，包括完全限定的域名和路径（可选）。 Teams 将密钥传输到以此字段中的值开头的 URL 终结点。例如，https://api.yelp.com。

基 URL 可确保密钥保持安全，并且不会泄露到随机终结点，即使另一个应用非法获取 API 密钥注册 ID 并将其合并到自己的应用中也是如此。如果在 API 密钥配置中注册的 URL 不是 OpenAPI 规范中定义的目标终结点的前缀，则会删除调用。
在“ 目标租户”下，选择以下任一项：
- 主租户：API 密钥仅在注册的租户中有效。
- 任何租户：API 密钥可在任何租户中使用。
在 “目标 Teams 应用”下，选择以下任一项：
- 现有 Teams 应用： “现有 Teams 应用 ”选项将 API 密钥注册 ID 绑定到特定的 Teams 应用。
- 任何 Teams 应用：API 密钥可用于任何 Teams 应用。
将生成 API 密钥注册 ID 。
在 Teams 开发人员门户中，选择“ 应用 ”，然后选择要在其中添加 API 密钥的应用。
转到 应用功能>消息扩展。
在 “身份验证”下，选择“ API 密钥 ”并添加 API 密钥注册 ID。
选择“保存”。

API 密钥注册 ID 更新为应用清单中属性的值 apiSecretRegistrationId 。可以在 Teams 开发人员门户的应用清单中验证 API 密钥注册 ID。

更新应用清单

apiSecretServiceAuthConfiguration通过 Teams 开发人员门户提交 API 密钥时，添加具有 apiSecretRegistrationId 属性的对象，该属性包含引用 ID。有关详细信息，请参阅 composeExtensions.commands。

"composeExtensions": [
    {
      "composeExtensionType": "apiBased",
      "authorization": {
        "authType": "apiSecretServiceAuth",
        "apiSecretServiceAuthConfiguration": {
            "apiSecretRegistrationId": "9xxxxb0f-xxxx-40cc-xxxx-15xxxxxxxxx3"
        }
      },

最佳做法

API 密钥：
- API 密钥必须至少包含 10 个字符，最多 2048 个字符。
- 更新 API 密钥后，密钥最多需要一个小时才能反映整个系统。
基 URL：
- 基 URL 必须以 https 开头，以确保安全通信。
- 必须包含完整的主机名才能指定确切的域。
- 可以添加可选路径来定义 API 的特定入口点。
当 Teams 将 API 密钥发送到以指定基 URL 开头的终结点时，此结构对于 API 密钥 () 的安全性至关重要。
目标租户：在 Microsoft 365 租户中开发应用时，最初会将其测试为为组织构建的自定义应用， (LOB 应用) 或自定义应用。在此阶段，必须将 API 密钥注册到 主租户 作为目标租户，以确保该密钥对租户保持独占。

完成测试并准备好将应用清单提交到 Teams 应用商店的合作伙伴中心后，需要将目标租户设置切换到 “任何租户”。此更改允许在 Teams 应用商店中提供应用后，跨各种租户使用 API 密钥注册 ID。
Teams 应用 ID：在 Microsoft 365 租户中开发应用并开始将其测试为组织 (LOB) 或自定义应用构建的自定义应用时，必须使用 Teams 应用 ID 将 API 密钥注册 ID 设置为 任何 Teams 应用。此配置允许将密钥用于上传为自定义应用的任何 Teams 应用，以及为组织构建的自定义应用 (LOB 应用，) 在上传 ID 后生成 ID。在此阶段，你将没有应用的 ID。

密钥的安全性仍通过 主租户 和 基 URL 进行维护。准备好向世界发布应用时，需要将 Teams 应用 ID 设置更改为 “现有 Teams 应用 ”并输入 Teams 应用 ID。最后，将应用清单提交到合作伙伴中心以包含在 Teams 应用商店中。 API 密钥注册现在绑定到特定的 Teams 应用，不能与其他人一起使用。

对于为组织生成的自定义应用 (LOB) 或自定义应用，存在难以访问的内部应用 ID。在此方案中，将配置限制为使用应用的租户。对于其他应用，请在将 API 密钥注册发布到 Teams 应用商店后将其链接到已发布的应用 ID。

通过

API 密钥身份验证

注册 API 密钥

更新应用清单

最佳做法

另请参阅

其他资源