[FC-0118] docs: add ADR for standardizing authentication patterns - #38301
Merged
Conversation
Contributor
Author
|
related doc worth reading: https://docs.openedx.org/projects/openedx-proposals/en/latest/best-practices/oep-0042-bp-authentication.html#consequences, we can make changes to the ADR based on the attached doc if needed. |
Faraz32123
changed the title
Faraz32123
force-pushed
the
docs/ADR-standardize_authentication_patterns_and_security_scheme_usage
branch
from
April 13, 2026 08:40
f5cb0c1 to
a6a25d3
Compare
feanil
reviewed
Apr 19, 2026
feanil
reviewed
Apr 21, 2026
| authentication mechanism for all API access** (external and internal), per `OEP-0042`_ | ||
| 2. **``BearerAuthentication`` and ``BearerAuthenticationAllowInactiveUser`` are | ||
| deprecated and MUST NOT be used in new code** | ||
| 3. **Session authentication MUST be used only for browser-based UI interactions** |
Contributor
There was a problem hiding this comment.
I'm not sure if this distinction is super important. What is the bad thing that happens if your API endpoints support session auth also? Right now DRF in openedx-platform supports both by default: https://github.com/openedx/openedx-platform/blob/master/openedx/envs/common.py#L822-L825 and I don't see a problem with that. I think it's more valuable that all endpoints support any valid auth scheme than having API calls not support the browser.
Contributor
Author
There was a problem hiding this comment.
@feanil I think you have valid point here that we should support any valid auth scheme instead of categorizing them on the basis of their usage.
I am adding a new commit that addresses above point with some additional remains(includes removal of JWT issuers & use of asymmetric keys) of OEP-0042, But it had some consequences(Link) that you might want to look in. That way we can decide the scope of this ADR. And we can remove the part that is not needed for this ADR accordingly.
Contributor
There was a problem hiding this comment.
I think this line is still worth updating to say that both JWT and Session auth are okay but other deprectaed authentication schemes such as bearer are not. What do you think. That way this aligns with the cleanup we want to do.
Abdul-Muqadim-Arbisoft
suggested changes
Apr 26, 2026
Contributor
|
@feanil: You should review openedx/edx-drf-extensions#284 and all its comments to see if you are missing anything, and you may want to reference it in this ADR. |
Faraz32123
force-pushed
the
docs/ADR-standardize_authentication_patterns_and_security_scheme_usage
branch
2 times, most recently
from
May 5, 2026 14:11
7504911 to
0ed80d7
Compare
robrap
reviewed
May 6, 2026
robrap
left a comment
robrap
left a comment
Contributor
There was a problem hiding this comment.
Additional thoughts. Thanks.
feanil
reviewed
May 7, 2026
|
|
||
| 1. **JWT authentication via** ``JwtAuthentication`` **MUST be the standard | ||
| authentication mechanism for all API(external and internal) access**, per `OEP-0042`_ | ||
| 2. **Session authentication MUST also be used when** the expected client for an API |
Contributor
There was a problem hiding this comment.
"For all API access" would include admin views, /oauth2/access_token/, and HMAC/webhook endpoints — none of which use JwtAuthentication. Narrow this to "DRF API endpoints that take user-authenticated requests" and list the exclusions for context.
Contributor
There was a problem hiding this comment.
@feanil: Would another way to say user-authenticated requests be password-authenticated or user-password-authenticated? I wasn't clear at first.
As an aside, for Mobile Authentication, there were some endpoints that will accept JwtAuthentication only if it has grant type password.
feanil
reviewed
Jun 4, 2026
Faraz32123
force-pushed
the
docs/ADR-standardize_authentication_patterns_and_security_scheme_usage
branch
from
June 10, 2026 08:17
03f1004 to
4d6afa4
Compare
Faraz32123
force-pushed
the
docs/ADRs-axim_api_improvements
branch
2 times, most recently
from
June 10, 2026 10:51
adf2e7b to
ad4b7ba
Compare
added 11 commits
June 17, 2026 11:51
Move BearerAuthentication depr plan out of this doc So that it resides in single place i.e. to its deprecation ticket.
Faraz32123
force-pushed
the
docs/ADR-standardize_authentication_patterns_and_security_scheme_usage
branch
from
June 17, 2026 06:52
9ad4526 to
6c35624
Compare
feanil
approved these changes
Jun 17, 2026
Faraz32123
deleted the
docs/ADR-standardize_authentication_patterns_and_security_scheme_usage
branch
June 19, 2026 07:38
Faraz32123
added a commit
that referenced
this pull request
Jun 24, 2026
* docs: add ADR for standardizing authentication patterns * docs: resolve confusion & update the ADR based on OEP-0042 * docs: support multiple valid auth schemes & deprecate BearerAuthentication * docs: change wording for decisions a bit. * docs: add real examples in accordance with our updated decisions * docs: sync ADR with edx-drf-extensions issue 284 openedx/edx-drf-extensions#284 * docs: make doc more explicit & address comments * docs: move Bearer auth depr plan out of ADR Move BearerAuthentication depr plan out of this doc So that it resides in single place i.e. to its deprecation ticket. * docs: add a pointer file in oauth_dispatch for this ADR * docs: make decision more clear * docs: make authentication_classes usage more clearer * docs: adress the comment related to session authentication
Faraz32123
added a commit
that referenced
this pull request
Jun 24, 2026
* docs: add ADR for standardizing authentication patterns * docs: resolve confusion & update the ADR based on OEP-0042 * docs: support multiple valid auth schemes & deprecate BearerAuthentication * docs: change wording for decisions a bit. * docs: add real examples in accordance with our updated decisions * docs: sync ADR with edx-drf-extensions issue 284 openedx/edx-drf-extensions#284 * docs: make doc more explicit & address comments * docs: move Bearer auth depr plan out of ADR Move BearerAuthentication depr plan out of this doc So that it resides in single place i.e. to its deprecation ticket. * docs: add a pointer file in oauth_dispatch for this ADR * docs: make decision more clear * docs: make authentication_classes usage more clearer * docs: adress the comment related to session authentication
Faraz32123
added a commit
that referenced
this pull request
Jun 24, 2026
* docs: add ADR for standardizing serializer usage (#38139) * docs: explicitly mention API versioning incase of backwards incompatible change (#38188) Co-authored-by: Muhammad Faraz Maqsood <faraz.maqsood@A006-01130.local> * docs: add ADR for standardizing permissions usage (#38187) Currently, authorization logic is implemented inconsistently across views, serializers, and custom access checks. This ADR will define a consistent approach using DRF permission classes, object-level permissions, and queryset scoping where appropriate. Co-authored-by: Taimoor Ahmed <taimoor.ahmed@A006-01711.local> * docs: minor change in ADR language * fix: add s back * docs: migrate restful & legacy django api endpoints to standard drf viewsets (#38191) * docs: Add ADR for ensuring GET requests are idempotent Add edx-platform/docs/decisions/0030-ensure-get-requests-are-idempotent.rst as an accepted ADR. Define policy that GET endpoints must be strictly read-only, with side effects moved to explicit write endpoints or async event pipelines. Include edx-platform relevance, anti-pattern vs preferred code examples, and rollout guidance for testing and migration. * docs: add ADR for standardizing API documentation and schema coverage - Propose adoption of drf-spectacular across Open edX services - Require @extend_schema decorators for all API endpoints - Document request/response schemas, status codes, and error conditions * docs: remove incorrect ADR number * docs: address api-doc-tools deprecation in ADR per review feedback - Add context explaining what api-doc-tools is and its relationship to drf-yasg - Document deprecation and archival of api-doc-tools as a consequence - Add migration guide mapping api-doc-tools decorators and URL helpers to their drf-spectacular equivalents - Add rejected alternative for updating api-doc-tools internals - Add rollout step for final archival cutover Closes review comment by @feanil * docs: expand ADR-0027 with api-doc-tools deprecation and drf-yasg incompatibility analysis Address review feedback on FC-0118 ADR 0027: - Add context paragraph explaining what api-doc-tools is (drf-yasg shim, decorators it provides, schema view, OpenAPI 2.0 output) - Document deprecation of api-doc-tools and drf-yasg as a consequence, including transition-window behavior - Add detailed 8-point incompatibility analysis explaining why drf-yasg cannot be replaced with drf-spectacular inside api-doc-tools (recorded in the ADR itself for future reference) - Add migration plan for existing api-doc-tools consumers with concrete decorator/import/setting mapping - Update Rollout Plan to track api-doc-tools removal - Add references to drf-spectacular migration guide, drf-yasg upstream status, and api-doc-tools repository * chore: fix edx-mantained to edX-platform * docs: add ADR for standardizing pagination across APIs (#38300) * docs: add ADR for api versioning strategy (#38304) * docs: add ADR for standardizing filtering/sorting parameters (#38303) * docs: add ADR-0029 standardized error responses decision (#38246) * docs: add ADR for merging similar endpoints (#38262) * docs: ADR for normalizing nested json apis (#38305) * docs: add separate example for input & output serializers * docs: ADR for documenting and consolidating internal MFE APIs (#38309) * docs: ADR for documenting and consolidating internal MFE APIs Define a plan to document all undocumented internal LMS APIs consumed by MFEs into stable, OpenAPI-described contracts. Introduces a consolidated config endpoint pattern with optional course/user context, authentication boundaries, and a rollout plan following OEP-21 DEPR process. * docs: add ADR for canonical MFE configuration endpoint Record that /api/frontend_site_config/v1/ is the canonical endpoint for MFE/front-end runtime configuration (frontend-base SiteConfig, OEP-65) and that /api/mfe_config/v1 is legacy, on the DEPR path tracked in #37255 and added, and that user-context data (roles, permissions) belongs on resource-oriented endpoints rather than on a configuration payload. Documentation/schema coverage is deferred to the API Documentation & Schema Coverage ADR (#38189). Partially supersedes ADR 0001 (MFE Config API). Part of FC-0118 Open edX REST API standardization (#38137). Refs #38280 * docs: add ADR for standardizing authentication patterns (#38301) * docs: add ADR for standardizing authentication patterns * docs: resolve confusion & update the ADR based on OEP-0042 * docs: support multiple valid auth schemes & deprecate BearerAuthentication * docs: change wording for decisions a bit. * docs: add real examples in accordance with our updated decisions * docs: sync ADR with edx-drf-extensions issue 284 openedx/edx-drf-extensions#284 * docs: make doc more explicit & address comments * docs: move Bearer auth depr plan out of ADR Move BearerAuthentication depr plan out of this doc So that it resides in single place i.e. to its deprecation ticket. * docs: add a pointer file in oauth_dispatch for this ADR * docs: make decision more clear * docs: make authentication_classes usage more clearer * docs: adress the comment related to session authentication * chore: correct file number w.r.t order of the ADRs --------- Co-authored-by: Muhammad Faraz Maqsood <faraz.maqsood@A006-01130.local> Co-authored-by: Taimoor Ahmed <68893403+taimoor-ahmed-1@users.noreply.github.com> Co-authored-by: Taimoor Ahmed <taimoor.ahmed@A006-01711.local> Co-authored-by: Robert Raposa <rraposa@edx.org> Co-authored-by: Abdul Muqadim <abdul.muqadim@A006-01811.local> Co-authored-by: Abdul Muqadim <abdul.muqadim@192.168.1.7> Co-authored-by: Abdul-Muqadim-Arbisoft <139064778+Abdul-Muqadim-Arbisoft@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
related issue: #38169