OAuth 2 Security Scheme in OpenAPI

OAuth 2 is a popular open authentication mechanism that supports an authentication flow allowing servers to authenticate on behalf of a user, and/or a whole application.

While more generally used for authenticating end-users (e.g.: Log in with Facebook), it is also used machine-to-machine flows where a whole application authenticates itself with the API (e.g. Connect Shopify to Xero).

OAuth 2 is considered more secure than other mechanisms due to its granted privileges through short-lived tokens that limit damage from intercepted tokens. Tokens that can only be used for a day can only cause damage for a day, and a well built API will not allow those tokens to be used to escelate privileges (change users password) so there’s less damage to be done whilst the token is valid.

The OAuth 2 protocol defines multiple ways of building a request against the tokenUrl endpoint, and supports mutliple flows at once so that different types of integrations can be set up for the same API.

OAuth 2 Security Scheme Object in OpenAPI

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

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

OAuth Flow Object in OpenAPI

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

The four OAuth 2 flows that OpenAPI v3.1 supports are:

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

Each flow object has its own configuration parameters, so let’s look at them individually.

Client Credentials Flow Object in OpenAPI

The Client Credentials flow is generally used for machine-to-machine communication where a specific user’s permission and context is not required. Think of an entire application integrating with a whole other application, to sync billing information or other organization-wide information.

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

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 security scheme using the authorizationCode flow:

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 security scheme using the password flow:

Implicit Flow Object in OpenAPI

The Implicit flow is generally used for browser/client-side applications that can’t keep a client secret, as in a browser all code and data is available to the user. This was popular for a while, but IETF’s OAuth working group recommends not using the implicit grant anymore. Read more about why here .

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

OAuth 2 Security Scheme With Multiple Flows in OpenAPI

If an API needs multiple OAuth 2 flows then that’s absolutely fine. To do this, describe each of the flows in the flows object. Here’s an example using the authorizationCode and clientCredentials flows:

If different endpoints supported different flows, then they would be split into different securitySchemes. In this example, the whole API is secured by clientCredentials, except for the /profile endpoint, which requires authorizationCode.

Scopes in OAuth 2 in OpenAPI

Scopes are used to define more granular permissions or access controls.

Sometimes this is very generic like read and write.

Some APIs focus on different resources:

• invoices
• customers
• orders

Some go even further and break scopes into resources and actions:

• invoices:read
• invoices:write
• invoices:delete
• customers:read
• customers:write
• customers:delete
• orders:read
• orders:write
• orders:delete

This not only makes sure people are not seeing things they should not be seeing, but limits accidental data loss when misconfigured applications go rogue.

The scopes are defined in the scopes object of the OAuth flow object, and the scopes required for a specific operation are defined in the security object of the operation.

No scopes

Scopes are optional, and an API may not use them at all. If that is the case the scopes can be defined as an empty object {}, and an empty list of scopes [] as the security requirement.

What about OAuth 2.1 and Device Authorization?

OAuth 2.1 is a simplified version of OAuth 2 that combines the best practices and removes the less secure flows. There are not many changes which are directly related to OpenAPI, the existing structure works fine.

For more information on OAuth 2.1, you can refer to the OAuth 2.1 specification  to understand the changes and improvements made in this version.

There is a new OAuth flow called Device Authorization, which is not yet supported in OpenAPI v3.1. This will be added in OpenAPI v3.2, which is currently in development.

For more information on the Device Authorization flow, take a look at the OAuth 2 Device Authorization Grant specification .