Backward-compatible multi-tenant Keycloak integration - preserving previous token endpoint

[AjithNirmal]

Background:
Migrating from WSO2 APIM (single endpoint /oauth2/token) to APISIX + multi-tenant Keycloak where each tenant has separate realms (/realms/{realm}/protocol/openid-connect/token).

Hard Requirement:
Must preserve /oauth2/token endpoint for backward compatibility - cannot change client integrations.
Multi-tenant Setup:

Client A → dev-box realm
Client B → qa-box realm
Client C → prod-box realm

Challenge:
How does APISIX determine which Keycloak realm to route to when all clients hit the same /oauth2/token endpoint?

[dosubot[bot]]

APISIX does not natively support dynamic routing to different Keycloak realms at a shared /oauth2/token endpoint based on request body parameters like client_id. Existing plugins such as proxy-rewrite, openid-connect, and authz-keycloak only support static upstream rewriting or single-realm integration and cannot inspect the request body to determine the correct realm for multi-tenant scenarios example.

To achieve backward-compatible multi-tenant Keycloak integration, you need a custom APISIX plugin. This plugin should:

• Run in the rewrite or access phase (before proxying).
• Use core.request.get_post_args (for form data) or core.request.get_json_request_body_table (for JSON) to extract client_id from the POST body plugin-dev-guide.
• Map client_id to the correct Keycloak realm (using a static table, config, or external service).
• Dynamically set ctx.var.upstream_uri to the appropriate realm-specific token endpoint (e.g., /realms/{realm}/protocol/openid-connect/token) before proxying plugin-dev-guide.
• Optionally, modify headers if Keycloak requires it.
• Handle unknown or missing client_id gracefully (e.g., return a clear error).

This approach preserves the /oauth2/token endpoint for all clients, allowing APISIX to route each request to the correct Keycloak realm based on the client identity in the request body.

For implementation, you can use the plugin development guide and refer to the proxy-rewrite plugin as an example of how to set the upstream URI. The mapping logic and error handling will be specific to your tenant/client setup.

If custom plugin development is not feasible, the only alternatives are to use an external proxy in front of APISIX or to chain gateways, but these add operational complexity.

Let me know if you want a sample Lua plugin skeleton or more details on mapping strategies.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}