API Gateway Authentication
Yong Qian
November 25, 2022
Importance of Authentication and Authorization for API Gateways
The core function of an API gateway can be summarized as connecting API consumers and API providers.
In practice, except for a few APIs that allow anonymous access, providers often restrict consumers: only eligible consumers can access the API. Besides, providers may not have the same access policy for different consumers, e.g., Consumers A and B can both access the /send_mail API, but the frequency of calls per minute needs to be calculated differently.
From the above two points, we can see that it is crucial to identify and verify the identity of API Consumers at the API gateway level. In the following, we will introduce how the open-source API gateway Apache APISIX implements authentication for consumers and authentication methods that are widely adopted by enterprises, and then further introduce how the user authentication system of APISIX can be used in conjunction with other security features to further enhance the security protection of API gateways.
Authentication and Authorization of Apache APISIX
Traditional HTTP proxies can only identify the requestor based on rough means such as request domain name and client IP, which is not enough for an API gateway. We need more refined authentication methods to address increasingly complex business requirements. One of the major advantages of APISIX over traditional proxies is its flexible plugin extension capability, including a collection of plugins for user authentication that can be divided into two categories depending on the implementation method:
- Interface with External Authentication Services
- Internal Gateway Authentication by Consumer Object Designed by APISIX
These two authentication methods will be introduced in turn.
Interface with External Authentication Services
Before an enterprise adopts an API gateway, there is often a separate authentication service deployed in the system. So how can we interface APISIX with the existing authentication service? APISIX provides a series of plugins that work by interfacing with various external authentication services and entrusting them to complete authentication.
For example, we can use the openid-connect plugin to interface with any authentication service that supports the OIDC protocol. The following is a sample configuration to interface with the keycloak service:
curl http://127.0.0.1:9180/apisix/admin/routes -H "X-Api-Key: your-API-key" -XPOST -d '
{
"uri":"/*",
"plugins":{
"openid-connect":{
"client_id":"apisix", // Generated when keycloak creates a client
"client_secret":"d5c42c50-3e71-4bbe-aa9e-31083ab29da4",
"discovery":"http://keycloak:8080/auth/realms/apisix_test_realm/.well-known/openid-configuration", // keycloak OpenID Endpoint
"scope":"openid profile",
"bearer_only":false,
"realm":"apisix_test_realm",
"introspection_endpoint_auth_method":"client_secret_post",
"redirect_uri":"http://127.0.0.1:9080/"
}
},
"upstream":{
...
}
}'
Internal Gateway Authentication
Consumer
When requests from various sources arrive at the API gateway, the gateway must identify these callers. Apache APISIX proposes the concept of "Consumer" to represent the callers of a certain type of service.
The Consumer object requires the configuration of an authentication plugin for use. Take the simplest key-auth plugin as an example:
$ curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: your-API-key' -X PUT -i -d '
{
"username": "jack",
"plugins": {
"key-auth": {
"key": "auth-jack"
}
}'
The above configuration means that when the request carries the specified key (auth-jack), the current request will be associated with the Consumer - jack. As you can see, the authentication plugin configured on the Consumer is actually an identity credential under a specified authentication mechanism. In the key-auth plugin, the key is the credential that identifies a consumer, similar to the username and password of the basic-auth plugin.
Configure Authentication Plugin for Route
Once we have associated the credential information with a specific consumer via the Consumer, we also need to enable the authentication plugin on the corresponding route:
$ curl http://127.0.0.1:9180/apisix/admin/routes/orders -H 'X-API-KEY: your-API-key' -X PUT -i -d '
{
"uri": "/orders",
"plugins": {
"key-auth": {
"header": "Authorization"
}
}
}'
The above configuration means that the key-auth plugin is enabled on the route /orders, and the authentication effect is as follows:
$ curl http://127.0.0.1:9080/orders -H 'Authorization: auth-jack' -i
HTTP/1.1 200 OK
...
$ curl http://127.0.0.1:9080/orders -H 'Authorization: wrong-key' -i
HTTP/1.1 401 Unauthorized
...
{"message":"Invalid API key in request"}
When a request from a user hits this route, APISIX will try to get the user-supplied key through the Authorization header. If it is not obtained, or the obtained key is not legitimate, then the request will be rejected directly by the gateway, thus protecting the upstream service.
It can be seen that in the above two authentication methods, the authentication plugin is at the core of the whole system, whose richness directly affects the choice of users for API gateways to achieve authentication. The following are some of the mainstream authentication methods and their respective advantages and disadvantages for your reference.
Mainstream Authentication Methods
Authentication and authorization, a basic mechanism that has existed since we entered the computer world, has evolved into a very diverse field after so many iterations over the years. The plugin mechanism of APISIX has greatly reduced the development cost of implementing various authentication methods. The following are some of the mainstream authentication methods already supported by APISIX:
Key Auth
Key Auth is the simplest of all authentication plugins, but it has a rich set of applications in real-world scenarios, such as licenses for paid software, tokens for identifying developers in open API platforms, etc., which can all be easily implemented with Key Auth. Moreover, based on APISIX's fully dynamic configuration and allocation capability, keys can be created and revoked quickly, taking effect in real-time.
Basic Auth
Basic Auth is an authentication method based on username and password, which is often used in web login scenarios. For example, the admin backend of a website can be used after the admin's logging in, where we can use Basic Auth to authenticate.
LDAP
LDAP (Lightweight Directory Access Protocol) is a lightweight file access protocol based on the X.500 standard, providing access control and maintenance of distributed information directories via IP protocol. With LDAP, the application and ops developers can control user access to resources at a granular level. With APISIX's ldap-auth plugin, you can easily interface with platforms that implement the LDAP protocol, such as Microsoft's Active Direcory, or OpenLDAP Server for Linux platforms, to finely control Consumer access to specific routes.
OIDC
OpenID is a decentralized online authentication system. For sites that support OpenID, users do not need to remember traditional authentication tokens such as usernames and passwords. Instead, they only need to register in advance with a website that acts as an OpenID identity provider (IdP), and can then use this account to log in to all applications that interface with that provider, e.g., to authenticate users of our own system through the accounts of well-known Google or Facebook services.
For OIDC, APISIX provides the openid-connect plugin, which can be used to interface with authentication services that support the OIDC protocol.
Forward Auth
When APISIX's standard authentication plugin does not meet your current needs, or if a dedicated and non-standard protocol authentication service has been deployed in your system, you may consider using the forward-auth plugin. Using this plugin, you can forward user requests to the authentication service via HTTP and return custom errors or redirect users to the authentication page if the authentication service responds with a non-normal status (error code other than 20x).
With the power of the forward-auth plugin, the authentication and authorization logic can be very cleverly transferred to a dedicated, non-standard protocol external service.
Linkage to Other Plugins After Authentication
User authentication is only the first step in securing the API with APISIX. Combining authentication capabilities with other security plugins will further amplify the gateway's security capabilities.
ACL（consumer-restriction）
In a complex backend system, there may be some APIs that have security restrictions that are higher than others, which require not only blocking anonymous users but also restricting authenticated users, e.g., allowing only whitelisted users to access the user management API.
In this case, we can use the consumer-restriction plugin provided by APISIX to implement the access control mechanism.
$ curl http://127.0.0.1:9180/apisix/admin/routes -H 'X-API-KEY: your-API-key' -X POST -i -d '
{
"uri": "/api/v1/users/admin",
"plugins": {
"key-auth": {},
"consumer-restriction": {
"whitelist": [
"Rose",
"Peter
]
}
},
"upstream": {
...
},
}'
The above route restricts the /api/v1/users/admin route to require key auth authentication via the key-auth and consumer-restriction plugins, and only Rose and Peter can access it.
Rate Limiting （limit-count）
We described earlier that you can associate user credentials with consumers by configuring authentication plugins in the Consumer, but the fact is that APISIX Consumer objects can mount not only authentication plugins, but also any plugins like Route and Service.
For example, in the actual application, the rate-limiting policy is often not static but personalized. It is commonly demanded that different service-level callers have different API rate-limiting policies. However, such a demand can not be solved by mounting the rate-limiting plugin on the route. Therefore, we need to mount the rate-limiting plugin on the Consumer and specify a targeted rate-limiting policy for each consumer.
$ curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: your-API-key' -X PUT -i -d '
{
"username": "jack",
"plugins": {
"key-auth": {
"key": "jack"
},
"limit-count": {
"count": 200,
"time_window": 60,
"rejected_code": 503,
"key": "$consumer_name",
}
}'
$ curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: your-API-key' -X PUT -i -d '
{
"username": "rose",
"plugins": {
"key-auth": {
"key": "rose"
},
"limit-count": {
"count": 1000,
"time_window": 60,
"rejected_code": 503,
"key": "$consumer_name",
}
}'
With the above configuration, we specify different rate-limiting policies for jack and rose, with rose having a higher request count quota of 1000 in 60 seconds, while jack only has 200.
Summary
As an indispensable capability of API gateways, authentication and authorization is one of the important factors that users consider when selecting API gateways.
Apache APISIX, the open-source gateway introduced in this paper, covers all major authentication methods and can meet the needs of enterprise users for authentication and authorization. APISIX also has the following advantages:
- Rich out-of-the-box authentication plugins
- Supporting built-in and external authentication methods, which users can freely choose
- Supporting secondary development, easy to interface with custom authentication centers
These benefits can help enterprises more easily land gateway-level authentication and authorization and strengthen API security.
Welcome to learn more about Apache APISIX. You can contact us at https://api7.ai/contact.