Testing API routes with HMAC-SHA256 authentication in OpenAPI (Swagger)

Question

I am trying to generate OpenAPI (Swagger) documentation for my API routes which require HMAC-SHA256 authentication. This means that I have to include Authorization header for every request which consists of API key and generated HMAC signature separated by colon (e.g. Authorization: API_KEY:GENERATED_SIGNATURE).

I can easily generate the needed signature with JavaScript, but I cannot figure out how to add "key" and "secret" input fields in Swagger-UI "Authorize" pop-up and how to finally add it to Authorization header in each request.

Is something like this possible with OpenAPI Specification v3 at all?

Answer 1

I would NOT post any keys and/or secrets in the Open API Specs, that could lead to a security issue. That type of information should be communicated separately from the API documentation and on a secure line.

I didn't find many examples to show how an apiKey is at least enabled, so here is one way of defining the HMAC Security or an apiKey. (Using Open API Specs 3.0)

At the root level under components, the 'securitySchemes' needs to be defined. (This is required to get this to work.)

   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

The field name ‘api_key’ in the securitySchemes must match the security used for the endpoint definition. 

Note: The ‘type’ must be one of these types: “apiKey”, “http”, “oauth2”, “OpenIdConnect”. I’ve picked apiKey in this case to represent the HMAC security.  

Then you have a few ways to implement security for your APIs.   

1. Security for ALL defined endpoints, the security definition must be defined at the root level, using the name specified in the securitySchemes.  Just leave the array open.

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

2. Defined security for each request:

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

In this example, we are enabling the 'api_key' security type for this POST request endpoint.

3. Use Both.  If you want to remove security for any of the requests, leave the security definition empty like below:

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

In the end, the result should show a secure lock icon on the request where the security is enabled.