Keycloak and Apache APISIX API authentication

The first architecture decision for Keycloak behind APISIX is not which plugin to install but which token flow each caller uses. Three caller types usually appear in one API estate: browser users, backend services and clients that hold opaque or reference tokens. Each maps to a different OAuth 2.0 flow in Keycloak, and each asks APISIX to do a different job. Settling this mapping first keeps the gateway configuration small and makes the trust boundaries visible to reviewers. Browser users should sign in through the authorization code flow. Keycloak issues a code after the user authenticates, and the gateway exchanges that code for tokens on the server side, so the access token never has to be handled by page script. Where the browser application is a public client with no secret it can hold, PKCE must be enabled on the Keycloak client so the code exchange is bound to the original request. In this pattern APISIX redirects unauthenticated users to Keycloak, receives the callback, exchanges the code and manages the session. Decide early whether APISIX holds the session cookie or whether the application does, because that choice changes logout, token refresh and what the upstream service sees.

Services that call APIs on their own behalf should use the client credentials flow. There is no user, so the Keycloak client should be confidential, with a secret or a certificate-based client authentication method held in your secrets store, and its service account should carry only the roles that the target API needs. APISIX's role in this flow is to validate the bearer token it receives, not to request one. Plan for token lifetime and rotation on the calling side, since the caller, not the gateway, obtains and refreshes these tokens. Clients that present opaque or reference tokens need token introspection. In this case APISIX does not decode the token locally. It calls the Keycloak introspection endpoint with its own client credentials and accepts the request only when Keycloak reports the token as active. The trade-off is clear: revocation is seen on the next check, but every protected request adds a network call and a dependency on Keycloak availability, so caching behavior and timeouts must be sized before go-live. Confirm in the openid-connect plugin documentation for your APISIX version which options govern introspection, caching, bearer token handling and which flows are supported, because option names and defaults change between releases. Your architecture team should record that confirmation with the chosen version in the design document.

APISIX is well suited to authenticating callers at the edge: the openid-connect plugin can verify a Keycloak-issued token before a request reaches an upstream, and route-level rules can reject requests that lack the expected identity. Fine-grained decisions are a separate design question. Keycloak's fine-grained authorization services model resources, scopes and policies, and those objects are evaluated by Keycloak or by a component that calls Keycloak, not by the gateway on its own. Treat the gateway as the place where coarse admission is enforced and treat resource-level permissions as a decision you make explicitly, rather than assuming the gateway will cover it.

A common pattern is for APISIX to validate the token and forward it upstream, after which each service validates the same token against Keycloak. The service checks the signature against the realm's published keys, confirms the issuer, audience and expiry, and then reads claims such as roles or groups. Where the service needs a live answer, it can call the Keycloak token endpoint or the introspection endpoint for the token. Decide early whether the upstream trusts the gateway's verification or repeats it. Repeating it costs a little latency and some key management, but it means a misconfigured route cannot quietly expose a service that trusts whatever arrives.

Role or group claims are the usual input for route rules. A realm or client role mapper can place roles into the access token, and the gateway configuration can then require a specific role for a path prefix or HTTP method. This works well for a small number of stable roles, such as a reader and a writer for an API family. It becomes hard to maintain when rules multiply, when roles mix business meaning with technical meaning, or when group membership changes faster than tokens expire. Keep the claim names, their mapping sources and their owners in a written access model before writing route rules, and test that a removed role stops working at the expected point in the token lifecycle.

Centralizing decisions at the gateway gives one place to review and change access for many services, and it keeps service code simpler. The cost is that the gateway becomes a single point of policy, its configuration must be versioned and tested like application code, and application owners may not see why a request was denied. Keeping decisions in each service keeps authorization close to the data it protects and to the people who understand it, but it spreads rules across teams and languages, which makes consistent audit evidence harder. Many organizations settle on coarse checks at the gateway and resource-level checks in services, and document which party owns each rule.

Before promising a model to auditors or application owners, confirm which authorization checks your gateway configuration can express for the APISIX version you deploy. The current APISIX release line and its plugin options change over time, so check the openid-connect plugin documentation and your own test results for claim matching, method-based rules and any consumer or role controls you intend to rely on. Run a negative test for each rule, including an expired token, a token missing the required role and a token for a different client. Record the results as the evidence for the model, and state clearly which decisions remain in the services.

The gateway is only protecting your APIs if it refuses the requests it should refuse, accepts the ones it should accept, and keeps its own management plane out of reach. Treat the test plan as an acceptance gate for the Keycloak and Apache APISIX design, not as a one-time smoke check. Each test below should have a named expected result, a recorded input, and an owner who can explain a failure. Negative token tests Start with requests the gateway must reject. Send a request with no token, an expired access token, a token whose audience does not match the API's expected audience, and a token issued by a different realm or issuer URL. Confirm the status code returned to the client and confirm that the upstream service never received the request. For the audience and issuer cases, check the configuration in the openid-connect plugin and in the Keycloak client scopes, because a mismatch in either place can produce a rejection that looks correct but is caused by a broken setting. Also test a token signed by a key that Keycloak no longer publishes.

Positive tests should cover each flow you intend to support: authorization code for user-facing applications, client credentials for service-to-service calls, and token introspection where you have chosen it. Use a real client registration for each flow, not a shared test account. Confirm the claims the upstream receives match what the route is meant to expose, and that scopes or roles that were not granted are absent. Record the token type, client ID, and expiry used in each test so the evidence can be traced back to a Keycloak client. Management plane and forwarded headers From each client network segment, attempt to reach the APISIX Admin API and the metrics or management endpoints of Keycloak. In traditional mode the Admin API listens on port 9180, so confirm which networks can reach that port and that the answer is a refusal, not just a missing route. Confirm the same for Keycloak's admin console and Administration REST API, which the production guide says should sit on a different hostname or context path from public frontend URLs. At the upstream, verify that forwarded headers such as the client address and protocol are set by the gateway and cannot be spoofed by a client request. Failover, restart and key rotation Restart the gateway nodes and, in the chosen deployment mode, the etcd members, while sending steady test traffic. Record which requests fail, for how long, and whether authorization decisions remain consistent once the component returns. Then rehearse a Keycloak signing key rotation in a non-production realm: publish the new key, confirm the gateway picks it up, retire the old key, and confirm that tokens signed with the retired key are rejected. Confirm with your Keycloak version and the APISIX openid-connect plugin documentation how key discovery and caching behave before you set a rotation window. Evidence and separate security testing Keep the results as dated evidence: the test plan, inputs, outputs, configuration versions, and sign-off. Change management teams usually need this record for each release of the gateway or Keycloak, and security reviewers use the same record as a baseline. The tests above confirm expected behavior. They do not establish that an attacker cannot bypass the gateway, so a separate security test of the gateway and its routes is a different piece of work. DeployOpen can run that security testing as a separate engagement with its own written scope.