tombcghtech/api_guidelines huggingface dataset:
Federated identity in the context of API security provides the ability to re-use user identities in an SSO way by providing a trust relationship between the identity service provider (OpenID Connect service) and the authorisation server. This establishment of trust between the identity provider and authorisation server is normally established using certificates and mutual authentication. All communication must be over TLS / MTLS to provide confidentiality and integrity controls.
OpenID Connect runs on top of OAuth 2.0 and is a lightweight RESTful framework for identity service interaction, to provide authorisation services. It allows claims (or attributes) about a user to be shared in a secure manner from an identity provider to the client application with the explicit consent of the user.
OpenID Connect uses all the flows, grant types and endpoints exposed by OAuth 2.0, and it adds the following additional capabilities to provide access to the users claims / attributes:
an ID token
a Userinfo endpoint.
The ID token is a JSON Web Token (JWT) that contains authenticated user information (and attributes) that the authorisation (OAuth 2.0 server) / authentication server (OpenID Connect server) provides to the client application.
This token can then be used to enforce finer grained access controls by providing additional attributes that can be used by the authorisation server to apply these policies.
The ‘new’ JWT has to be signed in order to address confidentiality and integrity requirements. There are also additional parameters (relates to code, session and access token hashes) defined that have been added to help address replay attacks.
The Userinfo endpoint can be called with the required access token to also obtain the same claims / attribute (for example, first name) provided in the ID token.
To address the risk of forged or stolen assertions, it is recommended that all communication is over TLS and tokens are at a minimum signed for authentication.
3.4.2. OpenID Connect grant flows
OpenID Connect builds on the existing OAuth 2.0 grant flows, and once implemented it is enacted using a specific scope (openid) in the initial authorisation call that the client makes to the OpenID Connect service.
There are a number of additional scopes that OpenID Connect introduces (for example, profile) that detail specific attributes (for example, name) that can be presented in the ID token. So, for example a client might request the profile information, but it is the identity provider that details what this will provide (for example, first and last name, phone and email address) and this has to be consented (via the OAuth 2 consent process) to by the user.
The request call also includes a response type that allows the application developer to request identity information tokens and security tokens depending on what information they want back, the type of client (for example, server/ client based). The link provides an excellent summary of the response type possible with OpenID Connect.
Diagrams of All The OpenID Connect Flows — Takahiko Kawasaki
The ID token not only includes identity information, it also includes additional technical claims that allow the client application to verify that the ID token is valid and came from the identity provider. It is highly recommended that a client validates the ID token (for example, signature, client ID and issuer). The ID token can also be encrypted to enhance the confidentiality and integrity of the information presented.
OpenID Connect works with all the existing OAuth 2.0 grant types and adds additional security controls to the authorisation code grant flow, for the implicit flow in OAuth 2.0 — this is seen as a less secure flow than the authorisation flow and is now being discouraged. OpenID Connect provides a level of enhancement to the implicit flow as the nonce and state are returned in a signed JWT, but this is really only recommended in login-only use cases.
Finally there is the concept of a hybrid flow that uses the authentication code flow as a base and (depending on what is required by the client and what is enabled by the authorisation server) it allows additional tokens (ID tokens) to be issued during the flow. These are both used to provide secure identity information and also additional confidentiality and integrity controls relating to state, nonce values and hashes.
Hybrid Flow Steps — OpenID Connect
A good example of where the hybrid flow is being mandated is in the management of consent in the Open Banking Consumer Data Rights specifications — GitHub.
3.4.3. OpenID Connect patterns
In the first OpenID Connect pattern, detailed in figure 18, the authentication and authorisation servers are conceptually hosted on different physical servers (the OpenID Connect server can be internal or external to the organisation). The user connects to the web application and is redirected to the OpenID Connect server for authorisation.
Once authorised, the user is redirected to the web application which, in turn, exchanges the ID token for an access token.
Note: It is the token flow and exchange that is key to understand in this model. The web application could be an application / API server and the interface to the authorisation and authentication server managed by the API gateway.
A trusted link is set up between the OpenID Connect server and the OAuth server (authorisation server) that also allows additional identity information to be provided in a JWT format via the Userinfo endpoint. This is important as the token exchange can result in the loss of user data that is required to provide fine-grained access.
If the OpenID Connect server was external, it would be the API gateway that would be responsible for the interface and token exchange process.
The application has to exchange the ID token for an access token in this pattern.
Figure 18: OpenID Connect — distributed authorisation and authentication server
View larger image (PNG 33KB)
In the second pattern, shown in figure 19, the OpenID Connect server is run on the same server as the OAuth authorisation server, so the ID token and the access token can be issued at the same time. In both models, the OpenID Connect server can use Lightweight Directory Access Protocol (LDAP) for its backend user store, to provide authorisation for internal users.
Figure 19: OpenID Connect and OAuth
View larger image (PNG 27KB)
One other model is for an external OpenID Connect pattern, where the OpenID Connect server is an external identity provider (for example, all-of-government service) and the API gateway is responsible for managing the token exchange, potentially also housing the authorisation server.
3.4.4. Health Relationship Trust (HEART) Working Group
The OpenID Foundation uses working groups to focus on specific problems, technology or specific marketplace sectors like Financial-Grade APIs (FAPI) or the Health sector HEART Working group.
Current Working Groups — OpenID Foundation
Health Relationship Trust (HEART) defines a set of profiles that enables patients to control how, when, and with whom their clinical data is shared.
HEART Working Group — OpenID Foundation
It also defines the interoperable process for systems to exchange patient-authorised healthcare data consistent with open standards, specifically Fast Healthcare Interoperability Resources (FHIR), OAuth, OpenID Connect, and UMA.
Two pertinent specifications are:
HEART Profile for User-Managed Access 2.0 — OpenID Foundation
HEART Profile for Fast Healthcare Interoperability Resources (FHIR) UMA 2 Resources — OpenID Foundation
3.4.5. CIBA flow
The OpenID Connect CIBA flow is important because it adds 3 ‘decoupled’ authorisation flows. Instead of using redirects through the browser, this model allows a user’s mobile device to be decoupled from the flow and the client application, and act as an authentication device on which the user authentication and the consent confirmations are performed.
The important point here is the client application and authorisation application / service do not have to run on the same device (for example, smartphone) or be linked.
In the CIBA flow the initial authorisation call is made to the new (OAuth2) backchannel authentication endpoint, and the authorisation server then delegates the authentication and consent approval tasks to the authentication device (smartphone) of the user, who will accept or deny the request.
The access token being sent to the client is managed by one of 3 flows:
Poll — the client polls the authorisation server until the authorisation server has received the approval from the authentication device
Ping — the client waits until it is notified by the authorisation server and then it requests the token
Push — the authorisation server, when it receives approval from the authentication device, pushes the access, ID token and refresh token to the client.
3.5. Authorisation
Authorisation is the act of performing access control on a resource. Authorisation does not 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 focuses on authorisation and provides additional patterns that work with OAuth or provides an alternative.
3.5.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 (for example, administration account).
Once a user is authenticated (for example, 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 (for example, microservices) and less monolithic. This will result in a need for fine-grained authorisation support at the request point. The API gateway will support either using OAuth 2.0 or its own proprietary capability.
The 2 types of authorisation that are covered are:
role-based or group-based authorisation — where membership in a role or group determines access rights for the consumer
policy-based or attribute-based authorisation — where characteristics of the consumer are evaluated to determine access rights for the consumer.
Figure 20: Authorisation techniques
Figure 20 lists the following 2 authorisation techniques that grant users the right to perform an action or access to information, via an API gateway, and where these are used:
Groups / roles based — recommended for internal-facing APIs and could be used for external-facing APIs
Policy / attribute based (using OAuth 2.0) — recommended for internal- and external-facing APIs.
These authorisation techniques are described in more detail in sections 3.5.2. to 3.5.4.
View larger image (PNG 20KB)
3.5.2. Roles-based access controls (RBAC)
In many organisations Active Directory (AD) provides the authentication services for users. AD 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.
AD (or LDAP) groups are synonymous with roles and can be used to provide coarse-grained authorisation for APIs.
3.5.2.1. Scopes (limited fine-grained access)
Based on the services (APIs) that are exposed, additional access controls can be applied using scopes. For example, a data service might provide ‘read’ and ‘write’ scopes that could be granted to a user based on the AD groups they were in.
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, for example, 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-/or fine-grained access and represent specific access rights, for example, 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- or 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 bound 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 NZ Business Number (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.
The NZBN update scope would look like:
https://api.nzbn.govt.nz/auth/pbd.readwrite
Whereas a read-only scope would be:
https://api.nzbn.govt.nz/auth/pbd.core.readonly
3.5.3. 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, for example, 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-grained authorisation services.
The really important control that ABAC provides is the ability to provide context when applying access controls, for example, access decisions can be based on the IP address of the device, the operating system of the client and the last known transactions of a client.
The recognised standard for ABAC is eXtensible Access Control Markup Language (XACML), which is based on Extensible Markup Language (XML).
3.5.4. 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:
an identity store containing groups
an identity access management system
a policy server.
Figure 21: API gateway for authorisation
Figure 21 illustrates an API gateway providing authorisation to a customer (using an application on their smartphone) to gain access to backend services, via a direct connection over Transport Layer Security (TLS) to:
a vendor identify access solution, or
an identity store, or
an eXtensible Access Control Markup Language (XACML) policy server.
View larger image (PNG 31KB)
4. Security controls
This section looks at additional controls that should be considered and implemented when protecting APIs.
The 5 areas that should be considered are:
Threat protection
Logging and auditing.
Depending on the classification of the information that is presented in the APIs and the risk framework applied, different access controls will need to be applied.
Appendix F provides more detail about the security controls that can be applied.
4.1. Confidentiality and integrity
Confidentiality and integrity cover the handling of request and response data, both in transit and at rest. The aim is to protect the payload content from unauthorised access, manipulation or faking. An API request needs to be received intact by the API, with validation as to the source of the request. Untampered API responses need to be received by the consuming application, with confirmation that they are legitimately from the API.
4.2. Availability and threat protection
Availability in this context covers threat protection to minimise API downtime, looks at how threats against exposed APIs can be mitigated using basic design principles and how to apply protection against specific risks and threats.
Availability also covers scaling to meet demand and ensuring the hosting environments are stable. These levels of availability are addressed across the hardware and software stacks that support the delivery of APIs.
There are no specific standards for availability, but availability is normally addressed under business continuity and disaster recovery standards. These standards recommend a risk assessment approach to define the availability requirements. Find further information on business continuity and risks on the Standards New Zealand website.
For cloud services, Digital.govt.nz provides an assessment tool that includes a risk assessment tool which covers availability, business continuity and disaster recovery related questions.
As mentioned in section 1.3. Risks, there are various types of risk that impact APIs. This includes threats to availability as well as confidentiality and integrity. Many threats can be mitigated as indicated in section 1.3.1. Mitigation approach and good secure coding practices using OWASP guidelines.
Where the resources being exposed by an API are sensitive — for example, not public data — it is advisable to perform:
threat assessment — early on in the API development lifecycle
penetration test — once an API is developed and published (testable).
There are also automated vulnerability testing tools that can be used to give an indication of vulnerabilities in web application designs.
4.3. Logging and alerting
Traditional logging, alerting and incident management practices also apply to APIs, along with additional considerations such as:
correlating API requests with specific backend system activity and the resulting API responses to support end-to-end tracing
identifying specific API requests from consumers to help resolve API consumer problems
detecting events that may indicate a malicious attempt to access an API.
5. API security use case
Figures 22 and 23 illustrate a sequence of information exchange events and highlight where security controls are implemented.
5.1. High-level view
Figure 22 shows the high-level interaction of the actors and participant service providers in the use case of invoicing and paying ACC levies.
Figure 22: API security use case high-level view
Figure 22 illustrates an API security use case high-level view using a Unified Modelling Language (UML) sequence diagram that shows interactions between different actors in the use case of invoicing and paying ACC levies.
The sequence is:
ACC presents invoice for levies to Application.
Application pays invoice to Broker (for example, Xero).
Broker creates payment consent to Bank.
Bank provides consent screen to Application.
Employer provides consent to Application.
Application sends approval to Bank.
Bank requests payment to Broker.
Broker submits payment to Bank.
Broker pays invoice to ACC.
ACC provides receipt to Broker.
Broker notifies Application.
Application provides review to Employer.
View larger image (PNG 204KB)
5.2. Detailed-level view
Figure 23 shows the detailed interaction of the actors and participant service providers.
Figure 23: API security use case detailed-level view
Figure 23 illustrates an API security use case detailed-level view using a Unified Modelling Language (UML) sequence diagram that shows interactions between different actors in the use case of invoicing and paying ACC levies.
Compared with figure 22, ACC also has an ACC control and an ACC boundary. The Bank has a Bank control and Bank boundary.
The diagram has 4 detailed sections:
Section 1 — get ACC access token
Employer requests ACC login to Application.
Application requests login to ACC boundary.
ACC boundary requests login to ACC control.
ACC control redirects login challenge to Application.
Employer answers login challenge to Application.
Application relays login challenge answer to ACC control.
ACC control gives auth token to Application.
Application exchanges auth token for access token to ACC control.
ACC control issues access token to application.
Application gets invoice for levies with access token to ACC.
Employer wants to pay invoice to Application.
Application issues pay invoice instruction to Broker (for example, Xero).
Section 2 — payment consent issuance
Broker creates payment consent to Bank boundary.
Bank boundary forwards payment consent to Bank control.
Bank control asks for consent details to Bank.
Bank provides details to Bank control.
Bank control redirects with login and consent screen to Application.
Section 3 — get access token for payment action
Employer logs in to bank and provides consent to Application.
Application provides login and consent to Bank control.
Bank control issues auth token and ID token to Broker.
Broker exchanges access token with auth token to Bank control.
Bank control grants access token to Broker.
Section 4 — bank payment finalisation
Broker sends approval with access token Bank.
Broker submits payment with access token to Bank.
Broker advises invoice paid to ACC.
Application sends review to Employer.
View larger image (PNG 149KB)
6. Appendix A — Standards for securing RESTful APIs
Table 3 captures (current) security standards that should be part of any API security strategy, ordered by type.
Note the provisioning standards(2) are included to complete this standards table. This enables it to be used by architects to select the most appropriate option.
Table 3: API security standards
Provisioning standards
SCIM
System for Cross-domain Identity Management is a RESTful API-based framework for Real Time provisioning and, like SPML, moves away from batch-based and delta-based provisioning processes. It uses a RESTful API to manage the provisioning of users.
As SCIM is a REST API framework, it should be secured using OAuth.
SPML
Service Provisioning Markup Language is an XML-based framework for facilitating the exchange of provisioning information (creates, updates and deletes) on user objects (for example, an LDAP directory). This is normally implemented to provide Just-in-Time (Real Time) provisioning.
Although now regarded by most as a legacy standard, it is still supported by most vendors and used by niche service vendors.
Security standards
2 (multi)-factor authentication
A method of confirming a user’s claimed identity (authentication) by using 2 or more pieces of evidence, relating to something they know, something they have and something they are.
Abbreviated Language for Authorisation defines fine-grained authorisation rules in a JSON-like policy language.
This language helps remove one of the greatest barriers for implementing XACML, which is complexity in writing of the access control policies.
Authorisation standards
Provides a framework for controlling access to resources.
CIBA
Client Initiated Backchannel Authentication is a decoupled grant flow that allows the end user to use their mobile device to authenticate and approve transactions.