azure - 从 azure apim 导出的 OAS 中的安全和策略

Question

假设我有不同的后端服务，在 azure api 管理 (apim) 中公开其 api。不同的服务依赖于不同的安全方法，例如jwt token 和订阅 key 。后端开发人员指定这些差异并使用 OpenApi 规范 (OAS) 将其上传到 apim。然后我发现Security definitions are ignored那么开发者必须在哪里指定这些信息呢？而是在描述中？或者在 apim 中传递安全信息的正确方法是什么。

此外，apim 可以设置有关安全的策略。这些政策也没有在美洲国家组织中公开。然而，除了订阅 key 之外，这只是默认行为，即使在 apim 的 api 设置中禁用了需要订阅的标签，订阅 key 仍然存在于 OAS 中。

那么当 OAS 中不存在后端服务安全性和 apims 安全性时，如何通知用户呢？我是否缺少某些配置？

我的 apim 的想法是让不同的后端服务供应商拥有不同的安全级别 - 可以在 OAS 中指定 - 但不会在 apim 导出的版本中提供任何内容。

此外，作为 apim 的所有者，我将设置一些安全设置 - 这些设置仍然不会出现在 OAS 中。那么消费者应该怎样做才能了解如何使用下载的 OAS 中公开的后端端点呢？

Answer 1

这个问题有几个部分......

在我工作的公司；我们使用 APIM，但我们没有在其中定义开放 API 规范 (OAS)。 IMO APIM 并不是真正打算用作 API 文档工具。

我们在Swagger Hub中定义并记录了OAS 。 Swagger Hub 是 Swagger 规范背后的公司，该规范现已更名为 Open API 规范。 Swagger Hub 是一项商业产品，但我认为还有免费套餐。

您可能知道，您可以在开放 API 规范中定义多种安全方案，例如

securitySchemes:
    jwt_token:
        type: oauth2
        flows:
            authorizationCode:
                authorizationUrl: {my-authorization-url}
                tokenUrl: {my-token-url}
    apim_subscription_key:
        type: apiKey
        in: header
        name: X-API-KEY

然后，您可以将这些安全方案应用到您的 Open API 规范(无论是在根级别还是在单个操作上)。

paths:
    '/{version}/users':
        get:
            summary: 'Search for users'
            description: 'blah'
            security:
                - jwt_token: []
                - apim_subscription_key: []

在 Swagger Hub 中，您可以“查看文档”以在“Swagger UI”中呈现开放 API 规范。当您在 Swagger UI 中调用操作时，您可以将服务器配置为指向不同的位置(例如 APIM)，例如

servers:
    - description: 'localhost'
      url: http://localhost:{port}
      variables:
        port:
            default: "8089"
    - description: 'APIM DEV'
      url: {apim-url}

参见here有关配置服务器的更多信息。

在 OAS 呈现的 Swagger UI 中，单击授权按钮并对指定的安全方案之一进行身份验证，如下所示:

并通过下拉菜单更改您指向的服务器:

切换到 APIM 服务器并调用您的 API 操作来调用 APIM 前端的 API。

您可以在 Swagger Hub 中发布 API，并使您的消费者可以公开访问该 API。

在 APIM 中，您可能需要实现诸如 validate JWT 之类的策略。 ，但正如您所提到的，这些并不存在于美洲国家组织中。理想情况下，您的 APIM 配置将全部处于源代码控制中，其中包括 OAS 以及 APIM 策略和其他配置等内容。完成所有这些实际上并不是微不足道的 - 我最近观看了一个 PluralSight 类(class)，它很好地概述了如何为 APIM 设置 SCM - 请参阅 here .

Swagger Hub 中有一个集成，可将 OAS 直接发布到 APIM，这可能也很有趣，但我尚未将其用作任何工作流程的一部分。请参阅here .

写给您的 API 消费者，您可以:

• 向他们提供来自 Swagger Hub 的 OAS，其中包括安全方案、服务器等。
• 只需让他们访问 Swagger UI 文档，这对于您的 OAS 来说是一个很好的 UI，能够根据您指定的安全方案进行身份验证并向在不同位置(例如，在不同位置运行的 API)发出 API 请求。本地主机，或在 APIM 后面的 Azure 中运行的 DEV/SIT/UAT API...