API Security Best Practices: Using OpenAPI to Improve API Security

The adoption of API specification frameworks like OpenAPI (OAS) encourages documentation best practices resulting in higher quality, more consistent API coding and improved API security. Historically, APIs were designed for machine-to-machine communications, and were rarely documented resulting in lower quality APIs and making it difficult to achieve the goals of catching security flaws earlier. Using a framework like the OAS automatically creates a centralized API documentation repository with standardized API definitions stored in a language-agnostic and machine consumable format that can be used by development and security teams alike to ensure coding consistency and address coding errors before they become exploits.

To help address both the quality and security challenges, organizations are using API specification frameworks like the OpenAPI specification (OAS) to create a centralized API documentation repository. The OAS standardizes API definitions in a language-agnostic and machine consumable format that can be used by development and security teams alike to ensure coding consistency and to uncover potential security gaps before publication or discovery by threat actors.

API Specification Adoption Trends: Slow Adoption, Yet High Perceived Value

In a Pulse survey of 100 executives and CXOs familiar with their API documentation and specifications process, we found that most organizations were in the early stages of specification frameworks adoption, citing numerous barriers including too many priorities. However, the survey does highlight that there is a high value derived from adoption – specifically better quality, security, and group collaboration.

Bridging the Gap with OAS

The OpenAPI specification documents all of the components referenced by the API including servers, methods, endpoints, parameters, requests and their responses. The remainder of the blog will discuss how the documentation of each API component can help developers and security teams improve API coding quality and reduce the number of potential security flaws.

Servers

Depending on the development phase, APIs, like any application are hosted in different environments (e.g., Dev, QA, UAT, Prod). In order to validate functionality and perform initial tests, it is not uncommon to use real customer data in non-production environments. Unfortunately, non-production environments are not subject to stringent testing, resulting in the data being inadvertently exposed to the Internet.

As shown in the code snippet below, the OpenAPI specification allows development teams to document their servers (Development, Staging, Production) and their protocol scheme (HTTPS) to ensure secure communication.

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

As the organizations roll out new servers for an API, they can keep the servers section up-to-date to enable the security teams to properly secure them.

Methods and Paths

Each method and path combination in an API defines the unique business logic or functionality that is going to be exposed to the public as an API endpoint. Examples include account registration or login, updating credit card numbers or user profiles, reviewing past orders, filing an insurance claim, and so on. Quite often developers make mistakes and end up implementing or exposing more methods and endpoints than they intended to, resulting in the introduction of added security risks. For example, in addition to exposing a read only GET endpoint, a developer mistakenly exposes a POST, PUT or DELETE endpoint that can lead to modification or deletion of customer data, an API risk documented as #9 on the OWASP API Security Top 10, Improper Assets Management.

As shown in the code snippet below, the OpenAPI specification has a mechanism to specify all endpoints and methods, which can be used by development and security teams alike to eliminate unintended endpoint exposure.

"paths": {
  "/pets": {
    "get": {
      "summary": "List all pets",
      "operationId": "listPets",
       ...
    },
    "post": {
      "summary": "Create a pet",
      "operationId": "createPets",
      ...
    }
  }
}

Request Parameters

Each resource referenced in an API can take dynamic values from the request using parameters. Just like any other HTTP request, these parameters can be in the path, query or body of the request. The code snippet below shows how an API specification can be used to properly document all required and optional endpoint parameters and lock down all incoming API requests. Any request with additional parameters can be either blocked or stripped out.

"parameters": [

  {
    "name": "limit",
    "in": "query",
    "description": "How many items to return at one time (max 100)",
    "required": false,
    "type": "integer",
    "format": "int32"
  }
]

Like the path and query parameters, dynamic values can be passed in the request body as well. The OAS specifies a way to define the body of the request.

"requestBody":{
  "description":"Create a new pet in the store",
  "content":{
    "application/json":{
      "schema":{
        "$ref":"#/components/schemas/Pet"
      }
    },
    "application/x-www-form-urlencoded":{
      "schema":{
        "$ref":"#/components/schemas/Pet"
      }
    }
  },
  "required":true
}

Response Body

Each API response should be documented with the best practice being to provide as LITTLE information as possible in the response. OpenAPI specification provides a method to specify the response structure and its individual fields. If an undocumented, additional field gets introduced for any reason, it can be flagged by the security tools with the help of this specification.

"responses":{
  "200":{
    "description":"Successful operation",
    "content":{
    "application/xml":{
       "schema":{
          "$ref":"#/components/schemas/Pet"
        }
      },
      "application/json":{
        "schema":{
          "$ref":"#/components/schemas/Pet"
        }
      }
    }
  }
}

Security Schemes

Interestingly, one of the most critical elements in developing an API is one of the flaws that is most commonly exposed or discovered: Broken User Authentication. Classified as #2 on the OWASP API Security Top 10 list, these authentication errors allow attackers to compromise authentication tokens or to exploit implementation flaws to assume other user identities, temporarily or permanently. Compromising a system’s ability to identify the client/user, compromises API security overall.

"securitySchemes":{
  "petstore_auth":{
    "type":"oauth2",
    "flows":{
      "implicit":{
        "authorizationUrl":"https://petstore3.swagger.io/oauth/authorize",
        "scopes":{
          "write:pets":"modify pets in your account",
          "read:pets":"read your pets"
        }
      }
    }
  },
  "api_key":{
    "type":"apiKey",
    "name":"api_key",
    "in":"header"
  }
}

Summary

Shift left critics say that the effort is failing to catch all the security flaws, placing the bulk of the blame on the development team. The reality is that shift left IS working, it IS catching flaws earlier. Even the most perfectly coded API is susceptible to an attack, which is where the security team comes into shield the right. By working with the development team in tandem, the groups can use a specification framework to document the APIs, understand the functionality, collaborate on testing to uncover and remediate possible security gaps before publication or discovery.