OAuth 2.0
OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server. GitHub, Google, and Facebook APIs notably use it. OAuth relies on authentication scenarios called flows, which allow the resource owner (user) to share the protected content from the resource server without sharing their credentials. For that purpose, an OAuth 2.0 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner. For more information about OAuth 2.0, see oauth.net and RFC 6749.
Flows
The flows (also called grant types) are scenarios an API client performs to get an access token from the authorization server. OAuth 2.0 provides several flows suitable for different types of API clients:
Authorization code – The most common flow, mostly used for server-side and mobile web applications. This flow is similar to how users sign up into a web application using their Facebook or Google account.
Implicit – This flow requires the client to retrieve an access token directly. It is useful in cases when the user’s credentials cannot be stored in the client code because they can be easily accessed by the third party. It is suitable for web, desktop, and mobile applications that do not include any server component.
Resource owner password credentials (or just password) – Requires logging in with a username and password. Since in that case the credentials will be a part of the request, this flow is suitable only for trusted clients (for example, official applications released by the API provider).
Client Credentials – Intended for the server-to-server authentication, this flow describes an approach when the client application acts on its own behalf rather than on behalf of any individual user. In most scenarios, this flow provides the means to allow users specify their credentials in the client application, so it can access the resources under the client’s control.
Describing OAuth 2.0 Using OpenAPI
To describe an API protected using OAuth 2.0, first, add a security scheme with type: oauth2
to the global components/securitySchemes
section. Then add the security
key to apply security globally or to individual operations:
The flows
keyword specifies one or more named flows supported by this OAuth 2.0 scheme. The flow names are:
authorizationCode
– Authorization Code flow (previously calledaccessCode
in OpenAPI 2.0)implicit
– Implicit flowpassword
– Resource Owner Password flowclientCredentials
– Client Credentials flow (previously calledapplication
in OpenAPI 2.0)
The flows
object can specify multiple flows, but only one of each type. Each flow contains the following information:
Field Name | Description | Applies to flows | |||
---|---|---|---|---|---|
|
|
|
| ||
| The authorization URL to use for this flow. Can be relative to the API server URL. | + | + | - | - |
| The token URL to use for this flow. Can be relative to the API server URL. | + | - | + | + |
| Optional. The URL to be used for obtaining refresh tokens. Can be relative to the API server URL. | + | + | + | + |
The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. | + | + | + | + |
About Scopes
With OpenAPI 3.0, a user can grant scoped access to their account, which can vary depending on the operation the client application wants to perform. Each OAuth access token can be tagged with multiple scopes. Scopes are access rights that control whether the credentials a user provides allow to perform the needed call to the resource server. They do not grant any additional permissions to the client except for those it already has. Note: In the authorization code and implicit flows, the requested scopes are listed on the authorization form displayed to the user. To apply the scopes, you need to perform two steps:
Define all supported scopes in your OAuth security definition in the
components/securitySchemes
section:List the scopes required by each operation in the
security
section of that operation:If all API operations require the same scopes, you can add
security
on the root level of the API definition instead:
No Scopes
Scopes are optional, and your API may not use any. In this case, specify an empty object {}
in the scopes definition, and an empty list of scopes []
in the security
section:
Relative Endpoint URLs
In OpenAPI 3.0, authorizationUrl
, tokenUrl
and refreshUrl
can be specified relative to the API server URL. This is handy if these endpoints are on same server as the rest of the API operations.
Relative URLs are resolved according to RFC 3986. In the example above, the endpoints will be resolved to:
Security Scheme Examples
Authorization Code Flow
The authorization
flow uses authorizationUrl
, tokenUrl
and optional refreshUrl
. Here is an example for Slack API:
Implicit Flow
implicit
flow defines authorizationUrl
that is used to obtain the access token from the authorization server. Here is an example:
Resource Owner Password Flow
The password
flow uses tokenUrl
and optional refreshUrl
. Here is an example:
Client Credentials Flow
The clientCredentials
flow uses tokenUrl
and optional refreshUrl
. Here is an example for Getty Images API:
Multiple Flows
Below is an example of the OAuth 2.0 security definition that supports multiple flows. The clients can use any of these flows.
Frequently Asked Questions
Should I additionally define authorizationUrl
and tokenUrl
as API operations?
authorizationUrl
is not an API endpoint but a special web page that requires user input. So, it cannot be described using OpenAPI. Still, you can describe tokenUrl
if you need it.
Should authorizationUrl
and tokenUrl
include query string parameters, such as grant_type
, client_id
and others?
The OpenAPI Specification does not state this, so it is up to you and the tools you use.
Last updated