tombcghtech/api_guidelines huggingface dataset:
API guidelines — Part B: API security 2022
Learn about API (Application Programming Interface) security reference architecture and the technical details for implementing API security.
1. API security
1.1. Introduction
According to Gartner, by 2022 API abuses will be the most frequent attack vector for enterprise web application data breaches. As such, securing Representative State Transfer (RESTful) APIs is fundamental to the success of any API strategy or implementation. Any approach should include the following 3 key areas:
domain of consideration
domain of control
identity(1)-centric and holistic view.
1.1.1. Domain of consideration
Developing and securing RESTful APIs is more than just applying standards, it is a framework and state of mind that has to be understood and followed jointly by the business owners, IT architects and developers.
The API security framework must be defined at the organisation and business level and should always consider who, how and what users and applications (both internal and external to an organisation) will interact with the APIs. These considerations should be defined at the beginning of any project and driven from a desired business outcome — for example, provide real time information for the public about the closest location and address of a general practitioner.
1.1.2. Domain of control
The domain of control contains the components that need to be developed and deployed, and they need to work together to provide API security to support:
registered application developer access to the API
authenticated and authorised consuming application access to the API or events
protected communication between the API, the event broker and the consuming application to ensure confidentiality and integrity
the ability for applications to act on behalf of a customer.
Figure 1 illustrates these domains of consideration and control working together to provide API security.
Figure 1: API security considerations
Figure 1 illustrates the domains of consideration and control working together to provide API security.
Within the domain of consideration:
application developers provide authentication to access the API developer portal
API developers provide authentication to access the API developer portal and API manager
customers, through a consuming application (an application on a device), are authenticated and authorised to use the API.
The domain of control is a subset of the domain of consideration and contains the following components:
API developer portal
API in the API gateway
backend systems
event broker and various services.
This is described in more detail in sections 1.1.1. and 1.1.2.
View larger image (PNG 87KB)
1.1.3. Identity-centric and holistic view
The security of APIs should not just be seen as a bounded solution, but needs to be seen from a holistic perspective. It needs to incorporate management and understanding of user identities across:
enterprise security
mobile security and application security
API security.
For example, securing an API that is targeted for a mobile application is not just about applying an OAuth (Open Authorization) profile, it should take into consideration how mobile devices and applications are managed and secured and how the enterprise security framework (for example, authentication) can be leveraged.
People- or user-centric security frameworks are key to defining the required access policies and controls for APIs. The management of identity (this includes users, device, servers and applications) should be central to any API security framework.
Figure 2: Identity-centric
Figure 2 is a Venn diagram with 3 intersecting circles representing:
enterprise security.
These intersect in the middle representing identity, which is central to an API security framework.
1.2. Definitions for APIs covered in these guidelines
This version of the API guidelines expands its remit to beyond REST APIs to include the additional API types: GraphQL, AsyncAPI and gRPC.
These additional types of API are covered in Part C: API development 2022, but from a high-level perspective the following definitions apply to all 4 API types.
Authentication The process of verifying the identity of a customer (or device) who presents identity credentials and authentication keys.
Authentication authority A system entity that provides authentication services to ensure only permitted customers (or devices) gain access.
Authorisation The process of verifying that a customer (or device) has the right to perform an action and what they are allowed to access.
Availability The ability to minimise API downtime by implementing threat protection.
Confidentiality The ability to ensure information that is sent between users, applications and servers is only visible to those authorised to use it.
Consent management The process that manages the collection of user data, ensuring that the required policies are applied, and the required consent has been obtained from the user, allowing the user to understand how the data is used and to be able to opt out if required. This is being driven by many global privacy laws.
Delegation When a user authorises another user (or device) to serve as his or her representative for a particular task.
Delegated authorisation A framework that defines how an owner of a set of resources can grant access (delegate) to a designated user or consuming application to perform actions on some of those resources on the owner’s behalf, but without sharing their credentials.
Federation The process that allows for the leverage and reuse of identity credentials to multiple authentication authorities for authentication and / or Single Sign-On (SSO).
Integrity The ability to ensure that information received has not been modified by a third party, also providing non-repudiation services
Provisioning The automated or manual service for aggregating and correlating identity data resulting in the creation of user (IT) accounts and the delivery of user metadata used by systems to define access policies and controls for services.
Threat protection The service for protecting APIs (at the ingress and egress points of an organisation) from known threats (for example, OWASP (Open Web Application Security Project) Top Ten) by preventing misuse or loss of availability.
Note: Threat protection should also be addressed at the operating system hardening level and should be an integral part of the API software development.
User-Managed Access (UMA) Developed to provide a user data delegation model that enables a resource owner to control the authorisation of data sharing and other protected-resource access made between online services on the owner’s behalf or with the owner’s authorisation by an autonomous requesting party.
Zero Trust (ZT) An evolving set of cybersecurity paradigms that move network defences from static, network-based perimeters to focus on users, assets and resources. A Zero Trust Architecture (ZTA) uses ZT principles to plan enterprise infrastructure and workflows. ZT assumes there is no implicit trust granted to assets or user accounts based solely on their physical or network location.
1.3. Risks
APIs are another channel into an organisation’s resources and information. Most organisations are accustomed to exposing a web interface, with good control over what information is released via that interface.
APIs offer direct, machine-to-machine access to resources and information, which makes it less obvious when information is incorrectly exposed. It becomes increasingly important for internal business stakeholders to decide what information and resources should be released via this channel, and to whom.
The security risks that APIs introduce will be similar to the traditional risks experienced on any web channel (web sites and web applications), except that there:
is an increased attack surface due to more ways in, multiple services to potentially exploit
is a risk of inadvertently exposing backend data, backend architecture and backend applications
is potential for greater consequences if your API is compromised or hijacked and serves up malicious payloads to consumers
are greater privacy concerns where APIs involve personally identifiable information
are risks of malware in uploaded files due to performance overhead or lack of inline scanning
is a risk of malformed APIs that are developed with limited security validation and inappropriate security validation
is a risk related to cloud- and container-based systems where security best practices are not applied.
Risks posed by APIs include loss of integrity, confidentiality, and availability of data, for example:
loopholes retrieving API resources may offer access to more information than was intended (especially if fields requested are built straight into a database (DB) query)
write operations offer a means of polluting data stores, feeding misinformation into a system
write operations could be used to form a Denial of Service (DoS) attack by overloading the server or data store
use of wildcards in search fields can shut down APIs and backend applications
cross-site scripting attacks made possible by consuming applications not checking user inputs
Structured Query Language (SQL) injection into consuming applications that cause database damage at the API backend
parameter attacks such as Hyper Text Transfer Protocol (HTTP) Parameter Pollution (HPP)
man-in-the-middle attacks, modifying API requests or responses leading to data eavesdropping or misinformation insertion
subverting authentication or authorisation mechanisms to spoof messages from legitimate consumers
credential leakage or stealing authentication tokens to obtain information illicitly
system information leakage through API error messages revealing details about an API’s construction or underlying system makeup
broken session IDs, keys and authentication create exposure to unauthorised access through authentication factors that are not functioning because of poor security design or technology bugs
other broken resource identifiers, authentication and authorisation mechanisms, allowing attackers to exploit flaws to obtain access, either temporarily or permanently
exposing too much information through the use of generic resource APIs rather than specialising APIs for each specific circumstance.
1.3.1. Mitigation approach
API risks need to be mitigated in a number of ways. There is no single off-the-shelf security solution that can be dropped in to address all aspects of API security. APIs need to be secure by design — security needs to be built in from scratch and be considered within the context of existing protection mechanisms. The main areas that API security covers are:
identity and access management to provide:
authorisation and delegated authority
confidentiality
availability and threat detection
logging, alerting and incident management.
This ensures that:
the consuming application is known and can only get access to API resources they are allowed to
message content has not been tampered with between consumer and provider
resources are reliably from the provider intended when the consuming application made the request
the API will be available when needed, and not brought down by attacks from malicious consuming applications.
In order to address API security risks, a security framework is needed that encapsulates all these aspects of security.
1.3.2. Zero Trust and decoupled environments
The Zero Trust Network Access (ZTNA) model has been talked about for a number of years. In the current environment it is now seen by many analysts as the direction organisations need to take. This section highlights areas of the model that can help mitigate risks related to APIs.
ZT architecture removed the concept of trusted internal and untrusted external networks and focuses on the policy of ‘never trust always verify’.
The selection of cloud services has changed this security model to one where all actors (employees, partners, and so on) require access controls no matter where they are coming from or on.
ZT is seen as an architecture that is critical for organisations moving towards decoupled microservices and API architectures.
Microservices architectures are the backbone of many API services offered by organisations and have embraced the concepts of identity and how permissions are created and enforced between different services.
Every microservice requires an identity that can be confirmed, and the required permissions and policies applied that should be based on attributes and contextual access.
Some of the areas that need to be considered by an organisation when planning their implementation of ZT include:
applying strong identification and authentication
building a digital trust model that is dynamic, and trust is only valid for the current session
constant evaluation
always authenticate
applying contextual authorisation (attributes, consent, location, time, behaviour)
building in a digital risk capability that maps to a level of confidence and constantly re-evaluates
leveraging identity and access management capability from identity proofing to adaptive authentication
incorporating endpoint security
transaction-level verification and continuous session validation
ensuring data security is applied with reference to encryption and user privacy controls including consent management
implementing strong auditing, logging, event reporting and forensics providing insight and behavioural patterns
smart threat detection with machine learning
injecting identity context into the API traffic (user, application, device)
using JWT (JavaScript Object Notation (JSON) Web Token) to provide secure and validated claims, which can also be encrypted
applying fine-grained access at the egress point, allowing the enforcement point to allow, block filter or modify the response
identifying propagation to backend services to make decisions
JWTs limiting chatter in microservice environments
all APIs should be secured and treated as if they are public APIs.
1.4. Security reference architecture
This section describes an API security reference architecture and its component parts to inform the construction of an API security framework. It is important to note that REST, gRPC, GraphQL and AsyncAPI are different architectural models for building synchronous and asynchronous APIs that can leverage the security controls (for example, OAuth 2.0 and OpenID Connect) defined in these guidelines, but they all have their own intrinsic security models (for example, throttling consideration in GraphQL) which are not covered in these guidelines.
1.4.1. Actors and security functional capabilities
Identity and access management defines the actors (users and devices) who interact with system components that manage and expose APIs. Figure 3 shows a typical model of API components (support stack) and actors. The actors and components are described in tables 1 and 2.
Figure 3: API actors and core components
Figure 3 illustrates a typical model of API security reference architecture.
The API components (support stack) are in the middle of the diagram and include the:
API gateway
event broker
API monitoring and analytics
credential stores (identity and key stores).
These core components are described in more detail in section 1.4.1. and in table 2.
In the right of the diagram, the following internal actors feed into the support stack:
internal application developers
internal API developers
business owners and security.
In the left of the diagram, the following external actors access the support stack:
customers — using consuming applications on devices, such as web browsers, mobile devices and servers, to access an API
consuming application developers.
The internal and external actors, and devices are described in more detail in section 1.4.1. and table 1.
View larger image (PNG 506KB)
The components defined remain valid no matter what API architecture (internal, cloud, hybrid) is implemented.
Table 1: Actors (users and devices)
External users
* Customers — the public, other agencies and partners who use consuming applications to access resources via APIs
* External application developers who build software to access resources via APIs
* PC browsers running web applications
* Mobile devices running apps
* Servers running systems with server-to-server communications
Internal users
* Internal API developers who build APIs
* Internal application developers who build software that accesses resources via APIs
* Business owners responsible for the API products
* Security responsible for ensuring the APIs are secure
The core components of an API security framework (the development portal, manager and gateway) provide a grouping of functionality. These functions can be delivered with discrete applications, or bespoke code development, via commercial off-the-shelf (COTS) products or through leveraging existing devices that can be configured to provide these functions or services.
Note: Some of the functionality may overlap or be combined into 1 or more products depending on the vendor used.
Table 2 lists the functions of a mature API delivery and security framework for an agency that is working with the development community. Together, these functions provide full support for the application developer building and developing consuming applications that will use the APIs exposed by the agency.
Depending on the requirements of the agency, some of these functions might not be required — for example, if the agency API exposed is purely for public consumption and only allows consuming applications to read information, then only a solution for enforcing threat protection (for example, DoS) might be required, and this could be delivered using an existing service protection capability.
Table 2: Core components
API portal
The API portal often provides the following functions for internal and external application developers:
* discovery of APIs
* analytics to monitor APIs
* access to specifications and descriptions of APIs, including Service Level Agreements (SLAs)
* social network capability to share and publish ideas.
The API portal also supports the development, build and test of consuming applications.
The API manager functions cover:
* centralised API administration and governance for API catalogues
* management of registration and on-boarding processes for communities of API developers
* lifecycle management of APIs
* applying pre-defined security profiles
* security policy administration / definition
* policy evaluation.
The API gateway capability can:
* act as the API proxy or the host acting as the primary point of access for exposed APIs
* enforce threat protection, throttling and quota management
* provide authorisation services to control access to APIs
* provide authentication services to ensure only permitted users (internal / external) have access to the API
* enforce security policy
* provide monitoring and analytics for business and security analysts.
The event broker (or ‘broker’) is responsible for receiving events (AKA messages) from publishers (services) and delivering them to subscribers (services), that is, the consumers who have registered interest in events of that type.
Brokers often store events until they are delivered, which is what makes event driven architectures very resilient to failures. Examples of brokers are RabbitMQ, Apache Kafka and Solace.
With the emergence of an AsyncAPI standard, event driven architectures are becoming more prevalent.
OpenAPI (REST APIs) and AsyncAPI are API (message and event-based APIs) documentation specifications in a machine-readable format.
AsyncAPI bindings specifications — GitHub
Business owners and security specialists need to be able to monitor the use of APIs to:
* monitor uptake of API services
* define when to deprecate an old version
* profile usage for business
* profile usage for security baselines
* detect and respond to security events (SEIM).
This helps adapt to change in usage and demand.
Credential stores
The credential stores are identity and key stores that are used to securely store:
* internal and external user objects, and possibly groups
* API keys and secrets, certificates, and so on.
These stores are used by the API gateway for authorisation and authentication services.
Figure 4 shows how the model can also be split with the API support stack duplicated — 1 set to support internal API usage and 1 set to support external use.
Figure 4: Split API support stack
Figure 4 shows a variation on the typical model of API components and actors shown in figure 3. It has the same API components and actors as described in figure 3, but the API support stack (API developer, manager and gateway) is duplicated — 1 set supports internal API users (internal API developers and application developers who are in-house and within the support stack) and 1 set supports external users (actors and devices).
View larger image (PNG 216KB)
Authentication, authorisation, confidentiality, integrity and availability can be applied across the components in the support stack, depending on component capabilities.
The actual configuration and location of the API functional capabilities will vary depending on individual circumstances (for example, some capabilities may be internal, some may be in the cloud, where API development is outsourced then an ‘internal’ functional stack may belong to the outsourcer, and so on). Also, some components might not be required or can be developed in-house.
1.5. Building secure APIs
Building in security starts from the ground up, so development of APIs needs to be done with awareness of the API security risks associated with the resources and information being exposed, and with appropriate mitigations in place for these API security risks.
When developing an API it is advisable to carefully consider potential malicious use, especially:
PUTs and POSTs — which change internal data and could be used to attack or misinform
DELETEs — which could be used to remove the contents of an internal resource repository.
Standard secure coding practices are always recommended, in line with New Zealand Information Security Manual (NZISM) guidance.
Security by Design Principles according to OWASP — patchstack
But API development should take special note of:
design-driven development (refer to Part C: API development 2022)
OWASP Top Ten — OWASP: a summary of the standard attacks and mitigations
REST Security Cheat Sheet — OWASP: REST-specific risks and how to prevent them — for example, input validation
OWASP API Security Project — OWASP: top 10 API-specific risks and how to prevent them.
The OWASP Cheat Sheet Series provides cheat sheets on a variety of security-related subjects.
OWASP Cheat Sheet Series — OWASP
It is worth reviewing them to see if others may apply to your specific circumstances. Special note should be taken of the following where your API accepts input values as parameters:
OWASP Input Validation Cheat Sheet — OWASP: a summary of input risks and mitigations
OWASP Cross-Site Scripting Prevention Cheat Sheet — OWASP: how to escape inputs to prevent cross-site scripting
OWASP SQL Injection Prevention Cheat Sheet — OWASP: ensuring database queries are built internally
OWASP Query Parameterization Cheat Sheet — OWASP: examples of SQL injection and stored procedure vulnerabilities.
It is also recommended that a security testing capability be incorporated into the development cycle that provides continuous, repeatable and automated tests to find security vulnerabilities in APIs and web applications during development and testing.
1.5.1. API security design principles
The following key principles should be applied when designing API security frameworks.
Design with the objective that the API will eventually be accessible from the public internet, even if there are no plans to do so at the moment.
Security first — build security into the API when being developed.
Use a common authentication and authorisation pattern, preferably based on existing security components: avoid creating a bespoke solution for each API.
Least privilege — access and authorisation should be assigned to API consumers based on the minimal amount of access they need to carry out the functions required, and strong authentication and authorisation models are applied.