Authentication strategies

OpenAPI 3.0 uses the term securitySchemes for authentication and authorization schemes. It lets you describe how the APIs are protected using the following security schemes:

• HTTP authentication schemes (they use the Authorization header):

  • Basic

  • Bearer

• API keys in headers, query string or cookies

• OAuth 2

Describing security

Security is described using the securitySchemes and security keywords. You use securitySchemes to define all the security schemes your API supports, and then use security to apply specific scheme(s) to the entire API or individual operations.

1. Defining securitySchemes

   All security schemes used by the API must be defined in the global components/securitySchemes section. This section contains a list of named security schemes, where each scheme can be of the following types:

   • http – for Basic, Bearer

   • apiKey – for API keys

   • oauth2 – for OAuth 2

2. Applying security

After you have defined the security schemes in the securitySchemes section, you can apply them to the whole API or individual operations by adding the security section on the root level or operation level, respectively.

• When used on the root level, security applies the specified security schemes globally to all API operations, unless overridden on the operation level.

• In the following example, the API calls can be authenticated using either an API key or OAuth 2. The ApiKeyAuth and OAuth2 names refer to the schemes previously defined in securitySchemes.

For each scheme, you specify a list of security scopes required for the API calls. Scopes are used only for OAuth 2 and OpenID Connect Discovery; other security schemes use an empty array [] instead.

Basic Authentication

Basic authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word Basic followed by a space and a base64-encoded string username:password.

You can describe Basic authentication as follows:

 The first section, securitySchemes, defines a security scheme named basicAuth (an arbitrary name).

• This scheme must have type: http and scheme: basic.

• The security section then applies Basic authentication to the entire API.

• The square brackets [] denote the security scopes used; the list is empty because Basic authentication does not use scopes.

API Keys

Some APIs use API keys for authorization. An API key is a token that a client provides when making API calls.

The key can be sent in the query string:

or as a request header:

or as a cookie:

API keys are described as follows:

This example defines an API key named X-API-Key sent as a request header X-API-Key: <key>.

• The key name ApiKeyAuth is an arbitrary name for the security scheme (not to be confused with the API key name, which is specified by the name key).

• The name ApiKeyAuth is used again in the security section to apply this security scheme to the API.The securitySchemes section alone is not enough; you must also use security for the API key to apply this authentication.

  The securitySchemes section alone is not enough; you must also use security for the API key to apply this authentication.

Extension: Adding Prefix To API Key

This extension enables the addition of a prefix to the API key or token when making API calls.

Bearer Authentication

Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens.

The client must send this token in the Authorization header when making requests to protected resources:

Bearer authentication is a security scheme with type: http and scheme: bearer. 

OAuth 2

OAuth 2 is an authorization protocol that gives an API client limited access to user data on a web server.

• OAuth relies on authentication scenarios called flows that allow the resource owner (user) to share the protected content from the resource server without sharing its credentials.

• For that purpose, an OAuth 2 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner.

Flows

The flows (also called grant types) are scenarios an API client performs to get an access token from the authorization server.

OAuth 2 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 a 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 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.

To describe an API protected using OAuth 2.0, do the following:

1. Add a security scheme with type: oauth2 to the global components/securitySchemes section.
2. Add the security key to apply security globally or to individual operations:

 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
		authorizationCode	implicit	password	clientCredentials
authorizationUrl	The authorization URL to use for this flow. Can be relative to the API server URL.	YES	YES	NO	NO
tokenUrl	The token URL to use for this flow. Can be relative to the API server URL.	YES	NO	YES	YES
refreshUrl	Optional. The URL to be used for obtaining refresh tokens. Can be relative to the API server URL.	YES	YES	YES	YES
scopes	The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.	YES	YES	YES	YES

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:

Extension: Additional Parameter Definition

This extension element defines extra parameters to retrieve from:

• Token Response

• Callback Request

• Access Token Decoding

These parameters are persist as an account parameter in the OAuthAccount entity which can be used for Server URL templating as mentioned on the API servers (Environments) page.

Type	YAML	Description
Token Response	<ch:codesample> </ch:codesample>	Specifies the list of parameters to retrieve from the access token response. name: Name of the parameter. type: Type of the parameter. Can be "header", or "body".
Callback Request	<ch:codesample> </ch:codesample>	Specifies parameters to retrieve from the callback request (containing the code value) received by the Adeptia application during the authorization code grant flow for obtaining the access token. name: Name of the parameter type: Type of the parameter. Can be “query“, or "header".
Access Token Decoding	<ch:codesample> </ch:codesample>	Specifies the list of parameters to be decoded from the received JWT access token.

Here is an example: