Warnings in OpenAPI 3.0 in postman

Introduction

Postman is a top-rated API platform that is used for building and using APIs. It is user-friendly as it simplifies each step of the API lifecycle and streamlines the collaboration to help the user create better APIs that too faster. It allows the user to perform various tasks like making requests, testing APIs, building and managing APIs, etc.

In today's article, we will use Postman to identify any potential security and formatting issues when defining our API. Below, we will observe a list describing possible warning messages and potential ways to resolve them.

Broken object-level authorization

Scope for OAuth scheme used in the security field is not defined in the securityScheme declaration

Issue description

The OAuth2 scopes used in the global security field need to be defined in the security schemes field. Otherwise, an attacker can introduce their scopes to fill the gap and exploit the system.

Possible fix

Make sure that all the OAuth2 scopes used are defined in the OAuth2 security scheme.

Resolution

security:
  - OAuth2:
    - read
    - write
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            read: read objects in your account
            write: write objects to your account

Broken user authentication

Security field is not defined

Issue description

If the global security field isn't defined, the API doesn't require any authentication by default. Anyone can access the API operations that don't have a security field defined.

Possible fix

The security field needs to be defined in the schema.

Resolution

openapi: 3.0.0
info:
paths:
security:
    - testAuth : []

Security field does not contain any item

Issue description

If the security field contains an empty array, no security scheme is applied to the operations by default.

Possible fix

The security field needs to contain at least one item in the array.

Resolution

openapi: 3.0.0
info:
paths:
security:
    - testAuth : []

Security field does not contain any scheme

Issue description

An empty object in the security field deactivates the authentication completely. Without security fields defined for each operation, anyone can access the API operations without any authentication.

Possible fix

Security field array items can't contain an empty object.

Resolution

openapi: 3.0.0
info:
paths:
security:
    - testAuth : []

Security scheme object not defined

Issue description

The components object of the API doesn't declare any security schemes which can be used in the security field of the API or individual operations.

Possible fix

Security schemes need to be defined in the schema of the component.

Resolution

components:
  securitySchemes:
    testAuth:
      type: http
      scheme: basic

Security scheme object does not contain any scheme

Issue description

An empty object in the reusable security schemes means that no authentication scheme is defined for each operation, anyone can access the API operations without any authentication.

Possible fix

Security schemes need to contain at least one item in the object.

Resolution

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

Excessive data exposure

API accepts credentials from OAuth authentication in plain text

Issue description

The access tokens are sent as plain text over an unencrypted network. Attackers can intercept the access tokens by listening to the network traffic in a public Wi-Fi network.

Possible fix

Make sure that the server URL is a valid URL and uses HTTPS protocol.

Resolution

servers:
  - url: https://my.api.example.com/
    description: API server
# ...
components:
  securitySchemes:
    OAuth2:
      type: oauth2
# ...
security:
  - OAuth2:
      - write
      - read

API accepts credentials from OpenID Connect authentication in plain text

Issue description

The credentials are sent as plain text over an unencrypted network. Attackers can intercept the access tokens by listening to the network traffic in a public Wi-Fi network.

Possible fix

Make sure that the server URL is a valid URL and uses HTTPS protocol.

Resolution

components:
 securitySchemes:
  OpenIdScheme:
   type: openIdConnect
   openIdConnectUrl: https://example.com/connect
paths:
 "/pets":
  post:
   operationId: addPet
   servers:
   - url: https://example.com/
     description: API server
   security:
   - OpenIdScheme: []

API accepts credentials from OAuth 1.0 authentication in plain text

Issue description

The authentication tokens are sent as plain text over an unencrypted channel. Attackers can intercept the token by listening to the network traffic in a public Wi-Fi network.

Possible fix

Make sure that the server URL is a valid URL and uses HTTPS protocol.

Resolution

servers:
  - url: https://my.api.example.com/
    description: API server
#...
components:
  securitySchemes:
    OAuth1:
      type: http
      scheme: oauth
#...
security:
  - OAuth1: []

API accepts API key in plain text

Issue description

API keys are sent as plain text over an unencrypted channel. Attackers can intercept API key by listening to the network traffic in a public Wi-Fi network.

Possible fix

Make sure that the server URL is a valid URL and uses HTTPS protocol.

Resolution

servers:
  - url: https://my.api.example.com/
    description: API server
#...
components:
  securitySchemes:
    AuthKeyAuth:
      type: apiKey
      name: api-key
      in: header
#...
security:
  - AuthKeyAuth: []

API accepts auth credentials in plain text

Issue description

The credentials are sent as plain text over an unencrypted network. Attackers can intercept the credentials by listening to the network traffic in a public Wi-Fi network.

Possible fix

Make sure that the server URL is a valid URL and uses HTTPS protocol.

Resolution

servers:
- url: https://example.com/
  description: Example server
components:
 securitySchemes:
  BasicAuth:
   type: http
   scheme: basic
security:
- BasicAuth: []

Improper assets management

The deprecated OAuth 1.0 scheme is used

Issue description

The security scheme uses OAuth 1.0 authentication which has been deprecated and replaced by OAuth 2.0.

Possible fix

Make sure that the security scheme isn't using the deprecated OAuth 1.0 authentication.

Resolution

components:
  securitySchemes:
    OauthFlow:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://my.auth.example.com/
          tokenUrl: https://my.token.example.com/
          scopes:
            write: modify data
            read: read data

OAuth authentication uses the deprecated implicit flow

Issue description

In OAuth implicit flow, the authorization server issues access tokens in the authorization request’s response. Attackers can intercept API calls and retrieve the access tokens to make other API calls.

Possible fix

It's recommended to use authorizationCode flow. Make sure that the OAuth authentication scheme isn't using the implicit flow.

Resolution

components:
  securitySchemes:
    OauthFlow:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://my.auth.example.com/
          tokenUrl: https://my.token.example.com/
          scopes:
            write: modify data
            read: read data

OAuth authentication uses the deprecated password flow

Issue description

OAuth password grant flow uses the user’s credentials to retrieve the access token. Attackers can intercept API calls and retrieve the access tokens to make other API calls.

Possible fix

It's recommended to use authorization code flow. Make sure that the OAuth authentication scheme isn't using the password grant flow.

Resolution

components:
  securitySchemes:
    OauthFlow:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://my.auth.example.com/
          tokenUrl: https://my.token.example.com/
          scopes:
            write: modify data
            read: read data

API information

API must have contact information available

Issue description

Your API schema's info object doesn't contain a contact object, which contains contact information including a name and email address.

Possible fix

Although contact information isn't required, including it allows your users to contact you. Add a contact object to your API schema's info object.

Resolution

info:
  contact:
    name: Project Name
    email: author@company.com
    url: https://example.com

API must have a contact email available

Issue description

Your API schema's contact object doesn't contain an email address for the contact person or organization.

Possible fix

Although contact information isn't required, including it allows your users to communicate with you. Add an email address to your API schema's contact object.

Resolution

info:
  contact:
    name: Project Name
    email: author@company.com
    url: https://example.com

API must have a contact name available

Issue description

Your API schema's contact object doesn't contain a name for the contact person or organization.

Possible fix

Although contact information isn't required, including it allows your users to communicate with you. Add a name to your API schema's contact object.

Resolution

info:
  contact:
    name: Project Name
    email: author@company.com
    url: https://example.com

Operations

All operations should have descriptions

Issue description

One or more operation objects in your API schema doesn't have a description.

Possible fix

A verbose explanation of the operation's behavior provides your users with important context. Add a description for each operation object.

Resolution

paths:
  '/health_check':
    get:
      ...
      description: health_check endpoint description.

All operations should have summaries

Issue description

One or more operation objects in your API schema doesn't have a summary.

Possible fix

A short summary of what the operation does provides your users with important context. Add a summary for each operation object.

Resolution

paths:
  '/health_check':
    get:
      ...
      summary: health_check endpoint summary

Operation summaries shouldn't end with a period

Issue description

One or more operations object in your API schema contains a summary that ends with a period (.)

Possible fix

Remove the final period from all summaries at the operations object level in your API schema.

Resolution

paths:
  '/health_check':
    get:
      ...
      summary: health_check endpoint summary

Models

Request body examples should only reference components

Issue description

Multiple request body objects in your API schema contain examples that should be consolidated into an examples section in the components object.

Possible fix

Consolidate all the examples from your request bodies into an examples section in the components object.

Resolution

description: user to add to the system
content:
  'application/json':
    schema:
      $ref: '#/components/schemas/User'
    examples:
       $ref: '#/components/examples/SampleUser'

Response schema should only reference components

Issue description

Multiple response objects in your API schema contain schemas that should be consolidated into a schemas section in the components object.

Possible fix

Consolidate all the schemas from your response objects into a schemas section in the components object.

Resolution

description: user to add to the system
content:
  'application/json':
    schema:
      $ref: '#/components/schemas/User'

All schemas should have descriptions

Issue description

One or more schema objects in your API schema's components object doesn't contain a description.

Possible fix

Add a description for every schema object in your API schema.

Resolution

components:
  schemas:
    GeneralError:
      type: object
      description: universal error object

Frequently Asked Questions

What is a collection in Postman?

In Postman, a collection is used to group related requests. It facilitates organizing requests into folders in a methodical manner.

What kinds of requests can you make with Postman?

Request Method, Request URL, Request Headers, Request Body, Pre-request Script, and Tests are all included in an HTTP request method.

What does Postman's endpoint mean?

You may include Postman in your development toolchain by integrating it with the Postman API endpoints. Through the API, you can add and run monitors, update environments, add and run new collections, and update existing collections. You can now access data kept in your Postman account programmatically.

What does Postman's collection mean?

A collection of saved requests is called a Postman Collection. Every request you make in Postman is recorded in the sidebar's History tab.

Conclusion

We hope this blog has helped you enhance your Knowledge about Postman and various warnings need to be understood during any error in Postman 3.0

See Basics of C++ with Data Structure, DBMS, Operating System by Coding Ninjas, and keep practicing on our platform Coding Ninjas Studio.

If you think you are ready for the tech giants company, check out the mock test series on code studio.

You can also refer to our Guided Path on Coding Ninjas Studio to upskill yourself in domains like Data Structures and Algorithms, Competitive Programming, Aptitude, and many more! You can also prepare for tech giants companies like Amazon, Microsoft, Uber, etc., by looking for the questions asked by them in recent interviews. If you want to prepare for placements, refer to the interview bundle. If you are nervous about your interviews, you can see interview experiences to get ideas about these companies' questions.

Nevertheless, you may consider our premium courses to give your career an edge over others!

Do upvote our blogs if you find them helpful and engaging!

Happy Learning!