You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by yi...@apache.org on 2026/08/31 02:13:25 UTC
(apisix) branch master updated: docs: clarify JWE and RAG plugin guidance (#13873)
This is an automated email from the ASF dual-hosted git repository.
Yilialinn pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new f94b3c765 docs: clarify JWE and RAG plugin guidance (#13873)
f94b3c765 is described below
commit f94b3c76567574ffd11981cad2a8b025a0af3f4f
Author: Yilia Lin <Yi...@apache.org>
AuthorDate: Mon Aug 31 10:13:19 2026 +0800
docs: clarify JWE and RAG plugin guidance (#13873)
---
docs/en/latest/plugins/ai-rag.md | 26 +++++++++---------
docs/en/latest/plugins/jwe-decrypt.md | 50 +++++++++++++++++++++++------------
2 files changed, 46 insertions(+), 30 deletions(-)
diff --git a/docs/en/latest/plugins/ai-rag.md b/docs/en/latest/plugins/ai-rag.md
index fe1130ddf..113ee2bb2 100644
--- a/docs/en/latest/plugins/ai-rag.md
+++ b/docs/en/latest/plugins/ai-rag.md
@@ -7,7 +7,7 @@ keywords:
- ai-rag
- AI
- LLM
-description: The ai-rag Plugin enhances LLM outputs with Retrieval-Augmented Generation (RAG), efficiently retrieving relevant documents to improve accuracy and contextual relevance in responses.
+description: The ai-rag Plugin retrieves context with Azure OpenAI embeddings and Azure AI Search before an LLM request is proxied.
---
<!--
@@ -38,9 +38,9 @@ import TabItem from '@theme/TabItem';
## Description
-The `ai-rag` Plugin provides Retrieval-Augmented Generation (RAG) capabilities with LLMs. It facilitates the efficient retrieval of relevant documents or information from external data sources, which are used to enhance the LLM responses, thereby improving the accuracy and contextual relevance of the generated outputs.
+The `ai-rag` Plugin implements the retrieval step of a Retrieval-Augmented Generation (RAG) request flow. It generates an embedding from the request, performs a vector search, adds the retrieved content to the protocol-specific LLM request input, and removes the `ai_rag` request object before the request is proxied.
-The Plugin supports using [Azure OpenAI](https://azure.microsoft.com/en-us/products/ai-services/openai-service) and [Azure AI Search](https://azure.microsoft.com/en-us/products/ai-services/ai-search) services for generating embeddings and performing vector search. PRs for introducing support for other service providers are welcomed.
+The current implementation supports [Azure OpenAI](https://azure.microsoft.com/en-us/products/ai-services/openai-service) for embeddings and [Azure AI Search](https://azure.microsoft.com/en-us/products/ai-services/ai-search) for vector search. Use the [`ai-proxy`](./ai-proxy.md) Plugin in the same request flow to proxy the augmented request to the LLM provider. The Plugin does not create or populate a search index; prepare the index and its content before sending requests through APISIX.
## Plugin Attributes
@@ -115,14 +115,14 @@ Save the API keys and endpoints to environment variables:
```shell
# replace with your values
-AZ_OPENAI_DOMAIN=https://ai-plugin-developer.openai.azure.com
-AZ_OPENAI_API_KEY=9m7VYroxITMDEqKKEnpOknn1rV7QNQT7DrIBApcwMLYJQQJ99ALACYeBjFXJ3w3AAABACOGXGcd
+AZ_OPENAI_DOMAIN=https://your-openai-resource.openai.azure.com
+AZ_OPENAI_API_KEY=your-azure-openai-api-key
AZ_CHAT_ENDPOINT=${AZ_OPENAI_DOMAIN}/openai/deployments/gpt-4o/chat/completions?api-version=2024-02-15-preview
AZ_EMBEDDING_MODEL=text-embedding-3-large
AZ_EMBEDDINGS_ENDPOINT=${AZ_OPENAI_DOMAIN}/openai/deployments/${AZ_EMBEDDING_MODEL}/embeddings?api-version=2023-05-15
-AZ_AI_SEARCH_SVC_DOMAIN=https://ai-plugin-developer.search.windows.net
-AZ_AI_SEARCH_KEY=IFZBp3fKVdq7loEVe9LdwMvVdZrad9A4lPH90AzSeC06SlR
+AZ_AI_SEARCH_SVC_DOMAIN=https://your-search-service.search.windows.net
+AZ_AI_SEARCH_KEY=your-azure-ai-search-api-key
AZ_AI_SEARCH_INDEX=vectest
AZ_AI_SEARCH_ENDPOINT=${AZ_AI_SEARCH_SVC_DOMAIN}/indexes/${AZ_AI_SEARCH_INDEX}/docs/search?api-version=2024-07-01
```
@@ -243,17 +243,17 @@ spec:
embeddings_provider:
azure_openai:
endpoint: "https://your-openai-resource.openai.azure.com/openai/deployments/text-embedding-3-large/embeddings?api-version=2023-05-15"
- api_key: "Bearer your-api-key"
+ api_key: "your-azure-openai-api-key"
vector_search_provider:
azure_ai_search:
endpoint: "https://your-search-service.search.windows.net/indexes/vectest/docs/search?api-version=2024-07-01"
- api_key: "Bearer your-api-key"
+ api_key: "your-azure-ai-search-api-key"
- name: ai-proxy
config:
provider: openai
auth:
header:
- api-key: "Bearer your-api-key"
+ api-key: "your-azure-openai-api-key"
model: gpt-4o
override:
endpoint: "https://your-openai-resource.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-02-15-preview"
@@ -307,18 +307,18 @@ spec:
embeddings_provider:
azure_openai:
endpoint: "https://your-openai-resource.openai.azure.com/openai/deployments/text-embedding-3-large/embeddings?api-version=2023-05-15"
- api_key: "Bearer your-api-key"
+ api_key: "your-azure-openai-api-key"
vector_search_provider:
azure_ai_search:
endpoint: "https://your-search-service.search.windows.net/indexes/vectest/docs/search?api-version=2024-07-01"
- api_key: "Bearer your-api-key"
+ api_key: "your-azure-ai-search-api-key"
- name: ai-proxy
enable: true
config:
provider: openai
auth:
header:
- api-key: "Bearer your-api-key"
+ api-key: "your-azure-openai-api-key"
model: gpt-4o
override:
endpoint: "https://your-openai-resource.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-02-15-preview"
diff --git a/docs/en/latest/plugins/jwe-decrypt.md b/docs/en/latest/plugins/jwe-decrypt.md
index 02dafc736..78a8947b3 100644
--- a/docs/en/latest/plugins/jwe-decrypt.md
+++ b/docs/en/latest/plugins/jwe-decrypt.md
@@ -6,7 +6,7 @@ keywords:
- Plugin
- JWE Decrypt
- jwe-decrypt
-description: The jwe-decrypt Plugin decrypts JWE authorization headers in requests directed to Routes or Services, enhancing API security.
+description: The jwe-decrypt Plugin decrypts its supported five-part compact token format and forwards the plaintext in a configured request header.
---
<!--
@@ -37,19 +37,31 @@ import TabItem from '@theme/TabItem';
## Description
-The `jwe-decrypt` Plugin decrypts [JWE](https://datatracker.ietf.org/doc/html/rfc7516) authorization headers in requests sent to APISIX [Routes](../terminology/route.md) or [Services](../terminology/service.md).
+The `jwe-decrypt` Plugin reads a five-part compact token from a request header, selects a [Consumer](../terminology/consumer.md) by the token's `kid`, decrypts the ciphertext with AES-256-GCM, and writes the plaintext to a configured header before proxying the request. You can enable the Plugin on APISIX [Routes](../terminology/route.md) or [Services](../terminology/service.md).
-The decryption key should be configured in [Consumer](../terminology/consumer.md).
+The token resembles [JWE Compact Serialization](https://datatracker.ietf.org/doc/html/rfc7516#section-3.1), but the current Plugin uses a Plugin-specific format. Configure a 32-byte decryption secret on the Consumer.
+
+:::warning
+
+The current implementation reads `kid` from the decoded header but does not validate the `alg` or `enc` fields and 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 HTTPS Upstream alone: APISIX does not verify server certificates for standard HTTP 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.
+
+:::
## Attributes
### Consumer
-| Name | Type | Required | Default | Valid values | Description |
-| ----------------- | ------- | -------- | ------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| key | string | True | | | A unique key that identifies the Credential for a Consumer. |
-| secret | string | True | | 32 characters | The shared symmetric encryption/decryption key. You can also store it in an environment variable and reference it using the `env://` prefix, or in a secret manager such as HashiCorp Vault's KV secrets engine, and reference it using the `secret://` prefix. |
-| is_base64_encoded | boolean | False | false | | Set to true if the secret is base64 encoded. Note that after enabling `is_base64_encoded`, the `secret` length may exceed 32 characters. You only need to make sure the decoded length is still 32 characters. |
+| Name | Type | Required | Default | Valid values | Description |
+| ----------------- | ------- | -------- | ------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| key | string | True | | | A unique key that identifies the Credential for a Consumer. |
+| secret | string | True | | 32 bytes | A shared symmetric key. Use a [secret reference](../terminology/secret.md), such as `$env://...` or `$secret://...`. |
+| is_base64_encoded | boolean | False | false | | Set to true if the secret is base64url encoded. The decoded secret must still be 32 bytes. |
### Route or Service
@@ -57,7 +69,7 @@ The decryption key should be configured in [Consumer](../terminology/consumer.md
| -------------- | ------- | -------- | ------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| header | string | True | Authorization | | The header to get the token from. |
| forward_header | string | True | Authorization | | Name of the header that passes the plaintext to the Upstream. |
-| strict | boolean | False | true | | If true, throw a 403 error if JWE token is missing from the request. If false, do not throw an error when JWE token is not found. |
+| strict | boolean | False | true | | If true, return a 403 error when the encrypted plugin token is missing. If false, continue when the token is not found. |
## Examples
@@ -75,7 +87,7 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/
### Create a Consumer with the Decryption Key
-The following example demonstrates how to create a Consumer with the decryption key and generate a JWE token for it.
+The following example demonstrates how to create a Consumer with the decryption key and generate an encrypted plugin token for it.
Create a Consumer with `jwe-decrypt` and configure the decryption key:
@@ -160,13 +172,13 @@ kubectl apply -f jwe-consumer-ic.yaml
</TabItem>
</Tabs>
-To generate a JWE token for the Consumer, encrypt the payload offline with any AES-256-GCM library, using the Consumer secret as the key. The token structure is:
+To generate a token for the Consumer, encrypt the payload offline with AES-256-GCM without protected-header AAD, 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 the following exact token structure:
```text
base64url(header).<empty>.base64url(iv).base64url(ciphertext).base64url(tag)
```
-where the header is `{"alg":"dir","enc":"A256GCM","kid":"<consumer-key>"}`. The IV must be unique and randomly generated for every token; never reuse an IV with the same key.
+where the header is `{"alg":"dir","enc":"A256GCM","kid":"<consumer-key>"}`. The fields describe the intended algorithm and identify the Consumer, but the current Plugin does not authenticate or validate them. The IV must be unique and randomly generated for every token; never reuse an IV with the same key.
For example, the following token encrypts the payload `{"uid":10000,"uname":"test"}` for the Consumer key `jack-key` with the secret configured above:
@@ -174,9 +186,9 @@ For example, the following token encrypts the payload `{"uid":10000,"uname":"tes
eyJraWQiOiJqYWNrLWtleSIsImFsZyI6ImRpciIsImVuYyI6IkEyNTZHQ00ifQ..vi29KBCQKcVmPwTT.VToyPMFbq-ZY05MIpntP1N3AmYeq3zELQ0B6iQ.vuTPG2ODc-DjUTjNCzfA2A
```
-### Decrypt Data with JWE
+### Decrypt Data from the Plugin Token
-The following example demonstrates how to decrypt the JWE token generated above.
+The following example demonstrates how to decrypt the plugin token generated above.
Create a Route with `jwe-decrypt` to decrypt the authorization header:
@@ -197,8 +209,9 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
},
"upstream": {
"type": "roundrobin",
+ "scheme": "https",
"nodes": {
- "httpbin.org:80": 1
+ "httpbin.org:443": 1
}
}
}'
@@ -221,9 +234,10 @@ services:
forward_header: Authorization
upstream:
type: roundrobin
+ scheme: https
nodes:
- host: httpbin.org
- port: 80
+ port: 443
weight: 1
```
@@ -240,6 +254,8 @@ adc sync -f adc.yaml
<Tabs groupId="k8s-api">
<TabItem value="gateway-api" label="Gateway API">
+The following Gateway API configuration uses public HTTPBin only with the non-sensitive demonstration payload shown on this page. Before forwarding real decrypted data, replace it with a controlled upstream and use an authenticated, protected network path. An APISIX HTTPS Upstream does not validate the upstream server certificate by itself; use a proxy or service mesh that validates the upstream server's identity.
+
```yaml title="jwe-decrypt-ic.yaml"
apiVersion: v1
kind: Service
@@ -304,7 +320,7 @@ kubectl apply -f jwe-decrypt-ic.yaml
</TabItem>
</Tabs>
-Send a request to the Route with the JWE encrypted data in the `Authorization` header:
+Send a request to the Route with the encrypted plugin token in the `Authorization` header:
```shell
curl "http://127.0.0.1:9080/anything/jwe" -H 'Authorization: eyJraWQiOiJqYWNrLWtleSIsImFsZyI6ImRpciIsImVuYyI6IkEyNTZHQ00ifQ..vi29KBCQKcVmPwTT.VToyPMFbq-ZY05MIpntP1N3AmYeq3zELQ0B6iQ.vuTPG2ODc-DjUTjNCzfA2A'