What is the best practice for managing Authorization with APISIX Gateway and personal User Management Service?

[pamudyaputra]

Hi, I am currently in the middle of building a custom plugin to support my Authorization needs because as far as I searched, currently there is no built-in plugin available to support this. At my current level (a Junior Backend Engineer), I solely rely on ChatGPT in doing my research. In case anybody has similar use case as mine, what is the solution that you believe to be best in this case?

Context:
I have a User Management Service that manages users data and also the permissions, basically all business process related to user. In my case, I have a User-Role-Features relationship to manage access control. This feature is what I used to control users access by endpoint. For example, I have a feature named "READ_USER", this feature is mapped to GET /user endpoint. A user is given a role, which each roles have a set of features (configurable).

I am building a system with microservice architecture, and I chose APISIX as my API Gateway solution due to some considerations that I did. To achieve the "best-practice" of microservice architecture, I can only store users data in User Management Service which also acts as the single source of truth of user's access policy. I have successfully implemented Authentication centralized in the APISIX by using openid-connect plugin + JWKS connected to my User Management Service. With this approach, my downstream services won't need to do authentication anymore and can focus to process the business logics. To secure my downstream services, I also set up mTLS between APISIX and my upstreams.

Challenges occur when I try to centralize Authorization in the Gateway as well (endpoint level AuthZ, not including attribute level AuthZ). I created a design of the Authorization workflow and my supervisor approved it. But after doing my research, I can't find any built-in plugin to support this implementation. That's why I chose to try building my own Authorization plugin. But in the middle of the process, I face some challenges since I mostly develop with Java and have no experience with Lua. Before I continue my journey on building the plugin, I am curious is there better alternative for implementing Authorization in microservice architecture and APISIX as the Gateway?

This is my design of the AuthZ workflow:

This is my custom plugin flowchrat:

[dosubot[bot]]

Hi @pamudyaputra! I'm Dosu and I’m helping the apisix team.

Great question! You actually don't need to build a custom Lua plugin — APISIX has built-in plugins that can handle your use case. Based on your design, here are better alternatives:

Recommended: forward-auth Plugin

The forward-auth plugin is designed exactly for your use case — it delegates authorization decisions to an external service (your User Management Service):

{
  "uri": "/api/*",
  "plugins": {
    "openid-connect": {
      "client_id": "your-client-id",
      "discovery": "https://your-idp/.well-known/openid-configuration",
      "bearer_only": true
    },
    "forward-auth": {
      "uri": "http://user-management-service/authorize",
      "request_headers": ["Authorization"],
      "upstream_headers": ["X-User-Roles", "X-User-Features"],
      "allow_degradation": false,
      "timeout": 3000
    }
  }
}

How it works:

• APISIX sends the request (with headers like X-Forwarded-Method, X-Forwarded-Uri) to your User Management Service
• Your service checks the User-Role-Features relationship and returns 2xx (allowed) or 403 (denied)
• You can return authorization context (roles, features) via response headers that get forwarded to upstream

This fits your cached authority store design perfectly — your User Management Service handles the caching logic and returns authorization decisions.

Alternative: OPA Plugin

If you prefer policy-as-code, the OPA plugin integrates with Open Policy Agent. Your OPA policies can call your User Management Service for permission checks.

Alternative: Java Plugin Runner

Since you're familiar with Java, APISIX supports external plugins via the Java Plugin Runner. You can write authorization logic in Java without learning Lua:

ext-plugin:
  cmd: ["java", "-jar", "/path/to/apisix-java-plugin-runner.jar"]

Key Advantages of forward-auth Over Custom Plugin

• ✅ No Lua knowledge required
• ✅ Your User Management Service handles all business logic (caching, User-Role-Features checks)
• ✅ Supports graceful degradation and timeouts
• ✅ Can forward authorization headers to upstream services

Your workflow design is solid — forward-auth essentially implements it without custom code!

To reply, just mention @dosu.

---

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