After mastering input and output modeling like a Jedi, let’s see how we can describe API’s security with the OpenAPI specification’s.

Writing OpenAPI (fka Swagger) Specification tutorial

This tutorial is composed of several posts:

In previous parts we’ve learned to write efficiently highly accurate interface description, in this seventh part we’ll learn how to describe how an API is secured.

All tutorial’s files are available on GIST.

If you’re a bit lost in the specification, take a look at my [visual documentation:

Security definitions

Following (almost) the same principle used with parameters and definitions, security can be defined and then used on different levels. Security definition takes place on specification’s root level in securityDefinition section. It contains a list of named security definitions. Each definition can be of type:

  • basic for Basic Authentication
  • apiKey when using an API key to secure the API
  • oauth2 for Oauth 2

Basic Authentication

To define a basic security it’s fairly easy, we only have to set its type to basic:

In this example we have defined three security definitions (UserSecurity, AdminSecurity and MediaSecurity), each of them is of basic type.

API Key

To define an apiKey security we have to:

  • Set type to apiKey
  • Indicate where the API ley is located with in. An API can be in a header or a query parameter
  • And then give the parameter’s name

In this example, we have defined three security definitions of apiKey type:

  • UserSecurity uses a header parameter named SIMPLE-API-KEY
  • AdminSecurity uses a header parameter named ADMIN-API-KEY
  • MediaSecurity uses a query parameter named media-api-key

Oauth 2

Flow and URLs

When defining an oauth2 security definition, we can define the Oauth2 flow used and corresponding authorizationUrl and/or tokenUrl depending on the chosen flow:

Flow Required URLs
implicit authorizationUrl
password tokenUrl
application tokenUrl
accessCode authorizationUrl and tokenUrl

In this example we have defined a OauthSecurity security definition of oauth2 type using an accessCode flow with an authorizationUrl and a tokenUrl.

Scopes

We can also define scopes by using a hashmap, the key is the scope’s name and the value is its description.

In this example, we’ve added three scopes (admin, user and media) to our OauthSecurity security definition

Using security definitions

Once we have described security definitions in securityDefinition we can apply them to the overall API or to specific operations with the security sections. When we apply a security definition to an operation, it overrides API security.

Basic Authentication

Let’s see how we can use a basic security definition.

API level

In this example the security definition which apply to ALL API operations is UserSecurity:

Operation level

As GET /persons operation do not define a security, it’s the UserSecurity defined on top level which applies:

On POST /persons operation, the top level security is overridden by AdminSecurity:

On POST /images operation, the top level security is also overridden, but this time it’s by MediaSecurity:

API Key

We can do exactly the same things with an API key security definition.

API level

In this example the security definition which apply to ALL API operations is UserSecurity:

Operation level

As GET /persons operation do not define a security, it’s the UserSecurity defined on top level which applies:

On POST /persons operation, the top level security is overridden by AdminSecurity:

On POST /images operation, the top level security is also overridden, but this time it’s by MediaSecurity:

Oauth 2

With an oauth2 the principle is the same but you can also define which scope(s) you use.

API level

In this example the security definition which apply to ALL API operations is OauthSecurity with the user scope:

Operation level

As GET /persons operation do not define a security, it’s the OauthSecurity with userscope defined on top level which applies:

On POST /persons operation, the top level security scope is overridden by admin:

On POST /images operation, the top level security is also overridden, but this time it’s by media:

Using multiple security types

It’s not mandatory to define a single type of security definition and use only one at a time. The examples below show how we can define security definitions of different types and use more than one on operations.

Security definitions

Here we define there different types of security:

Global security

Then we choose to apply both of them globally: It means that a consumer can call any operation (which do not override security) with one of those two security types.

Overriding global security

As GET /persons operation do not define a security, it’s the Oauth 2 OauthSecurity with userscope OR the basic authentication LegacySecurity defined on top level which applies:

On POST /persons operation, the top level security scope Oauth 2 OauthSecurity is overridden by admin and consumer can also still use the basic authentication LegacySecurity:

On POST /images operation, the top level security is fully overridden by the API Key MediaSecurity:

Conclusion

You now have mastered security. With this new post you are now a full expert when it comes to describe an API interface with the OpenAPI specification. But an interface contract alone may not be easy to understand without some explainations. In next post we’ll learn how to document this interface description (coming soon) to ease its understanding.