auth-module-architecture

Auth module architecture

Applicable scenarios

• Modify RBAC permission checks and resource authorization logic
• Handle relationships among user groups, members, resources, and permissions
• Modify IAM integration, callback, and synchronization logic
• Handle permission migration, tiered administrators, or OAuth2 authentication

Inapplicable scenarios

• Only adding a new permission resource type or action model
• Only granting permissions to users, adding members, or checking permissions
• Only modifying permission call sites in other business modules
• Only handling ordinary login pages or frontend authentication display

Quick guidance

1. This skill focuses on "how the permission platform itself is implemented and collaborates," not a one-off resource onboarding manual.
2. Auth includes both RBAC resource authorization and platform capabilities such as IAM integration, user groups, and OAuth2.
3. First enter the corresponding reference document by problem type:
   • Module structure and core objects:reference/1-auth-foundation.md
   • RBAC, user groups, and authorization chain:reference/2-rbac-group-authorization.md
   • IAM integration, OAuth2, and troubleshooting:reference/3-iam-oauth-debug.md
4. If you are designing a new resource type, action list, or initialization process, switch to permission-model-change-guide。
5. If you are handling a permission call failure in a business module, first determine whether it is an Auth platform issue or a business-side parameter passing issue.

High-signal rules

• The core of Auth is resources, actions, user groups, members, and authorization relationships
• IAM integration and local RBAC data form one complete permission chain and should not be viewed separately in isolation
• User group configuration, permission checks, and resource synchronization often affect the result together
• Permission platform changes should prioritize compatibility, cache refresh, and historical data

Key pitfalls

• Confusing permission model changes with Auth platform implementation
• Only changing validation logic without looking at user groups, resource data, and the synchronization chain
• Ignoring boundary differences when OAuth2, callbacks, and permission checks share context
• When troubleshooting permission issues, only looking at API responses without looking at the ternary relationship among groups, resources, and actions

Further reading

• Module structure and core objects:reference/1-auth-foundation.md
• RBAC, user groups, and authorization chain:reference/2-rbac-group-authorization.md
• IAM integration, OAuth2, and troubleshooting:reference/3-iam-oauth-debug.md
• If you are doing permission model onboarding: also see permission-model-change-guide