1.6 Authorisation


Authorisation is the act of performing access control on a resource. Authorisation doesn’t just cover the enforcement of access controls, but also the definition of those controls. This includes the access rules and policies, which should define the required level of access agreeable to both provider and consuming application. The foundation of access control is a provider granting or denying a consuming application and/or consumer access to a resource to a certain level of granularity.

In the Authentication section the concepts of OAuth were introduced and a number of Authentication patterns were defined. This section focusses on Authorisation and provides additional patterns that work with OAuth or provides an alternative.

1.6.1 Authorisation Techniques

Authentication on its own does not necessarily provide permissions to access an API or application. It merely validates that you are who you say you are. If it is used for access control, it is an all or nothing control mechanism (e.g. administration account).

Once a user is authenticated (e.g. using username and password), an authorisation process will grant (or deny) them the right to perform an action or access to information. Normally this authorisation process is applied using either a coarse grained or fine grained access control process.

The normal model is to provide coarse grained access at the API or API Gateway request point, and fine grained control at the backend services, but this model is changing as backend systems become more modular (e.g. microservices) and less monolithic. This will result in a need for fine grained authorisation support at the request point.

With this understanding, the two types of authorisation that will be considered are defined in Figure 32. This covers:

  1. Role- or Group-based authorisation
  2. Policy- or Attribute-based authorisation

 Illustration of Authorisation Techniques

Figure 32: Authorisation Techniques

The API Gateway will provide this support either using OAuth 2.0 or its own proprietary capability. Roles Based Access Controls (RBAC)

In many organisations Active Directory provides the authentication services for users. Active Directory groups are then used to provide authorisation. This is classed as Discretionary Access Control (DAC): access to systems is granted by applying Access Control Lists (ACLs) directly to the user, or to the groups in which users reside.

Note: LDAP directories can also provide this service, and in many organisations are used to provide the same service AD delivers but for external users.

Active Directory (or LDAP) Groups are synonymous with roles and can be used to provide coarse-grained authorisation for APIs. Attribute Based Access Controls

Attribute-based access control (ABAC) defines an access control process whereby access is granted based on policies that are built using attributes e.g. a policy might state that access to a specified resource is only permitted for users who are in Sales or Marketing, who are managers, during office hours only. ABAC provides fine grain authorisation services.

The really important control that ABAC provides is the ability to provide context when applying access controls, e.g. access decisions can be based on the IP address of the device, the operating system of the client and the last know transactions of a client.

The recognised standard for ABAC is XACML, which is an XML based-language.

1.6.2 API Gateway

API Gateways have been mentioned previously in the context of API protection. Most API Gateways on the market provide support for OAuth 2.0 and can also provide Authorisation (and Authentication) Services via a direct connection to:

  1. An Identity Store containing groups
  2. An Identity Access Management system
  3. A Policy server


Illustration of API Gateway for Authorisation

Figure 33: API Gateway for Authorisation

1.6.3 ABAC Implementation

To implement Attribute Based Access Control, the current models defined use XACML.

XACML (developed by OASIS), provides a reference architecture, a request / response protocol and a policy language.

It is a highly distributed and loosely coupled architecture. It provides very useful generic definitions of the required components (services) which can be used to define any access control model.

It uses the following services to define the reference architecture:

  1. Policy Enforcement Point (PEP) – where the request to the resource is intercepted and policy applied (based on the decision made by the Policy Decision Point)
  2. Policy Decision Point (PDP) – This is the policy server to which the PEP sends the request for evaluation as to whether a user should or should not have access to a resource. The PDP has access to policy and can match the credentials and request against policy to make a permit/deny decision. It can also enforce policy related obligations e.g. enhanced logging, notification and alerts, or re-routing to request additional authorisation process.
  3. Policy Administration Point (PAP) – The interface where the policies are developed and defined
  4. Policy Information Point (PIP) – Used to gather additional information about a user from Identity stores or databases to provide additional attributes that are required by the PDP to validate the policy and apply the required outcome

The links and flows between these services are detailed in the diagram below:

Illustration of XACML Reference Architecture 

Figure 34: XACML Reference Architecture

XACML is generally perceived as being difficult to write polices in, but this is being addressed in two ways:

  1. OASIS are developing a Request/Response Interface based on JSON and HTTP for XACML 3.0, Version 1.0
  2. There is a JSON-based language called ALFA (Abbreviated Language For Authorization) which can be used to build XACML policies

For XACML to support fine grained access for APIs requires a model such as is illustrated in the diagram below (based on the scenario in section 1.5.6).

Illustration of ABAC Support for APIs 

Figure 35: ABAC Support for APIs

It follows these steps:

  1. The access token is obtained during the request and exchange process
  2. The access token is presented during the resource request to the PEP, which also exposes the resource
  3. The access request is passed to the Authorisation Server
  4. The Authorisation Server verifies the access token and passes a XACML request to the PDP. This is where additional fine-grained access can be applied.
  5. The PDP authorises the PEP to allow access to the back end service

1.6.4        Scopes (Limited Fine Grain Access)

ABAC provides fine grained access controls to APIs. Based on the services (APIs) that are exposed, additional fine grained access controls can be applied using scopes. For example, a data service might provide “read” and “write” scopes.

When the “Authorisation code” token is passed to the Authorisation Server a scope parameter is included to define what scopes the client can use. Scopes can be used to limit the authorisation granted to the client by the resource owner. These scopes are defined by the client application developer. This is an important consideration as it can impact how the API service is defined e.g. single service with multiple scopes or multiple services with single scopes. The developer has to ensure that the minimum privileges are granted to client applications to carry out the tasks (exposed by the Client Application and APIs) the user wishes the application to complete.

Scopes provide a level of coarse/fine grained access and represent specific access rights e.g. the ability to read a document or write a new document (or both) is limited by the Access Token.

Scopes can be used alone to define coarse/fine grained access, but these scopes need to be defined and built into the Client application / API being built. Consideration is needed to understand (for example) if:

  • a single scope protects the service
  • scopes are defined to protect fine-grained business functionality
  • services should be divided into many smaller services with one scope each


Once the token is issued to a client application, the access rights bounded by the scope are encapsulated in the Access Token for the length of its validation period.

A client application may invite a user to authorise the application to act on behalf of the user. Using NZBN as an example, the client application (an accounting application for example) may invite a user to authorise the client application to update primary business data on the user’s behalf. The application may ask “Do you want [client application] to be able to update your business information on the NZBN Directory?”. Assuming the user grants the client application this privilege, the authorisation token returned by the API will have a scope that enables update access. This scope is represented by an identifier. For example, the NZBN update scope looks like this:


whereas a read-only scope would be:



Page last updated: 18/12/2016