1.4 Authentication


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 doesn’t 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 lifecycle, such as service deprecation, or notification of an outage. It also enables the API provider to implement different service levels for different consumers. E.g. 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.

1.4.1        Authentication Techniques

The diagram and table below lists the authentication techniques that can be used to secure APIs and provides guidance on when to use them.

 Illustration of Authentication Options

Figure 12: Authentication Options

Each of these is described in more detail in the subsections below.

1.4.2 Anonymous Authentication


This is where the customer and the application they are using can gain access to backend API services without needing to authenticate in any way.

Illustration of Anonymous Authentication Model 

Figure 13: Anonymous Authentication Model

This approach can be used when the risk associated with the API is negligible e.g. 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 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 pattern 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 back end application server which 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 (Open Web Application Security Project) web site. Typically, these relate to:

  1. Throttling to prevent Denial of Service attacks
  2. Message analysis to block HTTP attacks 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 (e.g. based on IP address). This capability can be applied using an API Gateway, or existing capabilities (e.g. firewalls, load balancers etc) may be able to provide this level of protection

1.4.3 Username and Password Authentication (Direct Authentication)


In the Direct Authentication model 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 (e.g. Active Directory) whilst external users (e.g. 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.

 Illustration of HTTP Basic/Digest Authentication Model

Figure 14: HTTP Basic/Digest Authentication Model

This model can be easy to implement but has many limitations:

  1. An identity store (e.g. LDAP) is required along with a full registration process for all user types (e.g. applications and application developers)
  2. Cannot leverage a federated authentication model, so no single sign on (SSO), requiring re-presentation of username and password at every step
  3. Password would be in clear text. If direct authentication is used, TLS would be required to secure all communications
  4. Open to brute force attacks
  5. 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 NZ Evidence of Identity Standard for guidance on customer authentication. If considering using this model for internal users, preference would be a Single Sign-On solution using Kerberos.

1.4.4 API Keys Authentication


API keys should be used for every system-to-system interaction with a production level API.

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.

Illustration of  API Key Authentication 

Figure 15: API Key Authentication

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 which 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 below:

  • 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. 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:

  1. More secure - greater entropy than passwords – random long string of characters
  2. Speed – API keys do not involve any hashing process, i.e. 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.

1.4.5 Certificates (Mutual) Authentication

Use this model when the API requires stronger authentication than offered solely by API Keys, and the overhead of certificate management is warranted.

In Certificate (Mutual) Authentication, 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 app. The app 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. 

 Illustration of Certificate Authentication

Figure 16: Certificate Authentication

This is Not Recommended for customer authentication as there would be a high overhead in terms of certificate management.

This is Recommended for consuming application to server (gateway) or API to back end communications (if needed).

Refer to the NZ Information Security Manual for guidance.

1.4.6 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 two factor) login process (See Figure 17) and a user store. Further details for this are not provided in this document, but a vendor API Portal will normally provide their own authentication solution and user store, or can integrate with an existing identity and access management system.

 Illustration of API Portal Login Page

Figure 17: API Portal Login Page

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:

  1. Provide contact details e.g. email address
  2. Register the application they are developing

The API Portal should provide registration services for the client application to use:

  1. API keys for basic authentication services and API monitoring
  2. OAuth services and the management of Client ID sand a Client Secrets (for applications)
  3. Additional production authentication and authorisation service e.g. basic, certificate etc.

1.4.7 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 smart phone capabilities can be leveraged to provide this additional factor, but other options are available, like smart cards or hardware tokens.

Page last updated: 18/12/2016