tombcghtech/api_guidelines huggingface dataset:
The contents of tokens and pieces of information asserted about a subject. For example, an ID token can contain a claim called mobile that asserts the subjects mobile phone number.
Delegated authorisation
Provides a framework for delegating the specified access rights to a third party.
Federation / authentication
Provides authentication and SSO services to customers and secure transportation of authentication and authorisation information.
FIDO U2F
The FIDO Alliance Universal Second Factor is an open authentication standard that can be incorporated into an API security framework.
JSON security standards
A set of standards that provide security around the exchange of tokens, based on JSON.
JSON Web Algorithm defines the algorithms used for encrypting the JWT.
JWE
JSON Web Encryption standard provides integrity validation and can be used with or without digital signatures.
JWK
JSON Web Keys represent the cryptographic key used for encrypting JWT. The algorithms for these are defined in JWA.
JSON Web Signature is a standard for signing JSON, thus providing a level of authority (where it has come from) and integrity, by proving the JWT has not been changed in transit.
A JSON Web Token is designed to be compact and provides trusted information that is used in the authentication process.
Used in API security to pass identity information, specifically by OpenID Connect.
An interoperability authentication protocol based on the OAuth 2.0 framework.
This is a relatively recent federation protocol that provides lightweight federation services. It is like SAML, provides SSO services and allows the secure exchange of user authentication data, but it is not as feature rich as SAML.
As it is based on REST / JSON, it is perceived as the federation service of choice for mobile services.
Derived from the original OAuth 1.0 specification (Request for Comments (RFC) 5849) that provides a method for client applications to access resources on behalf of a resource owner. It is an authentication framework around the exchange of signed tokens. It has now been made obsolete by OAuth 2.0.
An open standard for a delegated authorisation framework. It is not backward compatible with OAuth 1.0, but is modelled on the framework with the objective of providing greater flexibility, and defines specific credential (grant) flows.
It is also based on token exchange, with the primary difference being that the tokens are secured by mandating TLS on all communication connections (RFC 6749), where the OAuth 1 tokens are digitally signed.
OAuth 2.1
An update to OAuth 2.0.
The OAuth 2.1 Authorization Framework — IETF.
PKCE
Proof of Key Code Exchange provides enhanced security for the authorisation code flow.
Security Assertion Markup Language is an XML-based, open-standard data format for exchanging authentication and authorisation data between parties, in particular, between an identity provider and a service provider.
SAML is seen as complex but is regarded as a high-level security framework.
As it is based on XML, SAML can have high payload overheads and thus can result in performance issues in the mobile application space.
It is still widely used but its uptake is declining. It is included in this standard to support existing New Zealand SAML instances (for example, education, RealMe).
TOTP / HOTP
Time-based One-Time Password and Hash-based Message Authentication Code (HMAC)-based One-Time Password can be used in any of the authentication processes that are part of the process of gaining access to APIs. The requirements for these would be based on business requirements and risk analysis of the information or service being exposed by the API.
These could be used to add a U2F to any existing or proposed authorisation mechanisms.
User-Managed Access is an OAuth-based access management protocol standard.
It builds on OAuth 2.0 to provide additional delegated authorisation capabilities.
Its key focus, for RESTful APIs, is to enable an individual (resource owner) to manage and define a set of access control policies that can be managed by an authorisation server, which controls access to a set of APIs.
XACML
The eXtensible Access Control Markup Language standard is XML-based and defines a fine-grained attribute-based access control policy language.
It provides an architectural model and policy terminology that can be used to separate out the functions of any authorisation framework.
As it is based on XML it is sometimes perceived as a legacy standard, but, from a RESTful API perspective, it provides a fine-grained attribute-based authorisation framework (RFC 7061).
Industry-specific standards
FAPI
Financial Grade API is an OpenID workgroup that now defines a set of specifications that enforces in specific legislation, for example, Open Banking (NZ) and Customer Data Rights (Australia)
FHIR
Fast Healthcare Interoperability Resources is a standard describing data formats and elements and an API for exchanging electronic health records.
NZ Trust Framework
The framework that is driving NZ future Digital Identity direction.
Digital Identity Services Trust Framework
Payments New Zealand is a government body that is driving the Open Banking initiative in New Zealand.
7. Appendix B — Authentication
Find out more about different authentications used while implementing an API.
7.1. Anonymous authentication — Not recommended
Figure 24 shows an anonymous authentication model where the customer and the application they are using can gain access to backend API services without needing to authenticate in any way.
Figure 24: Anonymous authentication model
View larger image (PNG 21KB)
Anonymous authentication can be used when the risk associated with the API is negligible, for example, an API offering publicly available information. It can be used for internal APIs if the agency’s security policy allows.
The downside of this model is that it makes it difficult to gather effective analytics, and therefore to understand the implications of proposed changes to, and deprecation of, an API.
Although it is not recommended to use this model, it sometimes has to be included to support the scenario where a web application is making calls, on the home or login page, to a backend application server that stores the pages and the related JavaScripts. In this case it is the API gateway that provides the security, along with the due diligence required to ensure these pages and associated JavaScripts do not contain information that should be secured.
The anonymous authentication model should be protected against typical API vulnerabilities and threats, as listed on the OWASP web site. Typically, these relate to:
throttling to prevent DoS attacks
message analysis to block HTTP attacks and parameter attacks such as cross-site scripting, SQL injection, command injection and cross-site request forgery.
Note: If this approach is used, it might be appropriate to restrict access to the API based on other information (for example, based on IP address). This capability can be applied using an API gateway, or existing capabilities (for example, firewalls, load balancers) may be able to provide this level of protection.
7.2. Username and password authentication (direct authentication) — Not recommended
In the direct authentication model, illustrated in figure 25, the user is authenticated via an identity store using username and password (or hash) credentials over secure communications.
Username and password authentication is suitable for development purposes, during training or the initial stages of development, because it reduces the barrier to accessing the API. It could also be used for internal APIs, if the agency’s security policy allows, and may be suitable for customers if the identity risk associated with the API is low.
Internal users would likely use an internal LDAP directory (for example, Active Directory (AD)) while external users, for example customers, would require a separate identity store. The API gateway could provide the authentication services and, for external facing APIs, also threat protection services.
API security is provided by the application (web) server acting as a trusted subsystem with TLS links to the backend API server. The application / web server invokes the backend and provides the required user ID information, which can be in the form of a session token.
Figure 25: HTTP basic / direct authentication model
This model can be easy to implement but has many limitations including:
an identity store like LDAP is required along with a full registration process for all user types (for example, applications and application developers)
it cannot leverage a federated authentication model, so no SSO, requiring re-presentation of username and password at every step
passwords would be in clear text — if direct authentication is used, TLS would be required to secure all communications
it is open to brute force attacks
passwords have low entropy, have to be reset and managed, and are difficult to revoke at a granular level.
This model can be used for testing and development purposes but is not recommended for production APIs — API keys are preferred.
Refer to the Identification Management Standards for guidance on customer authentication. If considering using this model for internal users, preference would be a SSO solution using Kerberos.
Identification Management Standards
Kerberos — Wikipedia
7.3. API keys authentication — Recommended
API keys are a digital authentication mechanism, with the API key taking the form of a long string of generated characters.
API keys are usually unique and can be assigned to an application, developer or user. The usual practice is for an application developer to obtain a key for their application from the API provider and utilise the key within their application.
To obtain an API key, the developer must undergo a registration process with the API provider. The steps involved in the registration process are dependent on the level of risk associated with the API.
Figure 26: API key authentication
As illustrated in figure 26, at run time, the consuming application automatically passes the API key to the API every time it requests an API resource. The API gateway validates the API key against the API key store (which can be part of the API gateway functionality or provided by another secure device) before allowing the consuming application access to the requested API (or set of APIs) and backend resources.
This model is similar to the username and password model, but it is the API gateway that can be responsible for creating, managing the API key and API secret, and storing a copy in the API key store for validation, rather than redirecting to an identity store for policy validation and approval.
Username and password authorisation models can have high administration and response time overheads (relating to cryptographic functions). API keys are not linked to users and require no cryptographic functions. Like usernames and passwords, they come in pairs and are defined as:
API key — public unique identifier — a 40+ random character string to authenticate the consuming application to the API
API secret — private unique identifier — only known by the API gateway and used to validate the API key. The API secret in this model is not passed over the network.
API keys should be used wherever system-to-system authentication is needed (especially with a production level API). They are suitable for simple public APIs which do not need more complex authentication models. API keys should be used in preference to username and passwords because they are:
more secure — greater entropy than passwords – random long string of characters
speedier — API keys do not involve any hashing process, that is, the hashing process required for passwords.
However, the risk is that anyone with a copy of the API key can use it as though they were the legitimate consuming application. Hence, all communications should be over TLS, to protect the key in transit. The onus is on the application developer to properly protect their copy of the API key.
If the API key is embedded into the consuming application, it can be decompiled and extracted. If stored in plain text files they can be stolen and re-used for malicious purposes.
Note: API keys are recommended as they provide a level of security to public APIs that can help protect sites from screen scraping or provide the required information to throttle, or possibly bill, access to data.
Organisations need to carry out a risk analysis of the possible threats against the classification of the data that could be obtained and from this decide if API keys are required.
7.4. Certificates (mutual) authentication
When the API requires stronger authentication than offered solely by API keys, and the overhead of certificate management is warranted, use the certificate authentication model.
In the certificate (mutual) authentication model, illustrated in figure 27, internal and external parties are authenticated with each other. Both the consuming application and the API provider hold a digital certificate. The digital certificate can be trusted because it was issued by a mutually trusted certificate authority (CA). When the consuming application makes a request to the API, the server hosting the API presents its certificate to the consuming application. The application verifies the server’s certificate then sends its own certificate to the server. The server verifies the client certificate and mutual trust is achieved, allowing the consuming application to use the API.
Figure 27: Certificate authentication
View larger image (PNG 17KB)
Certificate authentication is:
not recommended for customer authentication as there would be a high overhead in terms of certificate management
recommended for consuming application to server (gateway) or API to backend communications (if needed).
For guidance, refer to the NZ Information Security Manual — Government Communications Security Bureau.
7.5. Developer authentication
Developer authentication will normally take place at the API portal when gaining access to APIs. The API portal will offer an authentication solution for developers to provide a username and password (possible 2 factor) login process (see figure 28) and a user store.
Further details for this are not provided in these guidelines, but a vendor API portal will normally provide their own authentication solution and user store, or it can integrate with an existing identity and access management system.
Figure 28: API portal login page
Figure 28 shows an example of an API portal login page for developers — the image is of a screen or interface for developers to log into a developer resource centre by:
entering their username or email address in the first field
entering a password in the second field
ticking a box in the ‘I’m not a robot reCAPTCHA’ field.
View larger image (PNG 117KB)
Once the developer has logged into the API portal they can browse and discover the APIs available. API portals normally require the consuming application developer to:
provide contact details like an email address
register the application they are developing.
The API portal should provide registration services for the client application to use:
API keys for basic authentication services and API monitoring
OAuth services and the management of client ID and a client secrets (for applications)
additional production authentication and authorisation service for example, basic, certificate.
7.6. Multi-factor authentication (MFA)
An application could use multi-factor authentication (MFA) to enhance other authentication techniques to mitigate identity risks. For example, by requesting a fingerprint from the customer in addition to their username and password (or API key).
Often smartphone capabilities can be leveraged to provide this additional factor, but other options are available, like smart cards or hardware tokens.
8. Appendix C — OAuth 2.0
OAuth 2.0 is a token-based authorisation framework and is defined and implemented using grant flow type patterns.
8.1. Grant flow types
There are 4 grant flow types supported by the OAuth 2.0. These define the different types of interaction a client application can perform to gain an ‘access token’ and thus access to the protected resource.
The different grant flow types are recommended for use in different situations for agencies implementing an API security framework. Recommendations are based on maximising the level of security for the APIs being exposed.
8.1.1. Authorisation code
Use for internal users or where the customer is the resource owner, your agency controls the resource server, but the authorisation server is not owned by the agency or is elsewhere within the organisation.
The authorisation server provides the authorisation code (grant) to the client application once the resource owner has approved the request.
The client application then uses this to request the access token.
The authorisation server validates the client application using the client ID and client secret. The client application has to store these credentials securely.
The client application authenticates to the authorisation server via its TLS certificate and call-back URL.
Useful if the API requires a customer of a client application to authorise access to a protected resource provided by the API.
Recommended to use
The most secure OAuth flow.
Use for public facing APIs for customer authorisation patterns. Use for pattern 1: internal use only. Use the state attribute to link request and response.
It is now recommended to include PKCE in this flow.
8.1.2. Implicit
Used when the client application resides on a device like a smartphone and cannot secure the credentials.
Only the access token is transmitted from the authorisation server to the client.
Not recommended to use
The least secure grant type.
If used, it should only be for information that is public and only for Government Electronic Tender Service (GETS).
8.1.3. Resource owner password credential
The resource owner’s username and password are used once as the authorisation grant to obtain an access token. The credentials are then discarded.
Use for customer authorisation pattern if authorisation code grant flow cannot be used. Use for pattern 1: internal use only to secure internal APIs that use active directory groups / Kerberos for authorisation and authentication if authorisation code grant flow is not available.
8.1.4. Client credentials
The client application is able to obtain access to the protected resource on its own behalf.
Use for:
pattern 6: authorising a consuming application from device to API
pattern 5: authorising a system to system interaction (B2B)using signed tokens
when the customer using the client, application is also the resource owner.
OAuth 2.0 introduced different grant types to provide organisations with the flexibility to support a variety of client application models. These specific models are not device driven — there is no specific device (for example, mobile) mapping to grant type; it is the level of risk an agency is prepared to support that needs to be defined to clarify which grant type should be selected.
For the application developer, the difference is in the infrastructure they need to provide, for example, the authorisation code grant flow type requires a managed server on which the client application runs.
The authorisation code is the most frequently used grant flow type as it is regarded as the most secure. It is covered in more depth in Appendix D. The implicit grant is the least secure and to quote from the OAuth RFC:
Implicit grants improve the responsiveness and efficiency of some clients (such as a client implemented as an in-browser application), since it reduces the number of round trips required to obtain an access token. However, this convenience should be weighed against the security implications of using implicit grants
OAuth RFC
These OAuth 2.0 grant flow types replace the 2-legged and 3-legged patterns used in OAuth 1.0.
There is now an RFC that has been defined that provides a device authorization grant flow (grant_type) that has been developed to address ‘browser less’ devices like a smart TVs, printers and uses another device to connect to the authorisation server to approve the request via a polling process.
9. Appendix D — OAuth 2.0 and OpenID Connect tokens and credentials
Find out how OAuth 2.0 and OpenID Connectand tokens and credentials are becoming a standard in access controls.
Access tokens are becoming a standard form of access control without the need for passing credentials. Anyone with an access token (bearer token) is permitted access to the resource being controlled, which makes tokens a target for stealing or copying. Hence it is important to keep the lifetime of tokens as short as realistically possible, depending on the type of resource being exposed and business risk appetite.
The OAuth framework (RFC 6749 and 6750) relies heavily on TLS for the security of the bearer token. The following RFCs offer additional integrity and confidentiality capability that can be applied to the bearer token (access token):
JSON Web Token (JWT) profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC 7523)
Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs) (RFC 7800).
There are 2 types of tokens, Opaque and JWTs. Both the access and refresh token can be presented in either form.
The Opaque tokens are produced by, and stored in, the authentication server. Each one has a specific task in the OAuth 2.0 framework.
The JWT tokens are produced and signed by the authorisation server but are not stored there. They are stored by the client application and when used are verified by the signature.
Table 4 provides a list of the main tokens and credentials that are used to provide authentication and authorisation services in the OAuth 2.0 framework.
Table 4: OAuth 2.0 tokens and credentials
Token description
Access tokens (Opaque)
Also called bearer tokens. No additional identity checks are carried out once this has been issued. Used by the client application to access protected resources on the provider, and it can be signed.
It is a random character string that also contains ‘scope’ information to allow additional access policies to be applied, for example, duration of access. It is granted by the resource owner via the authorisation grant token flow and enforced by authorisation and resource servers.
* The token is protected both in transit (TLS) and in storage (encryption).
* The ‘authorisation request header field’ format is only be used to transmit tokens.
Recommended:
* The lifetime of this token is set to 60 minutes.
* Scopes are used for coarse-grained and fine-grained access.
Not recommended:
* Form-encoded body parameter for transmission.
* Uniform Resource Identifier (URI) query parameter for transmission.
Refresh token (Opaque)
Used to obtain new access tokens when the old one expires or is invalid.
The token is protected both in transit (TLS) and in storage (encryption).
The lifetime of the token is set to 24 hours.
Opaque tokens vs JWTs
Access and refresh tokens can be delivered as an Opaque string or as a JWT that is signed and if required can be encrypted. Possible pros and cons of the JWT are JWTs:
* are self-contained as all the information required is within the token
* provide signing services to allow the verification of the token
* are harder to revoke.
* Organisations investigate both options and understand the differences between the 2 and define how 1 over the other can provide additional security controls or limits complexity.
Note: There is a move towards the JWT token as it can be used in the microservice space because the claims information is contained inside.
The authentication server sends the authorisation code to the client after being granted consent by the resource owner. Used to authenticate the client.
The lifetime of this token is set to 24 hours.
A 40+ random character string used in some scenarios to authenticate the client application to the API.
When implementing an authorisation solution that uses API keys. This is normally presented as an option in the developer API portal.
When registering an OAuth client application with the API portal, a client ID is issued. Used when interacting with the resource server.