Securing HTTP-based APIs

Applications often need to interact with APIs on behalf of users, but traditional user authentication methods are not well-suited for this purpose. Instead of using a user’s credentials, a more secure approach involves the user authenticating through an identity provider. This process generates temporary credentials, such as tokens or cookies, which the application can then use to securely interact with the API.

For more information refer to the NCSC’s guidance on choosing authentication methods and multi-factor authentication for your corporate online services

Good practice for secure API authentication includes the following:

Secure generation and exchange

A credential should be generated in a secure environment, and preferably not exported from where it has been generated.  This is especially the case for credentials based on public key cryptography. If a credential needs to be exported (normally the case if symmetric keys are used), then this must be done using secure transit, and the process should be automated with little or no human involvement. 

Avoid hard-coding credentials directly into source code that is stored in version control, especially if the repository is publicly accessible or shared widely. Once checked into version control, secrets may be difficult to fully remove. Attackers often scan public repositories to find such credentials.

Secure credential storage

Ensure your API credentials are securely stored. Consider using a secrets manager (with a secure storage backend like a HSM or cloud KMS), or storing credentials on a tamper-resistant hardware-backed storage location (such as a USB token or TPM). Poorly secured secrets will increase the likelihood of an attacker being able to steal your credentials, especially if you have secrets stored in multiple places which makes auditing difficult (a problem that’s known as 'secrets sprawl').

For short-lived credentials (or for authenticating to low-value applications) you may use software-backed storage. You should balance the length of time a credential is valid with the value and the storage method used.

Credential lifetime

The lifetime of a credential should be only set to the appropriate amount of time appropriate to the use case and threat. Credentials should be automatically rotated or renewed when they expire, the process of rotation should be automated with no human involvement.  If a credential can't be stored in a secure storage method or if the credential is not replay resistant, then you should mitigate the risk by making them short-lived. 

Avoid using long-term access keys which may grant indefinite access if compromised, potentially exposing data and services. Attackers who gain access to these keys can misuse your API resources until the keys are rotated or revoked. Using a shorter-term key will reduce the time window that an attacker can use a key before it becomes inactive (and is then of no use to an attacker).

Replay-resistant credentials

Use credentials that have protection from being replayed. This could be achieved by using credentials based on public key cryptography, such as certificates or a signed JSON web token (JWT). Credential use should be part of any monitoring strategy and any misuse should be alerted.

Avoid weak authentication methods

Don't use weak authentication methods such as basic authentication or API keys. Basic authentication transmits usernames and passwords within each request in a Base64-encoded format, while API keys are placed in a http header and are shared bearer tokens. Both these methods can be easily compromised, often due to poor secrets management. They also often offer broad access without expiration or the ability to limit permissions. You should instead adopt stronger authentication methods (like signed JWTs or certificates) which should be implemented and managed as per NCSC guidance. 

Once a user is authenticated, it is important to control what actions they can perform and what data they can access within the API. Authorisation governs access to resources based on the identity and privileges of the requesting entity. Unless you are hosting a completely open public API, it is essential to implement an authorisation framework.

Three fundamental principles guide effective authorisation governance:

1. Enforce least privileges: grant users or processes the bare minimum access rights necessary for their tasks, thus restricting potential security breaches or malicious activities.
2. Deny by default: restrict access by default, permitting entry only to explicitly authorised entities.
3. Validate permissions on every request: continually verify access permissions for each action within a system.

Granting excessive permissions to tokens increases the risk of data leakage or misuse of services. This commonly results from using generic keys or tokens with too broad scope, with full access to various endpoints. 

OAuth 2.0 and OpenID Connect (OIDC) are two complementary industry standard frameworks for securing API access and user identity management. You can use a family of standards to achieve our authentication and authorisation guidance.

1. OAuth 2.0 is an authorisation framework that enables third-party applications to access resources on behalf of a user without exposing their credentials. It facilitates secure delegated access using tokens but does not inherently provide authentication or identity verification. 
2. OpenID Connect extends OAuth 2.0 by introducing an identity layer that enables applications to authenticate users and retrieve identity-related claims via JWTs. It does this by incorporating an ID token, which contains verified information about the authenticated user. This extension facilitates Single Sign-On (SSO), allowing users to securely access multiple applications without needing to re-enter credentials.

Recent advancements in OAuth have introduced improved security mechanisms for credential protection, such as certificate-bound tokens and Demonstrating Proof-of-Possession (DPoP). Although relatively new, these security enhancements are widely supported and strongly recommended as part of the OAuth 2.0 Best Current Practice (BCP) guidelines to mitigate risks like token theft and replay attacks.