OAuth 2.0 Security Scheme in OpenAPI

OAuth 2.0 is a popular open authentication mechanism that supports an authentication flow allowing servers to authenticate on behalf of a user or organization.

While more generally used for authenticating clients and end-users, it is sometimes used in machine-to-machine applications, but is less popular than other security schemes due to the added complexity of the authentication flows.

OAuth 2.0 is considered more secure than other mechanisms due to its granted privileges through short-lived tokens that limit damage from intercepted tokens.

The OAuth 2.0 protocol defines multiple ways of building a request against the tokenUrl endpoint.

OAuth 2.0 Security Scheme Object in OpenAPI

The fields for an OAuth 2.0 security scheme are as follows:

Below is an example of an OAuth 2.0 security scheme using the clientCredentials flow:

components:
  securitySchemes:
    clientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://speakeasy.bar/oauth2/token/
          scopes: {}
security:
  - clientCredentials: []

OAuth Flow Object in OpenAPI

The value of the flows object is a map of OAuth 2.0 flow objects.

The four supported OAuth 2.0 flows are:

• implicit - Implicit Flow Object
• password - Password Flow Object
• clientCredentials (previously, application in OpenAPI 2.0) - Client Credentials Flow Object
• authorizationCode (previously, accessCode in OpenAPI 2.0) - Authorization Code Flow Object

Each flow object has its own configuration parameters, as described below.

Implicit Flow Object in OpenAPI

The Implicit flow is generally used for single-page applications that can’t keep a client secret as all the application code is available to the user.

The example below shows an OAuth 2.0 security scheme using the implicit flow:

components:
  securitySchemes:
    implicit:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://speakeasy.bar/oauth2/authorize/
          refreshUrl: https://speakeasy.bar/oauth2/refresh/
          scopes:
            read: Grants read access
            write: Grants write access

Password Flow Object in OpenAPI

The Password flow is generally used for trusted first-party clients that can securely store the client secret.

The example below shows an OAuth 2.0 security scheme using the password flow:

components:
  securitySchemes:
    password:
      type: oauth2
      flows:
        password:
          tokenUrl: https://speakeasy.bar/oauth2/token/
          refreshUrl: https://speakeasy.bar/oauth2/refresh/
          scopes:
            read: Grants read access
            write: Grants write access

Client Credentials Flow Object in OpenAPI

The Client Credentials flow is generally used for machine-to-machine communication where a specific user’s permission is not required.

The example below shows an OAuth 2.0 security scheme using the clientCredentials flow:

components:
  securitySchemes:
    clientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://speakeasy.bar/oauth2/token/
          refreshUrl: https://speakeasy.bar/oauth2/refresh/
          scopes:
            read: Grants read access
            write: Grants write access

Authorization Code Flow Object in OpenAPI

The Authorization Code flow is generally used for server-side applications where the client secret can be securely stored.

The example below shows an OAuth 2.0 security scheme using the authorizationCode flow:

components:
  securitySchemes:
    authorizationCode:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://speakeasy.bar/oauth2/authorize/
          tokenUrl: https://speakeasy.bar/oauth2/token/
          refreshUrl: https://speakeasy.bar/oauth2/refresh/
          scopes:
            read: Grants read access
            write: Grants write access

OAuth 2.0 Security Scheme With Multiple Flows in OpenAPI

You can define an OAuth 2.0 security scheme with multiple flows by specifying each flow in the flows object.

The example below shows an OAuth 2.0 security scheme using the authorizationCode and clientCredentials flows:

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://speakeasy.bar/oauth2/authorize/
          tokenUrl: https://speakeasy.bar/oauth2/token/
          refreshUrl: https://speakeasy.bar/oauth2/refresh/
          scopes:
            read: Grants read access
            write: Grants write access
        clientCredentials:
          tokenUrl: https://speakeasy.bar/oauth2/token/
          refreshUrl: https://speakeasy.bar/oauth2/refresh/
          scopes:
            read: Grants read access
            write: Grants write access
security:
  - oauth2: []

Scopes in OAuth 2.0 in OpenAPI

Scopes are used to define the permissions that a client has when accessing a resource. The scopes are defined in the scopes object of the OAuth flow object.

The scopes required for a specific operation are defined in the security object of the operation.

The example below shows an OAuth 2.0 security scheme with scopes:

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://speakeasy.bar/oauth2/authorize/
          tokenUrl: https://speakeasy.bar/oauth2/token/
          refreshUrl: https://speakeasy.bar/oauth2/refresh/
          scopes:
            read: Grants read access
            write: Grants write access
paths:
  /drinks:
    get:
      operationId: listDrinks
      summary: Get a list of drinks
      # Operation requires read scope
      security:
        - oauth2:
            - read