This is an automated email from the ASF dual-hosted git repository.
kayx23 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git
The following commit(s) were added to refs/heads/master by this push:
new d6aa62f4a13 refactor(seo): improve high-impression learning center
pages (#2102)
d6aa62f4a13 is described below
commit d6aa62f4a13405448b2efb70c99bc017f9e4a4c8
Author: Yilia Lin <[email protected]>
AuthorDate: Wed Aug 19 15:06:15 2026 +0800
refactor(seo): improve high-impression learning center pages (#2102)
---
.../blog/2022/01/25/apisix-grpc-web-integration.md | 2 +-
next/tests/e2e/docs-version-picker.spec.mjs | 5 +-
.../learning-center/api-gateway-authentication.md | 65 ++++++++++------------
.../api-gateway-for-microservices.md | 2 +
website/learning-center/api-gateway-security.md | 4 +-
website/learning-center/what-is-an-api-gateway.md | 3 +-
website/learning-center/what-is-grpc.md | 50 ++++++-----------
website/learning-center/what-is-mutual-tls.md | 52 +++++++----------
8 files changed, 76 insertions(+), 107 deletions(-)
diff --git a/blog/en/blog/2022/01/25/apisix-grpc-web-integration.md
b/blog/en/blog/2022/01/25/apisix-grpc-web-integration.md
index f3596c243e5..46656f10b0a 100644
--- a/blog/en/blog/2022/01/25/apisix-grpc-web-integration.md
+++ b/blog/en/blog/2022/01/25/apisix-grpc-web-integration.md
@@ -24,7 +24,7 @@ tags: [Ecosystem,Plugins]
## gRPC Web Introduction
-Originally developed by Google, gRPC is a high-performance remote procedure
call framework implemented on HTTP/2. However, because browsers do not directly
expose HTTP/2, Web applications cannot use gRPC directly. gRPC Web is a
standardized protocol that solves this problem.
+Originally developed by Google, [gRPC](/learning-center/what-is-grpc/) is a
high-performance remote procedure call framework implemented on HTTP/2.
However, because browsers do not directly expose HTTP/2, Web applications
cannot use gRPC directly. gRPC Web is a standardized protocol that solves this
problem.
The first gRPC-web implementation was released in 2018 as a JavaScript library
through which Web applications can communicate directly with the gRPC service.
The principle is to create an end-to-end gRPC pipeline compatible with HTTP/1.1
and HTTP/2. The browser then sends a regular HTTP request, and a gRPC-Web proxy
located between the browser and the server translates the request and response.
Similar to gRPC, gRPC Web uses a predefined contract between the Web client and
the back-end g [...]
diff --git a/next/tests/e2e/docs-version-picker.spec.mjs
b/next/tests/e2e/docs-version-picker.spec.mjs
index 95a2e1c1569..441b14ac424 100644
--- a/next/tests/e2e/docs-version-picker.spec.mjs
+++ b/next/tests/e2e/docs-version-picker.spec.mjs
@@ -26,7 +26,10 @@ for (const pagePath of DOC_PAGES) {
expect(hrefs.length, `${pagePath} should render a version
picker`).toBeGreaterThan(0);
for (const href of hrefs) {
- await page.goto(href);
+ // The static CI server can leave non-critical assets loading even after
+ // the docs DOM is ready. The content assertion below is the actual
+ // validity check, so waiting for the full load event only adds
flakiness.
+ await page.goto(href, { waitUntil: 'domcontentloaded' });
// Assert on CONTENT, never on HTTP status. The e2e static server
// (python3 -m http.server) answers an index-less directory with 200
// plus a directory listing, so a status assertion would pass on the
diff --git a/website/learning-center/api-gateway-authentication.md
b/website/learning-center/api-gateway-authentication.md
index d83fa6de8e5..7d09aaecabc 100644
--- a/website/learning-center/api-gateway-authentication.md
+++ b/website/learning-center/api-gateway-authentication.md
@@ -1,6 +1,6 @@
---
title: "API Gateway Authentication: Methods, Best Practices & Implementation"
-description: "Learn how API Gateway authentication works in Apache APISIX with
Key Auth, JWT, OpenID Connect, Keycloak, mTLS, HMAC, and access control."
+description: "Compare API gateway authentication methods including API keys,
JWT, OAuth 2.0, OIDC, mTLS, and HMAC, with implementation guidance for Apache
APISIX."
slug: api-gateway-authentication
date: 2026-04-14
tags: [authentication, security, api-gateway]
@@ -13,10 +13,25 @@ API gateway authentication verifies client identity at a
centralized entry point
In a distributed architecture, every service that exposes an endpoint must
answer a fundamental question: who is making this request? Without a gateway,
each service independently implements its own authentication stack. This leads
to inconsistent enforcement, duplicated code, and a broader attack surface.
-An API gateway centralizes this concern. It intercepts every inbound request,
validates credentials against a configured identity provider or local store,
and either forwards the authenticated request downstream or rejects it
immediately. Broken authentication consistently ranks among the top API
vulnerability categories, making centralized enforcement critical.
+An [API gateway](/learning-center/what-is-an-api-gateway/) centralizes this
concern. It intercepts every inbound request, validates credentials against a
configured identity provider or local store, and either forwards the
authenticated request downstream or rejects it immediately. Broken
authentication consistently ranks among the top API vulnerability categories,
making centralized enforcement critical.
Centralizing authentication at the gateway layer provides three key
advantages. First, it significantly reduces per-service authentication code by
consolidating auth logic into a single component. Second, it creates a single
audit log for every authentication event. Third, it enables credential rotation
and policy changes without redeploying individual services.
+Authentication establishes who or what is making a request. Authorization
determines what that authenticated identity may access. A gateway can enforce
both, but validating a credential does not by itself grant permission to every
upstream resource.
+
+## Comparison Table
+
+| Method | Complexity | Statefulness | Best For | Credential Lifetime |
+|--------|-----------|-------------|----------|---------------------|
+| Basic Auth | Low | Stateless (lookup) | Controlled integrations, legacy
clients | Manual rotation |
+| LDAP | Medium | Directory lookup | Enterprise users and existing directories
| Directory policy |
+| Key Auth | Low | Stateless (lookup) | Controlled server-to-server
integrations | Manual rotation |
+| JWT | Medium | Stateless | Distributed APIs and signed claims | Token
expiration |
+| OAuth 2.0 | High | Authorization server | Delegated access and
machine-to-machine grants | Access token lifetime |
+| OIDC | High | Identity provider and session | User authentication and SSO |
ID and access token lifetime |
+| mTLS | High | Certificate validation | Workload identity, partner APIs,
zero-trust | Certificate validity period |
+| HMAC | Medium | Stateless | Signed requests and webhook verification |
Per-key rotation policy |
+
## Authentication Methods
### Basic and LDAP Authentication
@@ -29,17 +44,17 @@ LDAP authentication validates a username and password
against an LDAP directory
Key authentication is the simplest method. The client includes a static API
key in a header or query parameter. The gateway validates the key against a
stored registry and maps it to a consumer identity.
-Key Auth works well for server-to-server communication where transport
security (TLS) is guaranteed and the client population is small. API keys
remain common for machine-to-machine authentication, though their share is
declining as organizations move toward token-based methods.
+Key Auth works well for controlled server-to-server communication where
transport security is enforced and credentials can be stored and rotated
safely. It is a poor fit for public clients, such as browser or mobile
applications, where a long-lived shared secret cannot be kept confidential.
Apache APISIX supports Key Auth natively through its [key-auth
plugin](/docs/apisix/plugins/key-auth/). Configuration requires only defining a
consumer and attaching the plugin to a route.
### JWT (JSON Web Tokens)
-JWT authentication uses digitally signed tokens that carry claims about the
client. The gateway validates the token signature, checks expiration, and
optionally verifies audience and issuer claims. Because JWTs are
self-contained, the gateway does not need to call an external service on every
request.
+JWT authentication uses digitally signed tokens that carry claims about the
client. A gateway validates the token signature and the claims required by its
policy, such as expiration and not-before times. Because JWTs are
self-contained, validation does not necessarily require an external request for
every API call.
-JWTs dominate modern API authentication. The compact format and stateless
verification make JWTs particularly well-suited for high-throughput gateways
where microsecond-level latency matters.
+The compact format and local signature verification make JWTs useful for
distributed APIs, provided issuers, signing keys, accepted algorithms, and
required claims are configured explicitly.
-APISIX implements JWT validation through its [jwt-auth
plugin](/docs/apisix/plugins/jwt-auth/), supporting both HS256 and RS256
algorithms with configurable claim validation.
+APISIX implements JWT validation through its [jwt-auth
plugin](/docs/apisix/plugins/jwt-auth/). It supports symmetric, RSA, ECDSA,
RSA-PSS, and EdDSA signing algorithms, together with configurable token
locations and time-based claim validation.
### OAuth 2.0
@@ -55,7 +70,7 @@ OIDC is the de facto standard for single sign-on in API
ecosystems. Major identi
### mTLS (Mutual TLS)
-Mutual TLS requires both the client and server to present certificates during
the TLS handshake. The gateway validates the client certificate against a
trusted certificate authority, establishing strong machine identity without
application-layer tokens.
+[Mutual TLS (mTLS)](/learning-center/what-is-mutual-tls/) requires both the
client and server to present certificates during the TLS handshake. The gateway
validates the client certificate against a trusted certificate authority,
establishing strong machine identity without application-layer tokens.
mTLS adoption has surged alongside zero-trust architecture initiatives. In
Kubernetes environments, mTLS between services has become increasingly common.
At the gateway level, mTLS is particularly valuable for B2B integrations and
internal service-to-service communication where certificate management
infrastructure already exists.
@@ -63,38 +78,25 @@ mTLS adoption has surged alongside zero-trust architecture
initiatives. In Kuber
HMAC authentication requires the client to compute a hash-based message
authentication code over the request content using a shared secret. The gateway
independently computes the same HMAC and compares the results. This method
provides request integrity verification in addition to authentication.
-HMAC is common in financial APIs and webhook verification scenarios where
request tampering must be detected. AWS Signature Version 4, used across all
AWS API calls, is an HMAC-based scheme processing billions of requests daily.
-
-## Comparison Table
-
-| Method | Complexity | Statefulness | Best For | Token Expiry |
-|--------|-----------|-------------|----------|-------------|
-| Basic Auth | Low | Stateless (lookup) | Controlled integrations, legacy
clients | Manual rotation |
-| LDAP | Medium | Directory lookup | Enterprise users and existing directories
| Directory policy |
-| Key Auth | Low | Stateless (lookup) | Internal services, simple integrations
| Manual rotation |
-| JWT | Medium | Stateless | High-throughput APIs, mobile clients | Built-in
(exp claim) |
-| OAuth 2.0 | High | Stateful (auth server) | Third-party access, delegated
auth | Access token TTL |
-| OIDC | High | Stateful (identity provider) | SSO, user-facing APIs | ID +
access token TTL |
-| mTLS | High | Stateless (cert validation) | Zero-trust, B2B, service mesh |
Certificate validity period |
-| HMAC | Medium | Stateless | Financial APIs, webhook verification | Per-key
rotation policy |
+HMAC is useful for financial APIs and webhook verification scenarios where the
receiver must verify both the sender and the integrity of the signed request.
## Best Practices
**Layer your authentication.** Use mTLS at the transport layer for service
identity and JWT or OAuth 2.0 at the application layer for user identity.
Defense in depth reduces the impact of any single credential compromise.
-**Enforce short-lived tokens.** Set JWT and OAuth 2.0 access token lifetimes
to 15 minutes or less for user-facing flows. Use refresh tokens to obtain new
access tokens without re-authentication. Short token lifetimes limit the window
of exploitation if a token is leaked.
+**Enforce short-lived tokens.** Choose JWT and OAuth 2.0 access-token
lifetimes that limit exposure while remaining practical for the client flow.
Use an appropriate renewal mechanism rather than issuing long-lived bearer
tokens by default.
**Centralize consumer management.** Define consumers at the gateway level with
consistent identity attributes. Map every API key, JWT subject, and OAuth 2.0
client ID to a named consumer entity. This enables unified rate limiting,
logging, and access control across authentication methods.
**Validate all claims.** Do not trust a JWT solely because its signature is
valid. Verify the issuer (iss), audience (aud), expiration (exp), and
not-before (nbf) claims. Reject tokens with unexpected or missing claims.
-**Log authentication events comprehensively.** Record every authentication
success and failure with client identity, timestamp, source IP, and the route
accessed. These logs are essential for incident response and compliance audits.
NIST SP 800-92 recommends retaining authentication logs for a minimum of 90
days.
+**Log authentication events comprehensively.** Record authentication successes
and failures with the available client identity, timestamp, source address, and
route. Set retention according to the organization's incident-response,
privacy, and compliance requirements.
## How Apache APISIX Handles Authentication
Apache APISIX provides a plugin-based authentication architecture that
supports the methods described above. Each authentication plugin runs in the
gateway's request processing pipeline before the request reaches any upstream
service.
-APISIX's consumer abstraction ties authentication credentials to named
entities. A single consumer can have multiple authentication methods attached,
enabling gradual migration between methods. For example, an organization
migrating from Key Auth to JWT can configure both plugins on the same consumer
during the transition period.
+APISIX's Consumer and Credential resources associate authentication material
with named consumers. When different consumers need to use different
authentication methods on the same Route or Service, the `multi-auth` plugin
provides explicit "any supported method" behavior.
Key plugins include:
@@ -102,9 +104,9 @@ Key plugins include:
- [jwt-auth](/docs/apisix/plugins/jwt-auth/): JWT signature verification with
configurable algorithms and claim validation.
- [openid-connect](/docs/apisix/plugins/openid-connect/): Full OIDC flow
support including authorization code, token introspection, and PKCE.
-APISIX also supports chaining authentication plugins with authorization
plugins such as consumer-restriction and OPA (Open Policy Agent), enabling
fine-grained access control decisions after identity is established.
+APISIX can also combine authentication with authorization plugins such as
consumer-restriction and OPA (Open Policy Agent), enabling access-control
decisions after identity is established. The [API gateway security
guide](/learning-center/api-gateway-security/) explains how authentication fits
with authorization, rate limiting, and other layers of defense.
-Performance benchmarks show APISIX processing authenticated requests with
sub-millisecond overhead for Key Auth and JWT validation, and under 5ms for
OIDC token introspection with a local identity provider. These numbers hold at
sustained loads exceeding 10,000 requests per second on modest hardware.
+To test these controls on a running gateway, first complete the [Apache APISIX
getting started guide](/docs/apisix/getting-started/) and then configure the
authentication plugin that matches the client and trust model.
## FAQ
@@ -114,7 +116,7 @@ JWT and OAuth 2.0 are not mutually exclusive. OAuth 2.0 is
an authorization fram
### Is API key authentication secure enough for production?
-API key authentication is secure for server-to-server communication over TLS
when keys are rotated regularly and scoped to specific consumers. It is not
recommended for client-side applications (browsers, mobile apps) because keys
cannot be kept secret on end-user devices. For any client-facing API, prefer
OAuth 2.0 or OIDC.
+API key authentication can be appropriate for controlled server-to-server
communication over TLS when keys are stored safely, scoped, monitored, and
rotated. It is not appropriate as a secret in public browser or mobile clients
because users can extract the key. For user-facing or delegated access, OAuth
2.0 and OIDC usually provide a better lifecycle and identity model.
### How does mTLS differ from standard TLS at the gateway?
@@ -122,11 +124,4 @@ Standard TLS authenticates only the server to the client.
The client verifies th
### Can I combine multiple authentication methods on a single route?
-Yes. Apache APISIX supports configuring multiple authentication plugins on a
single route. The gateway attempts each configured method in order and accepts
the request if any method succeeds. This is useful during migration periods or
when a route serves clients with different authentication capabilities.
-
-## Related
-
-- [What is an API gateway?](/learning-center/what-is-an-api-gateway/)
-- [API gateway security](/learning-center/api-gateway-security/)
-- [What is mutual TLS (mTLS)?](/learning-center/what-is-mutual-tls/)
-- [Get started with Apache APISIX](/docs/apisix/getting-started/)
+Yes, but the intended behavior must be explicit. Apache APISIX provides the
`multi-auth` plugin for a Route or Service that should accept a request when
any configured authentication method succeeds. Adding independent
authentication plugins without `multi-auth` does not provide the same
alternative-method semantics.
diff --git a/website/learning-center/api-gateway-for-microservices.md
b/website/learning-center/api-gateway-for-microservices.md
index c4000518121..5e2edf43a2e 100644
--- a/website/learning-center/api-gateway-for-microservices.md
+++ b/website/learning-center/api-gateway-for-microservices.md
@@ -87,6 +87,8 @@ API gateways and service meshes both manage network traffic
in a microservices a
| Protocol support | HTTP, gRPC, WebSocket, GraphQL | TCP, HTTP, gRPC |
| Request transformation | Yes | Typically no |
+For services that use [gRPC](/learning-center/what-is-grpc/), the gateway must
preserve HTTP/2 and streaming behavior or explicitly translate the protocol for
clients that cannot use native gRPC.
+
The two technologies are complementary, not competitive. Organizations
deploying both an API gateway and a service mesh generally report improved
overall system reliability compared to using either component alone.
## How Apache APISIX Supports Microservices
diff --git a/website/learning-center/api-gateway-security.md
b/website/learning-center/api-gateway-security.md
index 7fbe4227c25..088042ce9e3 100644
--- a/website/learning-center/api-gateway-security.md
+++ b/website/learning-center/api-gateway-security.md
@@ -45,7 +45,7 @@ A defense-in-depth approach applies multiple security
controls at the gateway la
### Authentication
-The gateway should verify identity before any request reaches a backend
service. Common mechanisms include JWT validation, OAuth 2.0 token
introspection, API key verification, and mutual TLS (mTLS) for
service-to-service communication. Centralizing authentication at the gateway
eliminates the risk of inconsistent enforcement across individual services.
+The gateway should verify identity before any request reaches a backend
service. Common mechanisms include JWT validation, OAuth 2.0 token
introspection, API key verification, and [mutual TLS
(mTLS)](/learning-center/what-is-mutual-tls/) for service-to-service
communication. Centralizing [API gateway
authentication](/learning-center/api-gateway-authentication/) reduces the risk
of inconsistent enforcement across individual services.
### Authorization
@@ -133,6 +133,4 @@ Apply at least three layers: a global rate limit to protect
overall infrastructu
## Related
- [What is an API gateway?](/learning-center/what-is-an-api-gateway/)
-- [API gateway authentication](/learning-center/api-gateway-authentication/)
-- [What is mutual TLS (mTLS)?](/learning-center/what-is-mutual-tls/)
- [API gateway rate limiting](/learning-center/api-gateway-rate-limiting/)
diff --git a/website/learning-center/what-is-an-api-gateway.md
b/website/learning-center/what-is-an-api-gateway.md
index 88522b402d9..d34ca54232a 100644
--- a/website/learning-center/what-is-an-api-gateway.md
+++ b/website/learning-center/what-is-an-api-gateway.md
@@ -59,7 +59,7 @@ Distributing traffic across service instances prevents
hotspots and improves ava
### Authentication and Authorization
-Centralizing identity verification at the gateway eliminates the need for each
service to implement its own auth stack. Common mechanisms include JWT
validation, OAuth 2.0 token introspection, HMAC signatures, LDAP, and [API key
authentication](/docs/apisix/plugins/key-auth/). Some gateways also integrate
with external identity providers through OpenID Connect.
+Centralizing [API gateway
authentication](/learning-center/api-gateway-authentication/) and authorization
eliminates the need for each service to implement its own auth stack. Common
mechanisms include JWT validation, OAuth 2.0 token introspection, HMAC
signatures, LDAP, and [API key authentication](/docs/apisix/plugins/key-auth/).
Some gateways also integrate with external identity providers through OpenID
Connect.
### Rate Limiting
@@ -207,7 +207,6 @@ No. An API gateway is the runtime component that processes
API traffic. An API m
## Related guides
- [API gateway for
microservices](/learning-center/api-gateway-for-microservices/)
-- [API gateway authentication](/learning-center/api-gateway-authentication/)
- [API gateway rate limiting](/learning-center/api-gateway-rate-limiting/)
- [API gateway security](/learning-center/api-gateway-security/)
- [Compare API gateways](/comparisons/)
diff --git a/website/learning-center/what-is-grpc.md
b/website/learning-center/what-is-grpc.md
index 6dd3efda75c..5050f2a9351 100644
--- a/website/learning-center/what-is-grpc.md
+++ b/website/learning-center/what-is-grpc.md
@@ -11,7 +11,7 @@ gRPC is a high-performance, open-source remote procedure call
(RPC) framework or
## Why gRPC Exists
-REST has dominated API design for over fifteen years, and it remains an
excellent choice for public-facing, resource-oriented APIs. However, as
microservices architectures scaled into hundreds or thousands of inter-service
calls per request, the limitations of REST became measurable: text-based JSON
serialization consumes CPU cycles, HTTP/1.1 head-of-line blocking limits
concurrency, and the lack of a formal contract language leads to integration
drift.
+REST remains a strong choice for public-facing, resource-oriented APIs. For
high-frequency service-to-service communication, however, JSON encoding,
repeated request-response exchanges, and separately maintained client models
can add overhead or allow contracts to drift. gRPC addresses these concerns
with generated interfaces, binary messages, multiplexed transport, and built-in
streaming.
Google developed gRPC internally (as Stubby) and open-sourced it in 2015.
Adoption has grown steadily, and gRPC has become a common choice for
latency-sensitive internal APIs in performance-critical systems.
@@ -19,7 +19,7 @@ Google developed gRPC internally (as Stubby) and open-sourced
it in 2015. Adopti
### Protocol Buffers (Protobuf)
-Protocol Buffers are gRPC's interface definition language (IDL) and
serialization format. A `.proto` file defines the service contract, including
methods, request types, and response types:
+Protocol Buffers are gRPC's default interface definition language (IDL) and
message format. A `.proto` file defines the service contract, including
methods, request types, and response types:
```protobuf
syntax = "proto3";
@@ -40,17 +40,17 @@ message OrderResponse {
}
```
-The `protoc` compiler generates client and server code in many languages from
this single definition. Binary serialization produces payloads that are
substantially smaller than equivalent JSON representations. This size reduction
directly translates to lower network bandwidth consumption and faster
serialization/deserialization.
+The `protoc` compiler generates client and server code in many languages from
this definition. For many schemas, binary serialization produces more compact
payloads than an equivalent JSON representation, but the exact size and
processing cost depend on the data model and implementation.
### HTTP/2 Transport
gRPC runs exclusively on HTTP/2, which provides several performance advantages
over HTTP/1.1:
-- **Multiplexing.** Multiple RPC calls share a single TCP connection without
head-of-line blocking. A service making 50 concurrent calls to another service
needs only one connection, not 50.
+- **Multiplexing.** Multiple RPC streams can share one TCP connection without
the request-level blocking behavior of HTTP/1.1. Packet loss can still affect
streams sharing the same TCP connection.
- **Header compression.** HPACK compression significantly reduces header
overhead for repeated headers.
- **Binary framing.** HTTP/2 frames are binary, eliminating the text parsing
overhead of HTTP/1.1.
-These transport-level improvements compound with Protobuf serialization to
deliver measurably lower latency in service-to-service communication.
+Together with Protocol Buffers, these transport features can reduce connection
and serialization overhead for service-to-service communication. The benefit
depends on payload size, concurrency, network conditions, and implementation
details.
### Streaming Modes
@@ -73,13 +73,13 @@ In practice, unary calls represent the majority of gRPC
usage, with server strea
| Streaming | Native (4 modes) | Limited (SSE, WebSocket) |
| Code Generation | Built-in (`protoc`) | Third-party tools |
| Browser Support | Requires proxy (gRPC-Web) | Native |
-| Payload Size | Significantly smaller | Baseline |
-| Latency (typical) | Lower inter-service | Higher inter-service |
+| Payload Size | Compact binary encoding; schema-dependent | Text encoding;
schema-dependent |
+| Latency | Optimized for RPC and streaming; workload-dependent | Workload-
and endpoint-dependent |
| Human Readability | Binary (needs tooling) | JSON is human-readable |
| Caching | Not HTTP-cacheable by default | HTTP caching built-in |
| Tooling Maturity | Growing | Extensive |
-REST remains the dominant choice for public-facing APIs, while gRPC is
increasingly preferred for internal microservices communication at larger
organizations. The two protocols serve complementary roles rather than
competing directly.
+REST is often easier to expose as a public API, while gRPC is often selected
for typed, internal service communication and streaming. The two protocols can
serve complementary roles in the same architecture.
## When to Use gRPC
@@ -98,7 +98,7 @@ REST remains the dominant choice for public-facing APIs,
while gRPC is increasin
- HTTP caching semantics are essential for performance.
- The team's existing tooling and expertise are REST-centric, and migration
cost outweighs the performance gain.
-Many organizations adopting gRPC maintain REST for external APIs and use gRPC
exclusively for internal communication, creating a dual-protocol architecture
that leverages each protocol's strengths.
+A system can expose REST at its public edge and use gRPC internally, allowing
each interface to use the protocol that best fits its clients and operational
requirements.
## gRPC and API Gateways
@@ -114,7 +114,7 @@ Browsers cannot make native gRPC calls because
browser-based JavaScript does not
### HTTP/JSON to gRPC Transcoding
-Many organizations need to expose gRPC services to clients that can only
consume REST/JSON. An API gateway with transcoding capabilities automatically
maps HTTP verbs and JSON payloads to gRPC methods and Protobuf messages based
on annotations in the `.proto` file. This enables a single gRPC backend to
serve both gRPC and REST clients without maintaining two codebases.
+Many organizations need to expose gRPC services to clients that can only
consume REST/JSON. An API gateway with transcoding capabilities can map HTTP
endpoints and JSON payloads to selected gRPC methods and Protobuf messages. The
exact mapping mechanism is gateway-specific: some implementations derive
mappings from `.proto` annotations, while APISIX uses a Proto resource and an
explicit service and method mapping. This enables a single gRPC backend to
serve both gRPC and REST clients wit [...]
In practice, gRPC deployments behind an API gateway typically use a mix of
pure gRPC proxying, gRPC-Web for browser access, and transcoding to serve REST
clients.
@@ -124,17 +124,17 @@ Apache APISIX provides native gRPC support across all
three integration patterns
### Native gRPC Proxying
-APISIX proxies gRPC traffic natively over HTTP/2, supporting unary and
streaming calls. Routes can be configured with gRPC-specific upstream settings,
and the full [plugin ecosystem](/plugins/) applies to gRPC routes:
authentication (JWT, key-auth), rate limiting, circuit breaking, and
observability all work transparently on gRPC traffic.
+APISIX proxies gRPC traffic over HTTP/2, including unary and streaming calls.
Routes use a `grpc` or `grpcs` upstream scheme. Route-level policies that
operate on supported request metadata can then be applied, but plugin
compatibility should be verified for the specific gRPC traffic and payload
behavior.
### gRPC-Web Support
-The [grpc-web plugin](/docs/apisix/plugins/grpc-web/) enables browser clients
to communicate with gRPC backends through APISIX. The plugin handles the
protocol translation between gRPC-Web and native gRPC, allowing frontend teams
to consume gRPC services directly without building a REST translation layer.
This reduces the API surface area and eliminates a class of contract
synchronization bugs.
+The [grpc-web plugin](/docs/apisix/plugins/grpc-web/) enables browser clients
to communicate with gRPC backends through APISIX. The plugin handles the
protocol translation between gRPC-Web and native gRPC, allowing frontend teams
to consume gRPC services directly without building a REST translation layer.
The [APISIX gRPC-Web integration
guide](/blog/2022/01/25/apisix-grpc-web-integration/) provides an end-to-end
configuration example.
### HTTP/JSON to gRPC Transcoding
-The [grpc-transcode plugin](/docs/apisix/plugins/grpc-transcode/) maps REST
endpoints to gRPC methods using the Protobuf descriptor. After uploading the
`.proto` file to APISIX, the plugin automatically exposes each gRPC method as
an HTTP endpoint, translating JSON request bodies to Protobuf messages and
Protobuf responses back to JSON. This is particularly valuable for
organizations migrating from REST to gRPC incrementally, as existing REST
clients continue working while backends are r [...]
+The [grpc-transcode plugin](/docs/apisix/plugins/grpc-transcode/) maps an HTTP
endpoint to a gRPC method using a Protobuf descriptor stored in an APISIX Proto
resource. A Route enables the plugin with the Proto resource ID, service name,
and method name. APISIX then translates JSON requests to Protobuf messages and
Protobuf responses back to JSON for that mapping.
-APISIX's gRPC performance is notable: internal benchmarks show gRPC proxying
at approximately 15,000 RPS per CPU core with 0.3 milliseconds of added
latency, comparable to its HTTP/1.1 proxying performance. The [getting started
guide](/docs/apisix/getting-started/) includes gRPC configuration examples.
+This allows teams to provide an HTTP/JSON interface for selected gRPC methods
without maintaining a separate translation service. The plugin documentation
includes the required Proto resource and Route configuration.
## gRPC Best Practices
@@ -152,30 +152,16 @@ APISIX's gRPC performance is notable: internal benchmarks
show gRPC proxying at
### Can gRPC completely replace REST?
-Not in most architectures. gRPC excels at internal service-to-service
communication where performance, type safety, and streaming matter. REST
remains superior for public APIs due to native browser support, human-readable
payloads, HTTP caching, and broader tooling familiarity. The most common
pattern is gRPC internally with REST or GraphQL at the edge, using an API
gateway for protocol translation.
+Not in most architectures. gRPC is a strong fit for internal
service-to-service communication where type safety and streaming matter. REST
is often easier for public APIs because browsers and general HTTP tooling can
use it directly, and HTTP caching semantics are familiar. A system can use gRPC
internally and expose REST or GraphQL at the edge when clients require it.
### How do I debug gRPC calls if the payloads are binary?
-Tools like `grpcurl` (a curl equivalent for gRPC), Postman (which added gRPC
support in 2023), and BloomRPC provide human-readable interaction with gRPC
services. For production debugging, structured logging at the gateway layer
that decodes Protobuf messages into JSON is the most effective approach.
APISIX's logging plugins can capture gRPC request and response metadata for
observability.
+Tools such as `grpcurl` and clients that support gRPC reflection can inspect
services and make test calls. In production, capture transport status, method
names, latency, and trace context at the gateway and service layers. Inspecting
message bodies requires schema-aware tooling and an explicit decision about
sensitive-data logging.
### What is the performance difference between gRPC and REST in practice?
-In controlled benchmarks, gRPC typically delivers significantly higher
throughput and lower latency than REST/JSON for equivalent workloads. The gains
come from binary serialization (smaller payloads, faster encoding), HTTP/2
multiplexing (fewer connections, no head-of-line blocking), and code-generated
clients (no reflection or manual parsing). The exact improvement depends on
payload size, call frequency, and network conditions. Organizations migrating
from REST to gRPC commonly report [...]
+gRPC can reduce serialization and connection overhead through binary messages,
generated clients, HTTP/2 multiplexing, and streaming. It is not inherently
faster for every workload. Measure representative payloads, concurrency,
network conditions, server implementations, and gateway policies before
choosing a protocol for performance reasons.
### Does gRPC work with WebAssembly or edge computing?
-Yes. Protobuf serialization libraries exist for languages targeting
WebAssembly, and gRPC-Web enables browser-based Wasm applications to call gRPC
backends. For edge computing, gRPC's compact payloads and efficient
serialization are advantageous on bandwidth-constrained links. Several CDN
providers, including Cloudflare and Fastly, now support gRPC proxying at the
edge as of 2025.
-
-### When should teams use gRPC instead of REST?
-
-gRPC is a strong fit for internal service-to-service communication that needs
efficient serialization, strict contracts, streaming, or low-latency calls.
REST is often simpler for public APIs and browser-facing use cases.
-
-### Can Apache APISIX proxy gRPC traffic?
-
-Yes. Apache APISIX can proxy gRPC traffic and support related gateway patterns
such as routing, load balancing, and protocol-aware traffic management.
-
-## Related
-
-- [What is an API gateway?](/learning-center/what-is-an-api-gateway/)
-- [API gateway for
microservices](/learning-center/api-gateway-for-microservices/)
-- [Get started with Apache APISIX](/docs/apisix/getting-started/)
+Yes. Protocol Buffer libraries are available for WebAssembly targets, and
gRPC-Web lets browser-based applications communicate with gRPC services through
a compatible proxy. At edge locations, support must be verified across the
client, proxy, and upstream because native gRPC and gRPC-Web have different
transport requirements.
diff --git a/website/learning-center/what-is-mutual-tls.md
b/website/learning-center/what-is-mutual-tls.md
index 5d786c2756a..ee46e88c2aa 100644
--- a/website/learning-center/what-is-mutual-tls.md
+++ b/website/learning-center/what-is-mutual-tls.md
@@ -11,7 +11,7 @@ Mutual TLS (mTLS) authentication is a security protocol where
both the client an
## Why Mutual TLS Matters
-Standard TLS protects the vast majority of internet traffic today. The
overwhelming majority of web traffic now uses HTTPS. However, standard TLS only
solves half the authentication problem: clients verify that the server holds a
valid certificate, but servers have no cryptographic assurance about the
client's identity. They rely on application-layer mechanisms like API keys,
tokens, or passwords instead.
+In a typical TLS connection, the client verifies that the server holds a valid
certificate, but the server does not authenticate the client with a
certificate. The server instead relies on application-layer mechanisms such as
API keys, tokens, or passwords when it needs to identify the caller.
This gap becomes critical in zero-trust architectures, service-to-service
communication, and regulated environments where network-level identity
verification is required. mTLS closes this gap by making identity verification
bilateral and cryptographic.
@@ -25,10 +25,10 @@ This gap becomes critical in zero-trust architectures,
service-to-service commun
| Certificate management complexity | Low | High |
| Typical use case | Public websites, APIs | Internal services, zero-trust,
IoT |
| Identity assurance level | Server only | Both endpoints |
-| Performance overhead | Baseline | ~5-10% additional handshake time |
+| Handshake work | Server certificate validation | Server and client
certificate validation |
| Common in browsers | Yes | Rare (except enterprise) |
-mTLS has become the predominant service-to-service authentication mechanism in
zero-trust network access (ZTNA) implementations, reflecting growing
recognition that network perimeter-based security is insufficient for
distributed architectures.
+mTLS is commonly used for service-to-service authentication and zero-trust
architectures because it establishes cryptographic identity before application
data is exchanged.
## How the mTLS Handshake Works
@@ -46,13 +46,13 @@ The mTLS handshake extends the standard TLS 1.3 handshake
with additional steps
**Step 6: Secure Channel Established.** Both parties derive session keys from
the shared secret. All subsequent communication is encrypted and authenticated
in both directions.
-The entire handshake adds approximately 1-2 milliseconds of latency compared
to standard TLS, depending on certificate chain depth and revocation checking
methods.
+The additional certificate exchange and validation make an mTLS handshake more
expensive than a standard TLS handshake. The actual cost depends on factors
such as certificate-chain depth, cryptographic algorithms, revocation checks,
network latency, and whether the connection can use session resumption.
## Use Cases for Mutual TLS
### Zero-Trust Architecture
-Zero-trust security models operate on the principle of "never trust, always
verify." Every service must authenticate cryptographically before
communicating, regardless of network location. mTLS provides the
transport-layer foundation for this model. The industry trend is strongly
toward zero-trust for new network access deployments, with mTLS as the
predominant service identity mechanism.
+Zero-trust security models operate on the principle of "never trust, always
verify." Every service must authenticate before communicating, regardless of
network location. mTLS can provide the transport-layer identity needed to apply
this model between clients, gateways, and services.
### Microservices Communication
@@ -60,27 +60,27 @@ In microservices architectures, dozens or hundreds of
services communicate over
### IoT Device Authentication
-IoT devices operate in physically untrusted environments where API keys or
passwords can be extracted from device firmware. mTLS binds device identity to
a hardware-backed certificate, making impersonation significantly harder.
Certificate-based authentication is widely adopted across IoT devices, with
mTLS adoption growing rapidly in industrial and healthcare IoT deployments.
+IoT devices can operate in physically untrusted environments where API keys or
passwords may be extracted from device firmware. When private keys are
protected by secure hardware, mTLS can bind device identity to a certificate
and make credential copying more difficult.
### API Security and Partner Integration
-APIs exposed to partners or regulated industries often require stronger
authentication than API keys provide. mTLS ensures that only clients holding a
certificate issued by the API provider's CA can establish a connection,
providing defense-in-depth before any application-layer authentication occurs.
Financial services APIs governed by Open Banking regulations in the EU, UK, and
Australia mandate mTLS for third-party provider connections.
+APIs exposed to partners or high-risk environments often require stronger
client authentication than an API key alone provides. mTLS ensures that only
clients holding a certificate issued by a trusted CA can establish a
connection, providing defense in depth before [application-layer
authentication](/learning-center/api-gateway-authentication/) occurs. This
transport-layer control is one part of a broader [API gateway
security](/learning-center/api-gateway-security/) strategy.
## Challenges of Implementing mTLS
### Certificate Lifecycle Management
-Every client and server in an mTLS deployment needs a valid certificate. For
an organization running 500 microservices with 3 replicas each, that means
managing 1,500 certificates with their own issuance, renewal, and revocation
cycles. Without automation, this becomes operationally unsustainable. Tools
like cert-manager (for Kubernetes), HashiCorp Vault, and SPIFFE/SPIRE address
this by automating certificate lifecycle operations.
+Every client and server identity in an mTLS deployment needs a valid
certificate with an issuance, renewal, and revocation process. As the number of
workloads grows, manual certificate management becomes impractical. Tools such
as cert-manager, HashiCorp Vault, and SPIFFE/SPIRE can automate parts of this
lifecycle.
-Certificate-related outages are common in organizations managing large
certificate inventories, and remediation can be costly. Automated rotation is
not optional for production mTLS deployments.
+Production deployments should automate renewal and alert before expiration.
Otherwise, an expired certificate can prevent a client or service from
establishing new connections.
### Certificate Rotation
-Short-lived certificates (hours or days) reduce the blast radius of a
compromised key but increase rotation frequency. Long-lived certificates
(months or years) reduce operational churn but increase exposure time if
compromised. The industry trend moves toward short-lived certificates: SPIFFE
recommends certificate lifetimes of 1 hour for workload identities, with
automated rotation handled by the SPIRE agent.
+Short-lived certificates reduce the time a compromised credential remains
usable but require reliable automated rotation. Longer-lived certificates
reduce rotation frequency but increase exposure if a key is compromised. Choose
a lifetime that matches the workload's risk and the recovery guarantees of the
certificate-management system.
### Performance Considerations
-mTLS adds computational overhead from asymmetric cryptography during the
handshake and certificate validation. For services handling thousands of new
connections per second, this overhead can be measurable. Connection pooling and
keep-alive headers amortize the handshake cost across many requests. TLS
session resumption (via session tickets or pre-shared keys) eliminates the full
handshake on reconnection, reducing the per-request cost to near zero for
long-lived connections.
+mTLS adds computational work during the handshake and certificate validation.
Services that create many new connections can therefore see more overhead than
services that reuse connections. Connection pooling, persistent connections,
and TLS session resumption can amortize or reduce repeated handshake work.
### Debugging and Observability
@@ -88,27 +88,27 @@ When mTLS connections fail, diagnosing the cause is harder
than debugging standa
## How to Configure mTLS in Apache APISIX
-Apache APISIX supports mTLS at both the edge (between clients and APISIX) and
internally (between APISIX and upstream services). The configuration uses
APISIX's SSL resource and route-level settings.
+Apache APISIX supports mTLS at both the edge (between clients and APISIX) and
internally (between APISIX and upstream services). Client-to-gateway
authentication is configured on an SSL resource, while gateway-to-upstream
authentication is configured on an upstream.
### Client-to-Gateway mTLS
-To require client certificates for incoming connections, configure an SSL
resource with the CA certificate that should be trusted for client
authentication. APISIX will reject any client that does not present a
certificate signed by the specified CA. See the [mTLS
documentation](/docs/apisix/mtls/) for the full SSL resource schema and
configuration examples.
+To require client certificates for incoming connections, configure an SSL
resource for the relevant SNI names and set `client.ca` to the CA certificate
trusted for client authentication. `client.depth` controls the maximum
verification depth. APISIX rejects a client that does not present a certificate
that can be verified against the configured CA. See the [mTLS
documentation](/docs/apisix/mtls/) for configuration examples.
### Gateway-to-Upstream mTLS
-When upstream services require mTLS, configure the upstream resource with the
client certificate and key that APISIX should present. This ensures APISIX
authenticates itself to backend services, maintaining the zero-trust chain from
edge to origin. The [upstream TLS configuration](/docs/apisix/mtls/) section
covers the required fields.
+When an upstream service requires mTLS, configure its upstream with
`tls.client_cert` and `tls.client_key`, or reference a client-type SSL resource
with `tls.client_cert_id`. APISIX then presents that certificate when
connecting to the upstream. This capability requires APISIX to run on
APISIX-Runtime. The [upstream mTLS
documentation](/docs/apisix/mtls/#mtls-between-apisix-and-upstream) covers the
prerequisite and supported fields.
-### Per-Route mTLS Policies
+### Scope Client Certificate Verification
-APISIX allows different mTLS policies per route, enabling gradual rollout.
Internal admin APIs can require mTLS immediately while public-facing routes
continue using standard TLS with application-layer authentication. This
granularity is configured through the route's `ssl` and `upstream` settings.
+Client certificate verification is attached to the SSL resource selected by
SNI, rather than to a Route `ssl` field. If specific URI patterns on that HTTPS
virtual host must bypass client-certificate checking, configure
`client.skip_mtls_uri_regex` on the SSL resource and keep the exception list as
narrow as possible.
-The [certificate management guide](/docs/apisix/certificate/) covers
integration with cert-manager and external CA providers for automated
certificate rotation within APISIX deployments.
+The [certificate guide](/docs/apisix/certificate/) explains how APISIX selects
certificates by SNI and configures CA bundles. Certificate issuance and
automated rotation remain the responsibility of the PKI or
certificate-management system used by the deployment.
## mTLS Best Practices
1. **Automate certificate lifecycle.** Never rely on manual certificate
issuance or renewal for production mTLS. Use cert-manager, Vault, or SPIRE.
-2. **Use short-lived certificates.** Target lifetimes of 24 hours or less for
workload certificates. Rotate automatically before expiration.
+2. **Limit certificate lifetime.** Use the shortest lifetime that the rotation
and recovery process can support reliably, and rotate automatically before
expiration.
3. **Separate CAs by trust domain.** Do not use the same CA for internal
service certificates and external partner certificates. Maintain distinct trust
hierarchies.
@@ -132,18 +132,4 @@ No. mTLS authenticates the transport-layer identity (which
machine or service is
### How does mTLS perform at scale in Kubernetes?
-In Kubernetes environments with service meshes, mTLS scales well because
certificate issuance and rotation are fully automated by the mesh control
plane. Istio, for example, issues and rotates certificates for every pod
automatically using its built-in CA. The performance impact is primarily on new
connections (the handshake), which is amortized by connection pooling.
Organizations running mTLS across 10,000+ pods report negligible steady-state
performance impact, with the main operation [...]
-
-### When should APIs use mutual TLS?
-
-mTLS is useful when both client and server identity must be verified,
especially for service-to-service communication, zero-trust architectures,
partner APIs, and high-risk internal APIs.
-
-### Can Apache APISIX enforce mTLS?
-
-Yes. Apache APISIX can be configured to validate client certificates at the
gateway layer so upstream services receive traffic only from trusted clients.
-
-## Related
-
-- [What is an API gateway?](/learning-center/what-is-an-api-gateway/)
-- [API gateway security](/learning-center/api-gateway-security/)
-- [API gateway authentication](/learning-center/api-gateway-authentication/)
+In Kubernetes environments, a service mesh or certificate controller can
automate certificate issuance and rotation for workloads. Connection reuse
limits repeated handshake work, but operators still need to monitor certificate
expiration, CA availability, rotation failures, and the resource cost of the
certificate-management control plane.
