In Development

This section is in development and is not complete or ready for review.

MC

Use Cases in Health

Personal Health Record (PHR)

Patient Login

Patient Reads PHR

Patient Updates PHR

Patient consent given by related person

In some health care scenarios, especially those children and young people, consent can actually given on the patient's behalf by a family member, caregiver or legal guardian.

Patient grants consent to Practitioner

Patient delegates to RelatedPerson

API Security Use Case

The illustrative example below demonstrates a sequence of information exchange events and highlight where security controls are implemented.

High Level View

This sequence diagram shows the high-level interaction of the actors and participant service providers.

Figure 32: API Security Use Case High Level View

Detailed Level View

This sequence diagram shows the detailed interaction of the actors and participant service providers.

Figure 33: API Security Use Case Detailed Level View

1. Glossary of terms

Below is a list of common terms. Terms in the Description column highlighted in bold are described elsewhere in the Glossary.

Term	Description
Analytics	Analytics in the context of this document is the capturing and reporting of API usage.
Consumers	Customers, API Consuming Applications and Application Developers who use the API.
Consuming Application	This is any application (on any device) that consumes an API.
Context	Context in this document generally refers to request context. For example, a JWT Token may contain information about the customer initiating an API request.
Customers	People (or organisations) that use the Consuming Applications to access the API resources the API Provider is offering.
Discovery	The ability for Application Developers to find resources and associated APIs to use in their Consuming Applications
API	Application Programming Interface - a piece of software, which provides a way for other disparate pieces of software (applications, systems) to talk to one another.
API Catalogue	The API delivery component that lists the APIs offered, along with their Interface Specifications and guidance on how to gain access and use the APIs.
API Developer	The organisation (or person) who creates the API and maintains the Interface Specification for the API.
API Developer Portal	The API delivery component that allows API Providers to engage with, onboard, educate and manage Application Developers whether inside or outside the organisation. These management activities will generally include registration, documentation, analytics etc.
API Gateway	The API delivery component that allows API Providers to offer APIs to the outside world. This component (physical or virtual) hosts the APIs ready for Consumers to access. It provides an API Provider with the ability to control who has access to their APIs by enforcing policies for access control. Some API gateways also offer additional capabilities.
API Manager	The API delivery component that allows API Providers to control an API’s visibility and behaviour. It is usually exposed as a UI/console to internal staff only, as it is seen as an administration component. It offers a variety of capabilities, including API registration and catalogue administration.
API Provider	Organisation who provides the API to expose a resource (information or functionality) for Consumers.
Application	The software behind the API which provides the business logic for the resource.
Application Developer	Software developer or organisation who builds Consuming Applications that use the API. An application developer can be internal to your agency, developers that work with trusted partners, developers from other agencies or developers from the private sector.
Interface Specification	Provides technical information to the API Developer community about the API. It includes information about how the API works, any access control features and any error conditions.
Product Manager	The product manager is usually a technical role. They understand an agency's API landscape and are owners of API management platforms.
Product Owners	The product ownership function usually resides in a business area rather than technology. The role of the product owner is to understand the product that the agency is trying to deliver and be able to make decisions on the representation of the product in an API.
Publish	The act of releasing the interface specification and associated API to a location accessible by Application Developers
Resource	The information or functionality exposed by the API.
State	State defines the point in time record of an in-flight transaction. Some systems maintain user state for a period of time to enable a transaction to be continued from the point of last recorded state. APIs are usually, but not always, considered stateless.

Table 6: Glossary of Terms

Glossary of acronyms

Further Reading

Table 11: Further reading

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).

Pattern 1: Internal Use only

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

Figure 15: 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.

Pattern 2: Identifying an 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.

Figure 16: 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 a Consuming Application below).

Pattern 4: Identifying a 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).

Figure 18: 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.

Pattern 5: Authorising a System to System Interaction (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.

Figure 19: 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. Business to business (B2B) models often carry sensitive information, so the consuming system needs to be authenticated to the provider for authorised access, confidentiality and integrity.

Pattern 6: Authorising a 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 Application A pays a fee so Application A gets a different quality of service from the API than Application B.

Figure 20: Consuming Application Authorisation

The consuming applications must be authenticated and authorised before accessing the API. This is normally enforced at the API gateway.

Pattern 7: Authorising a Customer (Delegated Authority)

In this 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.

Figure 21: 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.

Pattern 8: Decoupled Flow - CIBA

(Client Initiated Backchannel Authentication)

In the traditional flow the end user is redirected to an authentication page, in this pattern the authentication and consent process is delegated to an authentication device of the end user. This process is performed via a back channel with a request and response. This flow decouples the authentication device from the traditional flow. In this model the client can initiate the authentication, and consent, of an end-user via an out-of-band mechanism.

Figure 22: Decoupled Flow

Quick Reference Table

The following table provides a quick reference to identify the most appropriate authentication and authorisation model to use for the patterns defined above. The models are explained in detail in subsequent sections.

Table 10: Quick Reference Table

The initial consideration for any API Security Framework should be to use the Authorisation Code Grant Type, the following points provide pointers for agencies when considering their requirements:

1. It is good practice to use API Keys as the basis of all system-to-system authentication, such as consuming applications to API.

2. For the Authorise Consuming Application usage pattern, the Client Credentials Grant Type is recommended but the API Keys model can be used instead.

3. For the Customer Authorisation usage pattern

   • the Authorisation Code Grant Type is recommended where the customer is the Resource Owner, the provider (agency) controls the Resource Server, but the Authorisation server is not owned by the provider or is elsewhere within the provider organisation

   • Where there is a strong desire to not interrupt the customer’s experience with the consuming application, use of Client Initiated Backchannel Authentication is appropriate.

   • the Resource Owner Password Credentials Grant Type is appropriate where the customer is the Resource Owner, the provider (agency) controls the Resource Server, and the API Gateway is the OAuth 2.0 Authorisation Server

4. Use of solely API Keys for Customer Authorisation is only appropriate as a last resort

5. For the Internal Use Only usage pattern, the Authorisation Code Grant Type is recommended, where practical. Otherwise, it may be appropriate to leverage the provider agency’s existing internal authentication and authorisation providers

6. For the Developer Authentication usage pattern, it is appropriate to leverage (or build) the capabilities of the developer portal (e.g. username and password).

7. The Decoupled flow (CIBA) supports out-of-band authentication and consent approval. It is recommended for organisations that want to enable push notification for web-based services and applications.

8. The Authorisation Code Grant Type has been enhanced with PKCE (Proof of Key for Code Exchange) and addresses key security hacks. In OAuth 2.1 (draft) it is now recommended as a default option for Authorisation Code Grant Type.