1.3 Authentication & Authorisation Basics

1.3 Authentication & Authorisation Basics

Before looking at the technical solutions to API authentication and authorisation, this section will provide an introduction that illustrates the situations where authentication and authorisation are appropriate.

Authorisation and authentication are intrinsically linked inside the OAuth framework which in itself is regarded as synonymous with securing APIs. OAuth uses its own terminology which is worth becoming familiar with before adopting an OAuth approach.

As the OAuth framework is a commonly accepted approach to the securing of modern APIs (large companies like Google, Microsoft and Twitter use it), this section also covers an introduction to OAuth.

1.3.1 OAuth 2.0 Basics

OAuth provides a more comprehensive and extensible approach to security than some of the basic authentication and authorisation mechanisms. Based on security tokens, it can be used for delegated authority such as enabling a mobile application to act on behalf of its user.

The IT industry perceive the need for any production quality API security framework to be based on OAuth 2.0. In reality OAuth 2.0 is a delegated authorisation framework but it provides the foundations on which secure services can be built in order to provide the complete security solution.

OAuth requires some fundamental security components in order to work, and has its own terminology for describing these components and their roles:

Illustration of OAuth 2.0 components 

Figure 5: OAuth 2.0 components

  1. Resource Owner – the person who has the right to grant a third party (e.g. a consuming application) access to a protected resource (e.g. information about themselves). Quite often the resource owner is the customer.
  2. Client (or Client Application) – A consuming application requesting access to a protected resource on behalf of a third party e.g. a mobile application on a user’s (third party) smartphone or a web application accessed via a browser.
  3. OAuth Server / Authorisation Server provides a Security Token Server / Infrastructure for managing tokens. It is responsible for issuing:
  • Authorisation (code) grant – approval tokens driven by Resource Owner approval
  • Access tokens used by the API to authorise access
  • Refresh tokens which allow new access tokens to be requested by the client and re-issued within a specified timeframe
  1. Authentication Server – This is not a component of OAuth 2.0, or defined by OAuth 2.0, but needs to be considered when defining a complete OAuth 2.0 framework. This could be a simple login capability or managed by an Identity Service Provider.
  2. Resource Server – This hosts the protected resources (APIs & backend applications) which only allow authenticated and authorised clients by:
  • Checking the access token in each incoming API request
  • Validating the access token against the Authorisation Server and the permitted access rights

OAuth 2.0 comes with four types of grant flows, each appropriate to different situations and solution requirements:

  • Client Credentials
  • Resource Owner Password Credentials
  • Authorisation Code
  • Implicit

OAuth 2.0 is appropriate where there is a requirement for third party applications to access restricted resources. This should help mitigate the risks relating to:

  • Third party applications storing user credentials (username and password)
  • Resource servers having to support user stores and password authentication
  • Resource owners not being able to define granular access to resources, including duration
  • Revoking credentials that are compromised

For more details, see section 1.5, OAuth 2.0.

1.3.2 Usage Patterns

Different API usage patterns require different authentication and authorisation models. Below is a short definition of each of the different usage patterns.

Note: The Security components defined in the following diagrams are located, for simplicity, in the “trusted” zone i.e. an area managed by an agency. It is possible that these components could reside in different zones which relate to varying levels of trust (e.g. a DMZ). Internal Use only

In this pattern an API is developed for internal use only by agency applications/systems.

 Illustration of Internal API Security

Figure 6: Internal API Security

We see there is the need to authenticate and authorise the internal use to the internal application, and implement protection between the internal application and the API on the API Gateway. Application Developer

When an API is released for external use, the first interaction will be with App Developers who want to try the API out. This will normally be via the API Developer Portal.

Illustration of Developer Authentication to API Access 

Figure 7: Developer Authentication to API Access

The Application Developer needs to be authenticated to the API Developer Portal to register their new application and attain the relevant credentials which are used to secure interactions with the new application during development. The developer has to agree to the conditions of use and subsequent usage of the API can then be traced via the API keys (see Identify Consuming Application below). Identify Consuming Application

This pattern applies when the API provider needs to know which consuming applications are using their APIs (for communication, logging and analytics purposes).

 Illustration of Consuming Application Identification

Figure 8: Consuming Application Identification

The consuming application is authenticated (e.g. API Key, Client Secret etc.) to use the API, but this is only used as a means of identification or registration. System to System Authorisation (B2B)

The system to system model is where an API is being used to enable information sharing or integration with an external system e.g. a partner agency gaining access to supporting information.


lllustration of System to System Authorisation

Figure 9: System to System Authorisation

In this model the aim is to ensure that only the correct consuming system has access to the API, and that the API is protected from malicious use. B2B models often carry sensitive information, so the consuming system needs to be authenticated to the provider for authorised access, confidentiality and integrity. Authorise Consuming Application

Here the pattern covers the case where different external consuming applications may be granted different levels of access to resource(s). The application’s access is not dependent on which customer is currently using the application, but on which application is using the API e.g. perhaps the developer for App A pays a fee so App A gets a different quality of service from the API than App B.

 Illustration of Consuming Application Authorisation

Figure 10: Consuming Application Authorisation

The consuming applications must be authenticated and authorised before accessing the API. This is normally enforced at the API gateway. Customer Authorisation (Delegated Authority)

In the final pattern, external consuming applications may be granted different access to resource(s) depending on which customer is currently using the application e.g. learner authorises a mobile application to retrieve their own record of achievement.

 Illustration of Delegated Authority

Figure 11: Delegated Authority

The customer authenticates to the device. The device and/or the application is already authorised to use the API. The customer logs in and authorises the device and/or application to access their information. E.g. an internet banking application.

Page last updated: 18/12/2016