Skip to main content
API7.ai Logo

jwe-decrypt

The jwe-decrypt plugin reads a five-part compact token from a request header. It selects a consumer by the token's kid and decrypts the encrypted payload with AES-256-GCM. Before proxying the request, it writes the plaintext to a configured header. You can enable the plugin on APISIX routes or services. Configure a 32-byte decryption secret on the consumer.

The token resembles JWE Compact Serialization, but it is a plugin-specific format. The implementation reads kid from the decoded header; it does not validate the alg or enc fields, and it does not use the protected-header segment as AES-GCM additional authenticated data (AAD). Standard RFC 7516 JWE libraries are therefore not directly interoperable. Generate tokens with the exact format described below, use a fixed trusted token generator, and do not treat header fields as authenticated.

caution

The decrypted plaintext is forwarded in a request header. For sensitive plaintext, do not rely on an APISIX HTTPS upstream alone: APISIX does not verify the upstream server certificate when proxying to standard HTTPS upstreams. Send the request over an authenticated, protected network path, such as through a proxy or service mesh that validates the upstream server's identity. Restrict access to the upstream and avoid logging the configured forwarding header.

Examples​

The examples below demonstrate how you can work with the jwe-decrypt plugin for different scenarios.

Decrypt Data from the Plugin Token​

The following example demonstrates how to decrypt a plugin token. Generate tokens outside APISIX, configure the matching decryption key on a consumer, and create a route with jwe-decrypt to decrypt the authorization header.

Create a consumer with jwe-decrypt and configure the decryption key:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "jack",
    "plugins": {
      "jwe-decrypt": {
        "key": "jack-key",
        "secret": "key-length-should-be-32-chars123"
      }
    }
  }'

Create a route with jwe-decrypt to decrypt the authorization header:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "jwe-decrypt-route",
    "uri": "/anything/jwe",
    "plugins": {
      "jwe-decrypt": {
        "header": "Authorization",
        "forward_header": "Authorization"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "scheme": "https",
      "nodes": {
        "httpbin.org:443": 1
      }
    }
  }'

Generate plugin tokens outside APISIX by encrypting the payload with AES-256-GCM without protected-header AAD and using the consumer secret as the key. Standard RFC 7516 libraries normally authenticate the protected header as AAD and are not directly interoperable with this plugin. Use this exact token structure:

base64url(header)..base64url(iv).base64url(ciphertext).base64url(tag)

where the header is {"alg":"dir","enc":"A256GCM","kid":"<consumer-key>"}. These fields describe the intended algorithm and identify the consumer, but the current plugin does not authenticate or validate them. Use a unique, randomly generated IV for each token; never reuse an IV with the same key.

APISIX decrypts the encrypted payload and authentication tag directly with AES-256-GCM. It does not pass the protected header as AAD. A token generated with standard protected-header AAD is rejected with failed to decrypt JWE token.

Send a request to the route with the encrypted plugin token in the Authorization header. For example, the following token encrypts the payload {"uid":10000,"uname":"test"} for the consumer key jack-key with the secret configured above:

curl "http://127.0.0.1:9080/anything/jwe" -H 'Authorization: eyJraWQiOiJqYWNrLWtleSIsImFsZyI6ImRpciIsImVuYyI6IkEyNTZHQ00ifQ..vi29KBCQKcVmPwTT.VToyPMFbq-ZY05MIpntP1N3AmYeq3zELQ0B6iQ.vuTPG2ODc-DjUTjNCzfA2A'

You should see a response similar to the following, where the Authorization header shows the plaintext of the payload:

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Authorization": "{\"uid\":10000,\"uname\":\"test\"}",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.1.2",
    "X-Amzn-Trace-Id": "Root=1-6510f2c3-1586ec011a22b5094dbe1896",
    "X-Forwarded-Host": "127.0.0.1"
  },
  "json": null,
  "method": "GET",
  "origin": "127.0.0.1, 119.143.79.94",
  "url": "http://127.0.0.1/anything/jwe"
}