在 OpenAPI (Swagger) 中使用 HMAC-SHA256 身份验证测试 API 路由答案

【问题标题】：Testing API routes with HMAC-SHA256 authentication in OpenAPI (Swagger)在 OpenAPI (Swagger) 中使用 HMAC-SHA256 身份验证测试 API 路由
【发布时间】：2017-11-21 20:03:15
【问题描述】：

我正在尝试为需要 HMAC-SHA256 身份验证的 API 路由生成 OpenAPI (Swagger) 文档。这意味着我必须为每个请求包含 Authorization 标头，该标头由 API 密钥和生成的由冒号分隔的 HMAC 签名（例如 Authorization: API_KEY:GENERATED_SIGNATURE）组成。

我可以使用 JavaScript 轻松生成所需的签名，但我不知道如何在 Swagger-UI“授权”弹出窗口中添加“密钥”和“秘密”输入字段以及如何最终将其添加到 Authorization每个请求中的标头。

OpenAPI 规范 v3 是否可以做到这一点？

【问题讨论】：

这是一个旧线程，但想知道您是否找到了解决方案？我正在尝试做同样的事情 :) 提前致谢。
不幸的是，我还没有设法解决这个问题......没有付出太多努力，因为我跳过了一些东西直到我找到解决方案......

标签： javascript authorization swagger swagger-ui hmac

【解决方案1】：

我不会在开放 API 规范中发布任何可能导致安全问题的密钥和/或机密。此类信息应与 API 文档分开并通过安全线路进行交流。

我没有找到很多示例来说明至少如何启用 apiKey，因此这是定义 HMAC 安全性或 apiKey 的一种方法。（使用开放 API 规范 3.0）

在 components 下的根级别，需要定义“securitySchemes”。（这是让它工作所必需的。）

   components:
      securitySchemes:
        api_key:
          type: apiKey
          name: gpa_key
          in: header
          description: HMAC code encoded with key
      parameters:
         CustomerIdPathParam:
           name: customerId
           in: query
           description: Customer id
           required: true
           schema:
             type: string
             maxLength: 32
             example: TEST_123012
      schemas:
         InventoryDetails:
            type: objectBlockquote

securitySchemes 中的字段名称“api_key”必须与用于端点定义的安全性相匹配。

注意：“type”必须是以下类型之一：“apiKey”、“http”、“oauth2”、“OpenIdConnect”。在这种情况下，我选择了 apiKey 来表示 HMAC 安全性。

那么您有几种方法可以为您的 API 实施安全性。

所有已定义端点的安全性，安全性定义必须在根级别定义，使用在securitySchemes 中指定的名称。让阵列保持打开状态。

    info:
    servers:
      - url: 'https://stage.com'
        description: Stage Server
      - url: 'https://prod.com'
        description: Prod Server
    security: 
      - api_key: [ ]
    paths:

为每个请求定义安全性：

/coffee/hot/:  
  post:
    summary: Coffee request order
    description: Coffee a request order
    security: 
       - api_key: [ ]
    tags:
       - Starbuckin

在此示例中，我们为此 POST 请求端点启用“api_key”安全类型。

同时使用。如果您想删除任何请求的安全性，请将安全性定义留空，如下所示：

    /coffee/buildinfo:
        get:
          summary: Show the build information
          description: Show the detail build information
          tags:
            - Starbuckin
          security: [ ]
          responses:

最后，结果应该在启用了安全性的请求上显示一个安全锁图标。

【讨论】：