tombcghtech/api_guidelines huggingface dataset:
Maximise entropy (randomness) of security credentials by using API keys rather than username and passwords for API authorisation, as API keys provide an attack surface that is more challenging for potential attackers.
Balance performance with security with reference to key life times and encryption / decryption overheads.
Manage the exposure and lifetime of all APIs, and ensure all organisation APIs are covered by proactive scanning.
Validate the content of all incoming messages, ensuring communications are secured (in other words, encrypted) and apply threat protection policies (for example, injection and throttling).
2. Usage patterns
Different API usage patterns require different authentication and authorisation models.
Note: The security components defined in the following diagrams are located, for simplicity, in the ‘trusted’ zone, for example, an area managed by an agency. It is possible that these components could reside in different zones that relate to varying levels of trust — for example, a Demilitarized Zone (DMZ).
2.1. Pattern 1: Internal use only
In pattern 1, an API is developed for internal use only by agency applications or systems.
Figure 5: Internal API security
Figure 5 shows there is the need to authenticate and authorise the internal user to the internal consuming application, and implement protection between the internal application and the API on the API gateway, which interacts with the backend application.
2.2. Pattern 2: Identifying an application developer
When an API is released for external use, the first interaction will be with application developers who want to try the API out. This will normally be via the API developer portal.
Figure 6: Developer authentication to API access
Figure 6 shows that 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 pattern 4: identifying a consuming application).
2.3. Pattern 3: Anonymous consuming application
Pattern 3 applies when the API provider does not need to know which consuming applications are using their APIs.
Figure 7: Unidentified consuming application
Figure 7 shows a web application (the consuming application) on a web browser is unidentified (for example, has no API key) but can still use the API.
2.4. Pattern 4: Identifying a consuming application
Pattern 4 applies when the API provider needs to know which consuming applications are using their APIs (for communication, logging and analytics purposes).
Figure 8: Consuming application identification
Figure 8 shows a web application (the consuming application) on a web browser is authenticated (for example, has an API key, client secret, and so on) to use the API, but this is only used as a means of identification or registration.
2.5. 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 — for example, a partner agency gaining access to supporting information.
Figure 9: System-to-system authorisation
Figure 9 shows an external application (the consuming system) needs to be authenticated to access the API.
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.
2.6. Pattern 6: Authorising a consuming application
Pattern 6 covers the case where different external consuming applications may be granted different levels of access to resources. The application’s access is not dependent on which customer is currently using the application, but on which application is using the API, for example, 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 10: Consuming application authorisation
Figure 10 shows 2 consuming applications, an application on a smartphone (consuming app A) and a web application on a web browser (consuming app B). Both consuming applications must be authenticated and authorised before accessing the API. This is normally enforced at the API gateway.
2.7. Pattern 7: Authorising a customer (delegated authority)
In pattern 7, external consuming applications may be granted different access to resources depending on which customer is currently using the application — for example, a learner authorises a mobile application to retrieve their own record of achievement.
Figure 11: Delegated authority
View larger image (PNG 40KB)
Figure 11 shows the customer authenticates through the application (consuming application) on their smartphone 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, for example, an internet banking application.
2.8. Pattern 8: Decoupled flow — Client Initiated Backchannel Authentication (CIBA)
In a traditional flow, the customer or end user is redirected to an authentication page. In pattern 8 and shown in figure 12, 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 consuming application or client can initiate the authentication and consent of an end user via an out-of-band mechanism.
Figure 12: Decoupled flow
View larger image (PNG 129KB)
2.9. Quick reference
The following provides a quick reference to identify the most appropriate authentication and authorisation model to use for the patterns defined. The models are explained in detail in subsequent sections.
2.9.1. Pattern 1: Internal use only
The most appropriate authentication and authorisation models are:
mutual TLS (certificates)
vendor or internally developed API gateway capability — OAuth 2.0 grant types:
resource owner password credentials:
without OpenID Connect and without Proof of Key for Code Exchange (PKCE)
authorisation code:
without OpenID Connect and without PKCE — Recommended

Response type: Code
without OpenID Connect and with PKCE — Recommended

Response type: Code
with OpenID Connect and with PKCE — Recommended

Response type: Code
API gateway proprietary.
2.9.2. Pattern 2: Identifying an application developer
The recommended authentication and authorisation model is API gateway proprietary.
2.9.3. Pattern 3: Anonymous consuming application
The most appropriate authentication and authorisation model is API keys.
2.9.4. Pattern 4: Identifying a consuming application
API keys — Recommended
2.9.5. Pattern 5: Authorising a system-to-system interaction (B2B)
client credentials:
without OpenID Connect and without PKCE — Recommended
2.9.6. Pattern 6: Authorising a consuming application
2.9.7. Pattern 7: Authorising a customer (delegated authority)
without OpenID Connect and without PKCE
with OpenID Connect and without PKCE — Recommended

Response type: Code
Client Initiated Backchannel Authentication (CIBA):
with OpenID Connect and without PKCE — Recommended
vendor or internally developed API gateway capability — OpenID Connect:
Hybrid:
with OpenID Connect and without PKCE

Response type: Code_id token
with OpenID Connect and without PKCE

Response type: Code token
with OpenID Connect and without PKCE

Response type: Code id_token token
2.9.8. Pattern 8: Decoupled flow (CIBA)
The recommended authentication and authorisation model is vendor or internally developed API gateway capability — OAuth 2.0 grant type: Client Initiated Backchannel Authentication (CIBA) with OpenID Connect and without PKCE.
The initial consideration for any API security framework should be to use the authorisation code grant type. The following are pointers for agencies when considering their requirements.
It is good practice to use API keys as the basis of all system-to-system authentication, such as consuming applications to API.
For pattern 6: authorising a consuming application, the client credentials grant type is recommended but the API keys model can be used instead.
For pattern 7: authorising a customer (delegated authority):
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, it is appropriate to use client initiated backchannel authentication
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.
Using only API keys for customer authentication is not recommended and should be a last resort.
For pattern 1: internal use only, 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.
For pattern 2: identifying an application developer, it is appropriate to leverage (or build) the capabilities of the developer portal (for example, username and password).
Pattern 8: 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.
The authorisation code grant type has been enhanced with Proof of Key for Code Exchange (PKCE) and addresses key security hacks. In OAuth 2.1 (draft)it is now recommended as a default option for authorisation code grant type.
3. API authentication and authorisation basics
Before looking at the technical solutions to API authentication and authorisation, this section describes the situations where authentication and authorisation are appropriate.
Authorisation and authentication are intrinsically linked inside the OAuth 2.0 framework, which in itself is regarded as synonymous with securing APIs. OAuth 2.0 uses its own terminology, which is worth becoming familiar with when adopting an OAuth 2.0 approach.
As the OAuth 2.0 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 2.0.
3.1. Authentication — Required
When securing APIs, authentication is required to identify the consumers and / or consuming applications that want to access or consume an API. Authentication enables the API provider to identify all consumers of an API and to confirm that the consumer requesting access is who they say they are. This does not automatically authorise them to access the APIs or the underlying resources.
Providers should define a registration process for each category of consumer, whether system or human.
The ability of knowing who is using an API cannot be overstated. This is critical when it comes time to implement aspects of the API service life cycle, such as service deprecation, or notification of an outage. It also enables the API provider to implement different service levels for different consumers. For example, commercial customers might have a higher request limit per day than customers not paying for the service.
Making application developers register for use of the API also means they must sign up to terms and conditions that define how they might use the data they get from the API, and that they agree to ensure that their consuming applications will behave in an acceptable and non-abusive manner.
3.1.1. Authentication techniques
Figure 13 lists the authentication techniques that can be used to secure APIs and Appendix B — Authentication provides guidance on when to use them.
Figure 13: Authentication options
Figure 13 lists the following authentication techniques that can be used to secure APIs and where they are used:
Developer authentication — used to log in to the API portal
Anonymous — not recommended to use
Multi-factor authentication:
User name and password — not recommended for public facing APIs, useful in development / training environments
API keys — recommended to use for all APIs, used for application authentication (not human)
Certificates — used for: consuming application (B2B only) to API gateway, OAuth 2.0 client to authorisation server, API gateway to backend systems
OAuth2 and security tokens — recommended to use for internal and external production APIs
OpenID Connect — recommended to use where there is an OpenID Connect provider.
View larger image (PNG 165KB)
There is a second security token option that is built on Security Assertion Markup Language (SAML), but it is only recommended if SAML is already in place within a particular sector (for example education), otherwise SAML is seen as a deprecated model for REST APIs.
These guidelines do not cover the SAML option. For details on how SAML is used as an authentication token in OAuth 2:
SAML 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants — Internet Engineering Task Force (IETF) Datatracker
3.2. OAuth 2.0 basics
OAuth 2.0 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. For more details see Appendix C.
The IT industry perceives 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 2.0 requires some fundamental security components in order to work, and has its own terminology for describing these components and their roles.
Figure 14: OAuth 2.0 components
View larger image (PNG 45KB)
Figure 14 illustrates these components and their roles:
Resource owner — the person who has the right to grant a third party (for example, a consuming application) access to a protected resource (for example, information about themselves). Quite often the resource owner is the customer.
Client (or client application) — a consuming application requesting access to a protected resource on behalf of a third party for example, a mobile application on a user’s (third party) smartphone or a web application accessed via a browser.
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 that allow new access tokens to be requested by the client and re-issued within a specified timeframe.
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.
Resource server — this hosts the protected resources (APIs and backend applications) that 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 4 types of grant flows (how client applications can gain access tokens), 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.
The sections Resource-based scopes and Proof Key for Code Exchange (PKCE) are 2 additional concepts that should be clearly understood, and they provide additional security controls. Also, PKCE is seen as a security control that will be mandated in future versions of the OAuth 2 specification.
3.2.1. Resource-based scopes (for coarse-grained access)
Access and refresh tokens provide confirmation that the end user has consented to delegate access rights to the client. Resource-based scopes (scopes), which are linked to the access token, provide an additional level of authorisation, each one defining a specific capability, for example ‘read’ document or ‘write’ document.
Scopes are approved by the end user and enforced by the backend API. The authorisation server validates the token, which contains the scopes that have been consented to, and validates the client is not exceeding its access rights.
3.2.2. Proof Key for Code Exchange (PKCE)
The authorisation code grant type is regarded as the recommended solution for most scenarios and is regarded as one of the most secure options especially for server-side applications, where the final access token required to call the resource APIs is protected via an encrypted channel between the authorisation server and the client application (residing on a server).
To obtain the access token the client application makes an authorisation request to the authorisation server and if the required information is provided and approved, the authorisation server presents the client application with a code that is then used to request the access token over the secure back channel.
The back channel link is normally secured using Mutual Transport Layer Security (MTLS), but the initial flow to obtain the code token is over Transport Layer Security (TLS) and in certain architectures can be intercepted in a man-in-the-middle attack.
PKCE was developed specifically to address a man-in-the-middle attack, which is called the authorisation code interception attack, and in particular for mobile phone scenarios where malicious application (with elevated rights) could also be installed on the same mobile device as the client application and obtains the code, and with this then obtain the access token.
It works based on a random key (code verifier) that is generated, only known by the client and is used to create another random key, based on a hashing method, which is called the code challenge.
The challenge is sent (including the method) during the code flow and is stored by the authorisation server.
When the client requests the token with the code token, it also includes the original code verifier, which the authorisation server validates against the code challenge before the access token is returned to the client.
3.3. Basic OAuth 2.0 implementation patterns
There are 3 primary implementation patterns:
distributed resource and authorisation servers
client credential grant flow
authorisation code grant flow.
Figure 15: OAuth 2.0 implementation patterns with a separate authentication server
View larger image (PNG 56KB)
Figure 15 shows that in the patterns ‘client credential grant flow’ and ‘authorisation code grant flow’, the resource server resides with the authorisation server. But OAuth 2.0 also supports a distributed model, if needed, where the resource server and authorisation server are separate.
By adding an authentication server component into the API security framework, a number of additional implementation models can be considered. The patterns in figure 15 have separate authentication servers, for example, external identity service providers, Google, RealMe and internal authorisation services.
There is a simpler security architecture shown in figure 16 where the authentication server is housed on the same system as the authorisation and resource servers.
Figure 16: OAuth 2.0 implementation patterns with co-location of authorisation and authentication servers
View larger image (PNG 61KB)
3.3.1. Distributed model — User-Managed Access (UMA)
The distributed pattern models allow for multiple resource servers and authorisation servers and is addressed by User-Managed Access (UMA). UMA is a delegation access protocol allowing third parties to have temporary access to resources that are approved (consented to) by the resource owner. UMA is driven by the Kantara Initiative and currently has been put into production by a number of vendors.
Kantara Initiative — Kantara
Gluu
In figure 17, the resource owner has the ability to provide predefined policies that define the relationship and access controls for all their resources across multiple resource servers of what can be accessed and by whom (for example, minimise their interaction in the current OAuth approval process) and provides a central point of control.
A centralised UMA authorisation server then keeps track of all resource servers associated with a given resource owner.
Figure 17: User-Managed Access
Figure 17 shows an overview of UMA. The resource owner establishes a token-based trust relationship between the resource server and the authorisation server.
The resource owner also defines the access control policies that grant access to potential consumers. A client application, driven by the requesting party who is requesting access to resources owned by the resource owner, attempts to access a resource on a resource server but will be redirected to the UMA authorisation server.
The client application has to obtain a client key, client secret and access token from the UMA authorisation server before trying to get to the required resource on the resource server. The resource server will validate the access token and the permitted level of access with the authorisation server before allowing the client application to consume its required resources.
To support these interactions, the UMA authorisation server offers 2 APIs:
protection API — used by resource servers for getting authorisation-request tokens and validating access tokens
authorisation API — used by the client application to obtain a token for accessing a specific resource.
OAuth 2.0 provides a consent model that is driven via a synchronous process — UMA provides enhanced consent capability that is driven via asynchronous processes, which allows for:
the sharing of information with parties and groups based on relationships
managing requests from third parties
monitoring shares across sources.
3.4. OpenID Connect
OpenID Connect is the recommended security profile for the use of OAuth 2.0 authentication security tokens when an API requires more secure authentication than offered solely by API keys — for example, when data is a 2-way flow between the consuming application and the API.
3.4.1. Basic principles
OpenID Connect is used to:
enhance the process and user experience during the onboarding process
provide a SSO capability
secure transfer of user data
enrich the user experience
provide a trust framework [integrity] for service and identity providers to share consented user data.
During the authorisation token exchange process a level of authentication is required. The authentication process is limited to what authentication services the authorisation server can support. For example, the resource owner authorisation process is normally supported out of the box by the authorisation server, using username and password.
These authentication services can be enhanced with authentication security tokens by implementing the OpenID Connect OAuth profile. For customers and internal users this can be achieved using a brokered or federated identity service.