feat: implement permission validation API and hooks for authz by bra-i-am · Pull Request #269 · openedx/frontend-base

bra-i-am · 2026-05-22T21:35:17Z

Resolves #150 by porting openedx/frontend-app-authoring#2685 to frontend-base

Adds a new runtime/authz module that lets MFEs validate user permissions against the openedx-authz backend service without writing their own API layer.

What's added:

validatePermissions(apiBaseUrl, query) — POSTs to /api/authz/v1/permissions/validate/me with a batch of { action, scope } pairs and maps the array response back to caller-defined keys. Missing keys default to false.
usePermissions(query, featureEnabled, options?) — React hook backed by TanStack Query. Permission keys are spread at the top level (no nested .permissions object) alongside isLoading, isError, and isAuthzEnabled flags.
- When featureEnabled is false: no API call is made and all keys return true, preserving pre-authz behavior during gradual rollout via waffle flags.
- When the API call fails: isError is true and all keys resolve to false.
- Accepts an optional apiBaseUrl override for MFEs still on @edx/frontend-platform.
permissionsQueryKeys — exported query key factory for manual cache invalidation.
TypeScript types — PermissionValidationQuery, PermissionValidationAnswer<Query>, and related request/response item types.
Tests — unit tests for both api.ts (5 cases) and hooks.ts covering the enabled/disabled paths, error states, and the flat return shape.
Documentation — docs/how_tos/permissions.md covering usage, caching, MFE-level wrapper pattern, best practices, and cache invalidation.

Testing

Clone edunext/frontend-app-authoring to your tutor env
Run tutor mounts add ../path/to/clone/
Switch to this branch bc/generalize-authz-validation. This branch already updates the authoring MFE to consume the usePermissions hook from frontend-base.
Go to /admin/waffle/flag/
Add flag and set Name to authz.enable_course_authoring, set Everyone to yes and save. If this is no, you should be able to use the legacy behavior without authz permissions
Clone this repo in the root of your local clone of frontend-authoring-mfe and switch to the branch of this PR, and run npm i && npm run build to update the dist folder
Install this locally by running:
```
npm install file:./frontend-base
```
Go to a course in the Authoring MFE http://apps.local.openedx.io:2001/authoring/course/{_course_id_}
Access the Pages and Resources page by clicking Content in the header
If you manipulate the permissions of a user at http://apps.local.openedx.io:2025/admin-console/authz?scope={_course_id_}, Pages and Resources should be working as expected for each role

LLM usage notice

Built with assistance from Claude.

openedx-webhooks · 2026-05-22T21:35:39Z

Thanks for the pull request, @bra-i-am!

This repository is currently maintained by @openedx/axim-engineering.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

rodmgwgu

Looking good, just added some comments for discussion. Thanks!

rodmgwgu · 2026-05-25T22:00:07Z

+ * Consumers destructure permission keys directly — no nested `.permissions` object.
+ *
+ * @example
+ * const { enableAuthz } = useWaffleFlags(courseId);


Can you confirm if this would handle cases where the waffle flag is disabled globally but enabled for a specific course or org? It looks like it should, but just to be sure.

Can we add a comment specifying this?

yees, it should! The hook is completely agnostic to how featureEnabled is calculated. It doesn't matter if it comes from a global or specific flag; if featureEnabled = true the hook will call the API

I'll be adding the comment to specify this

rodmgwgu · 2026-05-25T22:12:20Z

+
+## Best Practices
+
+- **Define permission constants** in your MFE (`COURSE_PERMISSIONS`, etc.) rather than


Would it make sense to include the constants for the existing permissions here in frontend-base?

@rodmgwgu, thanks a lot for this call!

According to what I assumed, the permissions are MFE-specific. For example, in authoring MFE, we use these permissions to manage a course. I don't think they'll be needed anywhere else, and I tried to avoid coupling frontend-base to specific MFE permissions

The thing is, I agree there is a valid case for centralizing permissions: we should do it for those that will be needed across multiple MFEs, but I'm not sure either if this will be applied to other MFEs 😅 (I think it would be possible, for example, to frontend-app-instructor-dashboard) and, in case this will be, which permissions would qualify to be added in the repo

What do you think?

I think we will need more high level discussion around this, currently the permissions in the backend are all defined in one place, openedx-authz, so having something similar in the frontend seems to make sense.

However, the plan is to extract those out of openedx-authz and instead define them on whatever module needs to implement them.

So keeping it per MFE makes sense for long term.

[Done] We are not indicating consumers where to find the permissions they can use. I suggest to include https://docs.openedx.org/projects/openedx-authz/en/latest/concepts/core_roles_and_permissions/index.html here in the how to as well as the hook TSDoc.

rodmgwgu · 2026-05-25T22:12:54Z

+import { useWaffleFlags } from './waffleHooks'; // your MFE's waffle flag hook
+import type { PermissionValidationQuery } from '@openedx/frontend-base';
+
+export const useResourcePermissions = <Query extends PermissionValidationQuery>(


This looks useful and generic enough, could we add it to frontend-base?

This is intentionally a recommended pattern rather than a reusable hook, mainly because it references two things that are MFE-specific: the waffle flag name (enableAuthzCourseAuthoring in Authoring MFE), and the waffle flag hook (useWaffleFlags, which in this case hits to an endpoint in the studio). I think neither of those can live in frontend-base without coupling the library to a specific MFE's implementation

What do you think?

You are right, although the flag is just one now (for course authoring), there could be more in the future, so keeping it as a recommendation is fine, thanks!

rodmgwgu · 2026-05-25T22:15:25Z

+  const { isLoading, isError, data } = useQuery<PermissionValidationAnswer<Query>, Error>({
+    queryKey: permissionsQueryKeys.validate(query, apiBaseUrl),
+    queryFn: featureEnabled ? () => validatePermissions(apiBaseUrl, query) : skipToken,
+    retry,


Should we specify a staleTime here?

bradenmacdonald · 2026-05-26T08:42:12Z

Thanks for adding this to frontend-base! I'm going to defer to others for the review, but I'm happy to see this, and the approach is similar to the code you contributed to the authoring MFE which I liked.

bra-i-am · 2026-05-26T23:54:27Z

@bradenmacdonald and @rodmgwgu, thanks a lot for your time reviewing this!

@rodmgwgu, I've already addressed the feedback you left. Looking forward to any additional comments!

rodmgwgu

Looks great, thanks!

brian-smith-tcril · 2026-06-02T16:08:26Z

Making sure I understand this PR correctly:

This is porting openedx/frontend-app-authoring#2685. I do think it likely makes sense to have this live in frontend-base eventually, but I'm not sure about the timing here.

The main thing that concerns me is

3. Switch to this branch bc/generalize-authz-validation. This branch already updates the authoring MFE to consume the usePermissions hook from frontend-base.

The package.json on bc/generalize-authz-validation shows frontend-base, frontend-platform and frontend-build as dependencies. I'm very hesitant to have that be a path we go down when converting MFEs to frontend-base.

I agree with #150 's goal of creating "reusable utils to query for permissions from openedx-authz on frontend MFEs," but I think in the short term it likely makes sense for this to live in a standalone package to be consumed by both frontend-base apps and frontend-build/frontend-platform MFEs.

I'd also like to hear @arbrandes's take on this.

arbrandes · 2026-06-16T15:59:24Z

The package.json on bc/generalize-authz-validation shows frontend-base, frontend-platform and frontend-build as dependencies. I'm very hesitant to have that be a path we go down when converting MFEs to frontend-base.

Same. Having those three as simultaneous dependencies could lead to Unforeseen Consequences (tm).

I think in the short term it likely makes sense for this to live in a standalone package to be consumed by both frontend-base apps and frontend-build/frontend-platform MFEs.

Good idea. @bra-i-am, do you think that's doable?

dcoa · 2026-07-30T05:36:29Z

Thanks for the feedback @brian-smith-tcril and @arbrandes. I think the proposal to manage this as a standalone library makes sense, especially given the progressive migration of MFEs to frontend-base and the incremental rollout of RBAC. Since we're initially focusing on a limited set of scopes and roles, we won't need to update all MFEs at the same time.

A shared library seems like a solid short- to medium-term solution. It allows both efforts to move forward in parallel.

One question: what's the preferred process for creating the repository? Would you prefer to create it directly under the Open edX organization, or should we create it under our organization first and then transfer it over?

arbrandes · 2026-07-30T12:05:46Z

Would you prefer to create it directly under the Open edX organization, or should we create it under our organization first and then transfer it over?

I think currently the best path is to have the repository in the openedx org from the start. The first step of the process is to create a GH Request to axim-engineering.

bra-i-am · 2026-07-30T15:09:46Z

@brian-smith-tcril, @arbrandes, @dcoa: thanks for your comments. This is totally doable, and I agree it's the best path to follow!

I've already created the GH Request: openedx/axim-engineering#1725

Do you think frontend-authz is a good name for the new repository, or would you name it differently?

arbrandes · 2026-08-07T10:50:25Z

As I mentioned in my review of https://github.com/openedx/frontend-authz/pull/2, before we fully commit to a new temporary repository instead of implementing the feature here (or here and in frontend-platform), I'd like to understand which MFEs besides Authoring will use the feature, and in what timeframe.

mphilbrick211 · 2026-08-19T20:56:46Z

As I mentioned in my review of openedx/frontend-authz#2, before we fully commit to a new temporary repository instead of implementing the feature here (or here and in frontend-platform), I'd like to understand which MFEs besides Authoring will use the feature, and in what timeframe.

Hi @bra-i-am! Flagging this for you.

dcoa · 2026-08-20T04:24:05Z

As we agreed on having this on frontend-base first, this PR is ready for review :)

@arbrandes @brian-smith-tcril

arbrandes

Have a couple of requests, but otherwise looking good so far.

arbrandes · 2026-08-20T18:16:04Z

+export { usePermissions, permissionsQueryKeys } from './hooks';
+export type { UsePermissionsOptions, UsePermissionsResult } from './hooks';
+export type { PermissionValidationQuery, PermissionValidationAnswer } from './types';


validatePermissions should probably also be exported, no?

I added it in the exports and also add a section in the 'how to' explaining when could be used over the hook. Please have a look and let me know if that make sense

…larity

…e test

dcoa · 2026-08-28T05:18:42Z

thank you @arbrandes for helping us with the review I addressed your comments, could you validate?

arbrandes

Thanks for addressing the previous review. I have a couple more suggestions, if you don't mind.

arbrandes · 2026-08-28T13:46:59Z

+export interface PermissionValidationRequestItem {
+  action: string;
+  scope?: string;
+}


Make scope required (scope: string), and fix the @example on line 18, which shows { canEdit: { action: 'courses.edit' } } with no scope.

PermissionValidationSerializer composes ScopeMixin, whose scope = serializers.CharField(max_length=255) is required and non-blank (serializers.py:14-33), and the view indexes perm["scope"] unconditionally. Omitting it 400s the whole request, and since validatePermissions sends one batch for the entire query, every key in that query then resolves to false - a silent deny across the hook, triggered by a type that says the field is optional.

arbrandes · 2026-08-28T13:46:59Z

+  const { isLoading, isError, data } = useQuery<PermissionValidationAnswer<Query>, Error>({
+    queryKey: permissionsQueryKeys.validate(query, apiBaseUrl),
+    queryFn: featureEnabled ? () => validatePermissions(apiBaseUrl, query) : skipToken,
+    retry,
+    staleTime,
+  });
+
+  // Derived once: a disabled consumer must never be treated as loading, even when it
+  // shares a cache key with an enabled consumer whose fetch is in flight. Blanking the
+  // keys off the raw isLoading there would return isLoading: false with undefined keys.
+  const isPermissionsLoading = featureEnabled && isLoading;


Destructure isPending instead of isLoading:

const { isPending, isError, data } = useQuery(/* ... */); // ... const isPermissionsLoading = featureEnabled && isPending;

isLoading is actually isPending && isFetching. With the default networkMode: 'online', a query that cannot start because the browser is offline sits at fetchStatus: 'paused', so isFetching is false and isLoading never goes true. A consumer following the documented isLoading / isError / if (!canView) deny sequence renders a permission denial instead of a spinner.

arbrandes · 2026-08-28T13:46:59Z

+export { validatePermissions } from './api';
+export { usePermissions, permissionsQueryKeys } from './hooks';
+export type { UsePermissionsOptions, UsePermissionsResult } from './hooks';
+export type { PermissionValidationQuery, PermissionValidationAnswer } from './types';


Minor: consider also exporting PermissionValidationRequestItem and PermissionValidationResponseItem.

Now that validatePermissions is public, a caller typing the raw call's inputs or narrowing a response has no way to name those shapes.

arbrandes · 2026-08-28T13:46:59Z

+  return {
+    isLoading: isPermissionsLoading,
+    isError: featureEnabled && isError,
+    isAuthzEnabled: featureEnabled,
+    ...permissionResults,
+  } as UsePermissionsResult<Query>;


Minor: consider returning error alongside isError.

With retry: false, a consumer cannot tell a 401/403 from a transient network failure - both produce the same all-false result.

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label May 22, 2026

openedx-webhooks added this to Contributions May 22, 2026

github-project-automation Bot moved this to Needs Triage in Contributions May 22, 2026

bra-i-am force-pushed the bc/generalize-authz-validation branch from 99425d5 to 2c9c885 Compare May 22, 2026 21:56

bra-i-am marked this pull request as ready for review May 25, 2026 15:58

bra-i-am changed the title ~~[WIP] feat: implement permission validation API and hooks for authz~~ feat: implement permission validation API and hooks for authz May 25, 2026

bra-i-am marked this pull request as draft May 25, 2026 16:01

bra-i-am marked this pull request as ready for review May 25, 2026 21:12

bra-i-am requested review from arbrandes, bradenmacdonald, brian-smith-tcril, irfanuddinahmad, jacobo-dominguez-wgu and rodmgwgu May 25, 2026 21:13

rodmgwgu reviewed May 25, 2026

View reviewed changes

bra-i-am requested a review from rodmgwgu May 26, 2026 23:54

rodmgwgu approved these changes May 27, 2026

View reviewed changes

mphilbrick211 moved this from Needs Triage to In Eng Review in Contributions Jun 1, 2026

bra-i-am mentioned this pull request Jul 30, 2026

[GH Request] Create a repository to unify frontend authz utils openedx/axim-engineering#1725

Closed

bra-i-am mentioned this pull request Jul 30, 2026

feat: implement permission validation API and hooks for frontend-authz bra-i-am/frontend-authz-test#3

Open

dcoa mentioned this pull request Aug 6, 2026

Task - RBAC AuthZ - Implement AuthZ Utils into frontend-base #150

Open

arbrandes mentioned this pull request Aug 20, 2026

npm run lint exits 0 when eslint reports errors, so CI misses them #295

Open

arbrandes requested changes Aug 20, 2026

View reviewed changes

arbrandes reviewed Aug 20, 2026

View reviewed changes

Comment thread docs/how_tos/permissions.md Outdated

arbrandes reviewed Aug 20, 2026

View reviewed changes

Comment thread docs/how_tos/permissions.md Outdated

bra-i-am and others added 8 commits August 28, 2026 13:52

feat: implement permission validation API and hooks for authz

3782081

feat: enhance usePermissions hook with error handling and loading states

b87e6d2

refactor: simplify permission validation logic and update types for c…

da54197

…larity

refactor: address feedback

65c607f

docs: add link to permissions documentation

0198af6

docs: remove frontend-platoform references

6e44220

docs: update hoew to

3c4a85c

test: improve hooks test suite

2e09fe5

dcoa force-pushed the bc/generalize-authz-validation branch 2 times, most recently from 718ab6f to f035bb0 Compare August 28, 2026 03:57

dcoa added 3 commits August 28, 2026 14:51

refactor: take in cosideration featureEnabled when loading and improv…

f81d2cb

…e test

docs: add a section to explain when to use validatePermissions

f6971bc

style: fix linter after rebase

47da6df

dcoa force-pushed the bc/generalize-authz-validation branch from f035bb0 to 47da6df Compare August 28, 2026 04:51

dcoa requested a review from arbrandes August 28, 2026 05:17

arbrandes requested changes Aug 28, 2026

View reviewed changes


		## Best Practices

		- Define permission constants in your MFE (`COURSE_PERMISSIONS`, etc.) rather than

Uh oh!

Conversation

bra-i-am commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Testing

LLM usage notice

Uh oh!

openedx-webhooks commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rodmgwgu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bra-i-am May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dcoa Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bradenmacdonald commented May 26, 2026

Uh oh!

bra-i-am commented May 26, 2026

Uh oh!

rodmgwgu left a comment

Choose a reason for hiding this comment

Uh oh!

brian-smith-tcril commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

arbrandes commented Jun 16, 2026

Uh oh!

dcoa commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

arbrandes commented Jul 30, 2026

Uh oh!

bra-i-am commented Jul 30, 2026

Uh oh!

arbrandes commented Aug 7, 2026

Uh oh!

mphilbrick211 commented Aug 19, 2026

Uh oh!

dcoa commented Aug 20, 2026

Uh oh!

arbrandes left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dcoa Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dcoa commented Aug 28, 2026

bra-i-am commented May 22, 2026 •

edited

Loading

openedx-webhooks commented May 22, 2026 •

edited

Loading

bra-i-am May 26, 2026 •

edited

Loading

dcoa Jul 30, 2026 •

edited

Loading

brian-smith-tcril commented Jun 2, 2026 •

edited

Loading

dcoa commented Jul 30, 2026 •

edited

Loading

dcoa Aug 28, 2026 •

edited

Loading