Hashicorp Vault & Apache APISIX: Strengthen Your API Security

Chao Zhang

Chao Zhang

November 15, 2022


Nowadays, API (Application Programming Interfaces) has become the most common way to connect different software services. E.g., you fetch today's weather through some weather APIs or retweet a funny message through Twitter's API. API interconnection makes the Internet rich and colorful while also showing the darkness - API threats.

Data show that APIs now represent 90% of the attack surface of web applications, which means APIs now is one of the primary attack vectors. Then, how can we mitigate the API risks?

People may choose the API Gateway pattern in modern software architectures to defend against API attacks. An API Gateway is the software service's entry point, providing functionalities like load balancing, service discovery, and API authentication. Apache APISIX is one of the best API Gateways, which helps users to strengthen their API security through features like authentication, authorization, ACL (Access Control List), and IP deny/allow list. For instance, JWT authentication is a popular way to protect APIs. It asks API consumers to prove who they are via a JSON Web Token. In such a case, API requests without the credential or with the wrong one will be rejected by Apache APISIX.

Apache APISIX is also in charge of the signing of JSON Web Token (which needs a secret to sign in). From Apache APISIX's point of view, storing users' secrets becomes a critical question since the authentication will be out of work if the secrets are leaked. By default, Apache APISIX saves secrets in etcd, the configuration center for Apache APISIX configurations like route and upstream.

Unfortunately, etcd is not designed to protect sensitive data. Once an immoral man can access the etcd cluster, all data inside it will be exposed. It's not a big deal for an APISIX route object, but it would be fatal for secrets or the private keys of X509 certificates. For the sake of protecting sensitive data better, Apache APISIX integrated the Hashicorp Vault since version 2.12.0. So what is Hashicorp Vault?

What is Hashicorp Vault?

Hashicorp Vault is a storage infrastructure for safely saving users' secrets (e.g., database credentials, passwords, API keys). It supports integrating many external systems like Amazon Key Management Service and Google Cloud Key Management. Technically, Hashicorp Vault is a distributed system with the Raft consensus protocol. Your data will be saved with multiple backups, and you don't have to worry about the data's single point of failure.


But why is Hashicorp Vault special? Once you start the Hashicorp Vault server, it's in a sealed state. You cannot access any data unless you unseal this server. For unsealing a Hashicorp Vault server, you need to use key shares (generated when you init the Hashicorp Vault server with the Shamir Secret Sharing algorithm) to execute the unseal operations repeatedly. Times depend on the number of key shares ((X/2)+1 if the number of key shares is X). What's more, you can re-seal the Hashicorp Vault server in runtime if you see any suspicious signs that it's suffering from some attack.

How Does Apache APISIX Use Hashicorp Vault?

Currently, Apache APISIX integrates Hashicorp Vault in its jwt-auth plugin. The jwt-auth plugin is used to do the JWT authentication.


The basic interaction logics between Hashicorp Vault and Apache APISIX are:

  1. An API request comes in
  2. The JWT Auth plugin runs
  3. Apache APISIX tries to fetch the secret from Hashicorp Vault
  4. Hashicorp Vault returns the secret, and Apache APISIX caches it
  5. Apache APISIX uses the secret to validate the JSON Web Token
  6. Authentication passed, and the API request is forwarded to the backend service
  7. Send the API response back

You can configure the jwt-auth plugin in an Apache APISIX consumer object with the vault option to tell Apache APISIX to store/fetch the secret to/from Hashicorp Vault. Apache APISIX consumer is an abstraction of API consumer. API credentials can be configured at the consumer level.

curl -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  "username": "jack",
  "plugins": {
    "jwt-auth": {
      "key": "your-api-key",
      "vault": {}

The Hashicorp Vault configurations can be set in Apache APISIX config.yaml.

  host: ''
  timeout: 10
  token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
  prefix: 'kv/apisix'

Care must be taken here that the token should have read permission for path kv/apisix/consumer, which is the place Apache APISIX Admin API saves secrets.

path "kv/apisix/consumer/*" {
    capabilities = ["read"]

When API requests from that consumer come in, Apache APISIX will try to fetch the secret from the configured Hashicorp Vault server (and cache the result in memory) and use this secret to validate the JSON Web Token.

Future of the Integrations between Apache APISIX and Hashicorp Vault

There are several kinds of sensitive data in Apache APISIX, but only the JSON Web Token secret can be saved to Hashicorp Vault right now. However, in the future, all API credentials, like an API key, and a user password, can be saved to Hashicorp Vault. Besides, the certificate's private key and Admin API keys can also be saved there. All of these data will be separated from configurations. In this way, your API security is strengthened not only because you use API authentication, but also because the API credentials are protected appropriately.

Hashicorp VaultAPI Security