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 ObjectauthorizationCode
(previously,accessCode
in OpenAPI 2.0) - Authorization Code Flow Objectpassword
- Password Flow Objectimplicit
- 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
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
Last updated on