docs: add ADR on JWT usage

[rodmgwgu]

Description

This PR adds a proposed ADR on the use of JWT tokens for AuthZ.

The decision on this document is open for discussion, please add any comment or concern on the proposed approach, this was derived based on my research on past and present usage of JWT tokens on the platform and previous efforts for implementing authorization mechanisms.

My knowledge on this part of the platform and it's history is still limited, so please feel free to add any concerns or points that I may not have taken into account.

[openedx-webhooks]

Thanks for the pull request, @rodmgwgu!

This repository is currently maintained by @openedx/committers-openedx-authz.

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:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

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.

[mariajgrimaldi]

@sarina @rodmgwgu: can we get the CLA signed? 👀 Not sure how this is working with WGU.

[mariajgrimaldi]

I generally agree with this approach!

Currently, I can only see those roles being passed currently directly in the JWT payload: https://github.com/openedx/edx-platform/blob/acbf50a7dd8492a9fb80f35ffbc561b668fe619d/openedx/core/djangoapps/oauth_dispatch/jwt.py#L275-L276 for administrator and superuser roles. We haven't decided whether to use those django-native definitions still or move them into the authZ. What makes more sense to me, simplicity-wise, is to keep using those and implement other feature-specifics into the authz system but we'd need a way of integrating them seamlessly. In any case, that would mean continuing to send the same roles in the same format. What do you think?

[rodmgwgu]

Yes, the existing roles will continue being passed to the JWT as-is, and for now will still be picked by the current auth code.

The new AuthZ implementation won't directly care about these, unless we find any special case that would need it, in that case we would do an "OR" on the specific action, for example:

Let's say that we identify that superuser should always have access to "read" any Library, on the GET library endpoint handler, we would validate like (pseudo code):

has_access = is_superuser() or new_authz_has_permission("library-read", user, library)

where is_superuser() is the existing code that validates this, and new_authz_has_permission is our new implementation.

Would this make sense?

[mariajgrimaldi]

Yes, that makes total sense. I think this is the simplest approach given the current state.

Another case came to my attention last week while I was discussing with my team about how the new authz framework should interact with other systems: Aspects. Currently, this is how the system manages access to its resources:
https://github.com/openedx/tutor-contrib-aspects/blob/e0db9f51250fd842dcdcce8abb57befc17cff0ae/tutoraspects/templates/aspects/apps/superset/pythonpath/openedx_sso_security_manager.py#L179-L208 - roles are sent in the JWT. It looks like we only use admin and superuser -I think- so it should work the same.

If this is not the case, then we'll need to decide on our next steps for handling this specific case of authorization management, but it's not an immediate blocker. Should we document this somewhere?

FYI @bmtcril

[bmtcril]

I think if the existing JWT implementation doesn't change that is fine for Aspects' use of the superuser role to grant access to all reports.

However in the long term, the way Aspects uses the courses endpoint to find which roles the user has on individual courses will have to change. Ideally we would have an endpoint that would allow us to get all courses that a specific user has a specific permission on instead of having to query all courses that the user is associated with, then do further API calls to determine if they have the necessary permission to view reports for each course.

I'm not sure those details are relevant to this ADR, but we may want to capture the generic use case for "external service needs to check LMS/Studio permissions over API" somewhere.

[rodmgwgu]

@sarina @rodmgwgu: can we get the CLA signed? 👀 Not sure how this is working with WGU.

We are working on it now, thanks.

[sarina]

Closing to rekick the CLA check

[sarina]

This looks great to me! Requesting a review as well from @bmtcril

[sarina]

Closing and re-opening to kick the new status check.

[sarina]

@mariajgrimaldi could you review and merge when you're ready?

[mariajgrimaldi]

@sarina: of course! I added a comment earlier today: #34 (comment). By the way, I don't think I have write permissions yet.

[sarina]

@mariajgrimaldi you do now! 🙂

[sarina]

This is not actually important but the bullets in this section are nested too far and in the rendered view they view as quotes (https://openedx-authz--34.org.readthedocs.build/en/34/decisions/0003-jwt-usage.html#possible-methods). Probably not actually worth fixing, but worth paying attention to for more user-facing documentation.

[mariajgrimaldi]

LGTM!