Skip to content

Commit 1351dfa

Browse files
rodmgwgurodmgwgu
committed
docs: ADR for Enforcement mechanisms - current user permission checks from MFEs and other remote clients
1 parent 834d68b commit 1351dfa

1 file changed

Lines changed: 194 additions & 0 deletions

File tree

‎docs/decisions/0007-enforcement-mechanisms-mfe.rst‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
0007: Enforcement mechanisms - current user permission checks from MFEs and other remote clients
2+
################################################################################################
3+
4+
Status
5+
********
6+
7+
**Draft**
8+
9+
Context
10+
*********
11+
12+
Authorization (AuthZ) decisions need to be enforced not only on the
13+
backend services, but also on the frontend applications, including
14+
Micro-Frontends (MFEs) and mobile apps. This ensures that users only see
15+
and can interact with the UI elements they are permitted to access based
16+
on their roles and permissions.
17+
18+
To achieve this, we need to establish effective communication mechanisms
19+
between the backend services and the frontend clients. This involves
20+
determining how AuthZ data is transmitted, how often it is updated, and
21+
how the frontend applications can use this data to enforce access
22+
control for the currently authenticated user.
23+
24+
We want an approach that:
25+
26+
- Minimizes the amount of requests and data transferred between the
27+
backend and frontend.
28+
- Is granular enough to match the functionality available on the
29+
backend.
30+
- Is easy to implement and maintain across different frontend
31+
applications.
32+
33+
**Please note:** The scope of this ADR is limited to enforcing permissions
34+
for the currently authenticated user.
35+
36+
Decision
37+
**********
38+
39+
I. REST API for authorization queries
40+
=====================================
41+
42+
We will implement a dedicated REST API endpoint that frontend
43+
applications can use to query for specific permissions for the currently
44+
authenticated user. Queries would be at the Subject-Action-Object-Context
45+
level, being the Subject always the current authenticated user. This allows
46+
the frontend to check if a user has permission to perform a specific action
47+
on a specific object within a given context.
48+
49+
To optimize performance and reduce latency, the API will support batch
50+
queries, allowing multiple permission checks in a single request. It
51+
will also have caching mechanisms in place.
52+
53+
API Definition
54+
--------------
55+
56+
POST /api/authz/v1/permissions/validate/me
57+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
58+
59+
Validate if the current user has specific permissions.
60+
61+
Request Body:
62+
"""""""""""""
63+
64+
Format:
65+
66+
.. code:: ts
67+
68+
Array<{
69+
action: string
70+
scope?: string
71+
}>
72+
73+
Example:
74+
75+
.. code:: json
76+
77+
[
78+
{
79+
"action": "act:read",
80+
"scope": "lib:DemoX:CSPROB"
81+
},
82+
{
83+
"action": "act:edit",
84+
"scope": "lib:DemoX:CSPROB"
85+
}
86+
]
87+
88+
**Please Note:**
89+
90+
- The user (subject) would be inferred from the authenticated user
91+
making the request.
92+
- The order of the permissions in the response array will match the order
93+
of the request. This must be guaranteed by the implementation.
94+
The frontend will rely on this order to match responses to requests.
95+
96+
Response Body:
97+
""""""""""""""
98+
99+
Format:
100+
101+
.. code:: ts
102+
103+
Array<{
104+
action: string
105+
scope?: string
106+
allowed: boolean
107+
}>
108+
109+
Example:
110+
111+
.. code:: json
112+
113+
[
114+
{
115+
"action": "act:read",
116+
"scope": "lib:DemoX:CSPROB",
117+
"allowed": true
118+
},
119+
{
120+
"action": "act:edit",
121+
"scope": "lib:DemoX:CSPROB",
122+
"allowed": false
123+
}
124+
]
125+
126+
Possible response codes:
127+
""""""""""""""""""""""""
128+
129+
- 200: Ok, includes the Response Body defined above.
130+
- 400: Bad Request, happens when the request body doesn't match the
131+
required format.
132+
- 401: Unauthorized, happens when the user is not authenticated/logged in.
133+
134+
**Please note:** There is no “404 not found” case here, if the action or
135+
scope doesn't exist, the “allowed” value in the response will be whatever
136+
Casbin evaluates in this case.
137+
138+
II. Frontend integration
139+
========================
140+
141+
Frontend applications will integrate with the REST API to enforce
142+
authorization decisions. This will involve:
143+
144+
#. Querying the API for permissions when rendering UI components.
145+
#. Using the API response to conditionally render or style UI elements
146+
based on the user's permissions.
147+
#. Implementing a caching strategy on the frontend to minimize API calls
148+
and improve performance.
149+
150+
The specifics on when and how to query the API will depend on the
151+
application's architecture and user interaction patterns.
152+
153+
Standard frontend library functions will be developed to facilitate
154+
permission queries, incorporating reasonable defaults for caching,
155+
request deduplication, and auto-refresh mechanisms. These functions will
156+
most likely be implemented as part of frontend-base.
157+
158+
Consequences
159+
**************
160+
161+
- The REST API approach provides a flexible and scalable way to enforce
162+
AuthZ decisions across different frontend applications.
163+
164+
- It allows for real-time updates to permissions, as the frontend can
165+
query the API as needed.
166+
167+
- The batch query and caching mechanisms help mitigate performance
168+
concerns, ensuring that the user experience remains smooth.
169+
170+
- Frontend developers will need to implement the necessary logic to
171+
interact with the REST API and enforce AuthZ decisions.
172+
173+
- The approach is adaptable to various frontend architectures,
174+
including MFEs and mobile apps, making it a versatile solution for
175+
the Open edX platform.
176+
177+
Rejected Alternatives
178+
***********************
179+
180+
- Embedding AuthZ data in JWT tokens: As discussed in `0003-jwt-usage`,
181+
embedding AuthZ data in JWT tokens can lead to large token sizes and
182+
stale permissions, in addition to having to re-implement Casbin model
183+
logic in the frontend.
184+
185+
- Depending solely on backend enforcement on resource endpoints:
186+
Relying solely on backend enforcement can lead to a poor user
187+
experience, as users may see UI elements they cannot interact with,
188+
leading to confusion and frustration.
189+
190+
References
191+
************
192+
193+
- `Open edX REST API Conventions
194+
<https://openedx.atlassian.net/wiki/spaces/AC/pages/18350757/Open+edX+REST+API+Conventions>`_

0 commit comments

Comments
 (0)