Learning Center
API Gateway
11 min read

API Gateway Authentication

API gateway authentication is an important way to control the data that is allowed to be transmitted using your APIs.

What is an API Gateway? In essence, it authenticates that a particular consumer has permission to access the API, using a predefined set of credentials. There are special cases — for example, the option to allow anonymous authentication — but generally speaking, the aim of API authentication is to deny access to consumers who fail the authentication test. Kong supports many different plugins to enable different methods of API gateway authentication we'll look at some of the most commonly used below — and can even support multiple methods for authentication. You can combine multiple methods using AND and OR logic, allowing you to establish more complex authentication procedures that only allow access in very specific circumstances.

In this article, we will look in more detail at how API gateway authentication works, why it is important and the main methods commonly used in an API gateway to authenticate access requests.

Why is API gateway authentication important?

APIs, generally speaking, represent a way to request or receive data from an endpoint and return it to your central data store.

That endpoint can take one of several different forms:

  • A human end-user accessing your API via a web-based application or mobile app
  • A piece of hardware or equipment returning data via an Internet of Things (IoT) API
  • An employee or partner using an internal API to submit or process data

In all cases, authentication matters. For external APIs, including human-facing and IoT APIs, it makes good sense to authenticate the endpoint before allowing it to transmit data via the API. This protects against mistaken and malicious submissions of data, helps to manage the total amount of data transmitted and provides a necessary layer of security so that you can implement access control, including the option to cut off access when a subscription expires. For internal APIs, authentication might seem less significant, but it is still an important step in verifying that the data transmitted is authorized and that you want to transmit it to your data store.

Authentication also gives you an opportunity to determine how a failed request is handled. That might mean simply blocking the request and returning an error code, but in some circumstances, you might still want to provide limited access. Kong allows for this via anonymous authentication, which we will look at in more detail below.

How does an API gateway enable authentication?

Kong supports a number of authentication plugins. These can be used to control traffic to upstream services, including both APIs and microservices.

Authentication plugins can be configured to apply to service entities within the an API gateway. In turn, service entities are mapped one-to-one with the upstream services they represent, essentially meaning that the authentication plugins apply directly to those upstream services. There are several different ways to authenticate access, which we will look at in a moment, including generic authentication, anonymous access and multiple authentication.

Kong also supports API key authentication, a powerful way to authenticate consumers by allowing end-users to provide an authorized API key via a header or querystring. API key authentication is one of the most popular ways to conduct API authentication and can be implemented easily using Kong's Key Authentication plugin to create and delete access keys as required.

By combining different methods of API authentication using multiple Kong plugins, as well as different levels of authentication like generic, anonymous and multiple authentication, you can set up sophisticated permissions for the data requests received by your Kong services and routes.

What are the most common methods of API gateway authentication?

Kong's library of plugins includes simple ways to implement the best-known and most widely used methods of API gateway authentication. Simply add the relevant plugin to your Kong deployment and you're ready to start authorizing consumers in the appropriate way. That can mean assigning credentials to individual consumer entities, configuring limited access for anonymous users or using some other method of verifying an entity when it makes an access request.

Plugins make it easy to add new authentication methods to your Kong deployment, with full documentation to help you configure the plugin in minutes and start authenticating requests using the new method immediately. Combining multiple methods of authentication using AND and OR logic is also easy when you need to set up a more complex authentication process or when you want to add a secondary method of authentication to one that you already use.

Some of the most common methods of API gateway authentication include:

Basic Authentication

Enable basic authentication to access a service using an assigned username and password combination. The Basic Auth plugin checks the Proxy-Authorization and Authorization headers for valid credentials and approves or denies the access request accordingly. Basic Auth can be used with both HTTP and HTTPS requests and is an effective way to add simple password protection to web applications.

Key Authentication

As mentioned above, KeyAuth checks for an API key to grant access to a specific service or route. Again, this is compatible with both HTTP and HTTPS protocols and has the option of a fallback anonymous consumer to provide limited access if initial authentication fails.

OAuth 2.0 Authentication

Support the industry-standard authentication protocol OAuth 2.0 using a simple plugin to enable access with the option to issue time-limited tokens which must be refreshed once they expire. OAuth 2.0 is compatible only with secure HTTPS services and should, therefore, be used with routes that are configured to only accept the HTTPS protocol.

Learn how to set up Kong Gateway OAuth2.

LDAP Authentication Advanced

LDAP authentication advanced is available with Kong Enterprise subscriptions and enables LDAP Bind Authentication with protection via a username and password combination. It can be enabled on a service, route or on older versions of Kong with the legacy API entity. It can also run as a global plugin, which means it will run on every request that is received. Like key authentication, LDAP authentication advanced allows an anonymous consumer value to be used in the event that authentication fails, for limited access without a valid password.

OpenID Connect

OpenID Connect is a plugin that is available to Kong Enterprise customers and supports a variety of credentials, including:

  • Signed JWT access tokens
  • Opaque access tokens via Kong OAuth 2.0 or third-party IdP
  • Session cookie credentials set up between the client and Kong
  • Authorization code using OpenID Connect authorization code flow
  • Client ID and secret via OAuth 2.0 client credentials grant
  • Username and password via OAuth 2.0 password grant

Using OpenID Connect API gateway plugin, Kong can act as a proxying OAuth 2.0 resource server and also as an OpenID Connect Relying Party.

Other Methods

There are several other ways to authenticate API gateway access using Kong plugins, including both Kong Gateway and Kong Enterprise. Among them are:

And on Kong Enterprise only:

Full documentation of all the plugins listed above is available from Kong Hub.

Microservice authentication with API gateway

To authenticate access to an upstream microservice using the Kong API gateway, you must create a service associated with that microservice. Remember, a service entity is mapped one-to-one with the upstream microservice or API that it represents, so in essence, once this entity is created, you can think of the service and the upstream microservice as being one and the same. You must then specify a route so that Kong knows how to transmit the data it receives to the appropriate service entity.

Many different routes can point to the same service entity, allowing individual services — and therefore the upstream microservice or API they are mapped onto — to play a role in different routes, for example, to allow authentication in different ways for different user groups. Once you have established the appropriate service entity and route or routes, you can then configure your chosen authentication plugin to allow or deny access according to the user's credentials.

The precise way in which this is done depends on the plugin and the authentication method, but again, full documentation is provided to help you understand what credentials each plugin requires to return successful authentication. It is a good idea to familiarize yourself with the documentation for each of the authentication plugins you use, as functionality and compatibility can vary.

Different levels of authentication

As mentioned above, it is possible to provide for different levels of authentication using one or more plugins, increasing the potential to construct more complex methods of authentication. Some of the primary examples of authentication levels include:

Generic Authentication

Generic authentication simply checks the supplied credentials against a basic authentication test. If the credentials pass the test, it adds the relevant credential details and consumer information to the headers and forwards the request on. If the credentials fail, the request is blocked, with no fallback alternative. This means you can restrict access only to authorized individuals via a range of different methods — for example, a one-factor username and password login, or an API key.

Kong supports many different authentication plugins as listed above, giving you plenty of options when it comes to deciding on the type of credentials you require to be supplied in the access request.

Anonymous authentication

In some cases, you might want to allow anonymous access for end-users whose credentials fail the initial authentication test. For example, this could allow you to provide a limited service to non-subscribers while unlocking a more complete, higher capacity or higher-speed service for subscribers. Anonymous authentication typically involves specifying an 'anonymous' consumer ID in the plugin configuration, and if authentication fails, access is provided using this ID instead. It is worth noting that using anonymous authentication, the request will be shown as successful because access was granted — albeit via the specified anonymous consumer ID.

Where anonymous authentication is not defined, the request will show as having failed, with a 403 Forbidden response. These are mutually exclusive options — so if an anonymous consumer ID is used as a catch-all for failed requests, you should not expect to see the 403 Forbidden response.

Multiple authentication

Multiple authentication allows several plugins to be used to authenticate access to a single service entity and therefore to the upstream microservice it represents — or to a route you have defined in Kong. You can configure the behavior of these methods such that authentication must pass all of the credential checks in order to be given access equivalent to a logical AND statement. This means users must provide more correct credentials in order to gain access, allowing for two-factor (or more) authentication to be established, which significantly decreases the risk of unauthorized individuals gaining access through a brute force attack or leaked credentials.

Alternatively, the multiple methods can be set up in a logical OR configuration by specifying an anonymous consumer ID in the configuration of each method. In this case, if any one of the credential checks is passed, access will be granted, while if all of the tests are failed, access will be granted via the anonymous consumer ID as a catch-all fallback option.

Finally, it is also possible to create an OR configuration without providing anonymous fallback access to requests that fail every credential check. This catch-all anonymous access can be blocked using the request-termination plugin to instead return a fail code, thereby ensuring that every logical combination of authentication options is open to you without giving anyone unauthorized access.

Authenticate an API gateway call to another API gateway

Finally, in certain circumstances, it may be necessary for one API gateway to call another API gateway - for example, for an office network behind an API gateway to request data from a remote server farm that is also behind an API gateway. Authentication of such calls can provide an important extra layer of control to make sure that only valid and authorized requests are passed between the two gateways.

Often these types of data requests occur between two gateways that are both within your direct control as part of a distributed network or wide area network, giving you admin access to the security configuration of both gateways. Because of this, gateway-to-gateway access is often achieved by authorizing the specific IP address used by each gateway within the security settings of its counterpart, creating an IP tunnel between the two.

Whitelisting the other gateway, combined with the option of communicating via a secure VPN, effectively blocks access to data requests from all other IP addresses, limiting access to just one IP where appropriate for maximum security. In scenarios where one API gateway needs to call another, this is one option to allow it to do so without opening that gateway to unauthorized data requests from third parties.