Skip to content

Commit bbb69ea

Browse files
rodmgwgurodmgwgu
committed
docs: ADR for Enforcement mechanisms - communication with MFEs and other clients
1 parent ec2e182 commit bbb69ea

1 file changed

Lines changed: 197 additions & 0 deletions

File tree

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

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
0007: Enforcement mechanisms - communication with MFEs and other 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.
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+
Decision
34+
**********
35+
36+
I. REST API for authorization queries
37+
=====================================
38+
39+
We will implement a dedicated REST API endpoint that frontend
40+
applications can use to query for specific permissions. Queries would be
41+
at the Subject-Action-Object-Context level, being the Subject always the
42+
current authenticated user. This allows the frontend to check if a user
43+
has permission to perform a specific action on a specific object within
44+
a given context.
45+
46+
To optimize performance and reduce latency, the API will support batch
47+
queries, allowing multiple permission checks in a single request. It
48+
will also have caching mechanisms in place.
49+
50+
API Definition
51+
--------------
52+
53+
POST /api/authz/v1/permissions/validate
54+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
55+
56+
Validate if the current user has specific permissions.
57+
58+
Request Body:
59+
"""""""""""""
60+
61+
Format:
62+
63+
.. code:: ts
64+
65+
Array<{
66+
action: string
67+
object?: string
68+
scope?: string
69+
}>
70+
71+
Example:
72+
73+
.. code:: json
74+
75+
[
76+
{
77+
"action": "act:read",
78+
"object": "lib:test-lib",
79+
"scope": "org:OpenedX"
80+
},
81+
{
82+
"action": "act:edit",
83+
"object": "lib:test-lib",
84+
"scope": "org:OpenedX"
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+
object?: string
106+
scope?: string
107+
allowed: boolean
108+
}>
109+
110+
Example:
111+
112+
.. code:: json
113+
114+
[
115+
{
116+
"action": "act:read",
117+
"object": "lib:test-lib",
118+
"scope": "org:OpenedX",
119+
"allowed": true
120+
},
121+
{
122+
"action": "act:edit",
123+
"object": "lib:test-lib",
124+
"scope": "org:OpenedX",
125+
"allowed": false
126+
}
127+
]
128+
129+
Possible response codes:
130+
""""""""""""""""""""""""
131+
132+
- 200: Ok, includes the Response Body defined above.
133+
- 400: Bad Request, happens when the request body doesn't match the
134+
required format.
135+
- 401: Unauthorized, happens when the user is not authenticated/logged in.
136+
137+
**Please note:** There is no “404 not found” case here, if the action,
138+
object or scope doesn't exist, the “allowed” value in the response will
139+
be whatever Casbin evaluates in this case.
140+
141+
II. Frontend integration
142+
========================
143+
144+
Frontend applications will integrate with the REST API to enforce
145+
authorization decisions. This will involve:
146+
147+
#. Querying the API for permissions when rendering UI components.
148+
#. Using the API response to conditionally render or style UI elements
149+
based on the user's permissions.
150+
#. Implementing a caching strategy on the frontend to minimize API calls
151+
and improve performance.
152+
153+
The specifics on when and how to query the API will depend on the
154+
application's architecture and user interaction patterns.
155+
156+
Standard frontend library functions will be developed to facilitate
157+
permission queries, incorporating reasonable defaults for caching,
158+
request deduplication, and auto-refresh mechanisms. These functions will
159+
most likely be implemented as part of frontend-base.
160+
161+
Consequences
162+
**************
163+
164+
- The REST API approach provides a flexible and scalable way to enforce
165+
AuthZ decisions across different frontend applications.
166+
167+
- It allows for real-time updates to permissions, as the frontend can
168+
query the API as needed.
169+
170+
- The batch query and caching mechanisms help mitigate performance
171+
concerns, ensuring that the user experience remains smooth.
172+
173+
- Frontend developers will need to implement the necessary logic to
174+
interact with the REST API and enforce AuthZ decisions.
175+
176+
- The approach is adaptable to various frontend architectures,
177+
including MFEs and mobile apps, making it a versatile solution for
178+
the Open edX platform.
179+
180+
Rejected Alternatives
181+
***********************
182+
183+
- Embedding AuthZ data in JWT tokens: As discussed in `0003-jwt-usage`,
184+
embedding AuthZ data in JWT tokens can lead to large token sizes and
185+
stale permissions, in addition to having to re-implement Casbin model
186+
logic in the frontend.
187+
188+
- Depending solely on backend enforcement on resource endpoints:
189+
Relying solely on backend enforcement can lead to a poor user
190+
experience, as users may see UI elements they cannot interact with,
191+
leading to confusion and frustration.
192+
193+
References
194+
************
195+
196+
- `Open edX REST API Conventions
197+
<https://openedx.atlassian.net/wiki/spaces/AC/pages/18350757/Open+edX+REST+API+Conventions>`_

0 commit comments

Comments
 (0)