authentication - 带有自定义 header 名称的 Swagger/OpenAPI Bearer 身份验证

Question

我正在使用 OpenAPI 定义现有 API ( Samanage) 的(一小部分)以协助完成一些集成工作。

我需要使用 Bearer auth 进行身份验证，但通过在 Authorize 之外的 header 中发送 token 。

服务器希望在名为 X-Samanage-Authorization 的 header 中进行 Bearer 身份验证，如下例所示:

curl -H "X-Samanage-Authorization: Bearer <TokenGoesHere>" -H 'Accept: application/vnd.samanage.v2.1+json' -H 'Content-Type: application/json' -X GET https://api.samanage.com/incidents.json

我知道 https://swagger.io/docs/specification/authentication/bearer-authentication/ ，但它似乎并没有完全帮助我。

这个(OpenAPI 3)

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
...
security:
- bearerAuth: []

产生一个名为 default (Authorization) 的身份验证 header

curl -X GET "https://api.samanage.com/incidents/12341234.json" -H "accept: application/json" -H "Authorization: Bearer <TokenGoesHere>"

然后失败 (401)。

我觉得我想要这个:

components:
  securitySchemes:
    bearerAuth:
      type: http
      name: X-Samanage-Authorization
      in: header
      scheme: bearer

但这在 Swagger 编辑器中验证失败，因为我相信 http 的 type 不允许 name 组件(例如apiKey 会)。我无法完全理解文档 here老实说。

我确实读过 Specification Extensions但作为 OpenAPI 的新手，我找不到任何关于如何实际实现我需要的示例。

非常感谢任何见解!

Answer 1

type: http 用于 RFC 7235 定义的 HTTP 身份验证和 IANA HTTP Authentication Scheme Registry .根据定义，HTTP 身份验证使用 Authorization header 。

要使用自定义 header 名称，您需要将其定义为 API key (类型:apiKey):

components:
  securitySchemes:
    bearerAuth:
      type: apiKey
      name: X-Samanage-Authorization
      in: header

请注意，由于它是一个非标准的 Bearer 方案，因此客户端需要手动将“Bearer”前缀添加到 token 值。例如，当您在 Swagger UI 中单击“授权”时，您需要输入“Bearer TOKEN”而不仅仅是“TOKEN”。