Skip to content

[DEPR]: BearerAuthentication #284

Open
DEPR
Open
[DEPR]: BearerAuthentication#284
DEPR
Labels
deprProposal for deprecation & removal per OEP-21

Description

@robrap
robrap
opened on Dec 8, 2022

Proposal Date

2022-12-08

Target Ticket Acceptance Date

2022-12-23

Earliest Open edX Named Release Without This Functionality

Q - 2023-10

Rationale

The use of BearerAuthentication was informally documented as deprecated in OEP-42: Authentication, created on 2020-02-28. This OEP was just capturing an earlier (possibly undocumented) decision to deprecate in favor of the newer JWT authentication. At the time OEP-42 was documented, the only reason to keep BearerAuthentication was in support of mobile apps, because they didn't yet support JWT authentication. However, JWT Authentication is now supported for mobile apps as well.

The reason to remove BearerAuthentication is to simplify our authentication to fewer technologies, making it safer and easier to understand.

Removal

Docs and referencing code will need to be updated. See BearerAuthentication GitHub search results for a start.

This ADR will be partially superseded/updated, because BearerAuthentication would no longer be an option.

Replacement

Usage will be replaced by JwtAuthentication:

edx-drf-extensions/edx_rest_framework_extensions/auth/jwt/authentication.py

Line 26 in a03c5fc

class JwtAuthentication(JSONWebTokenAuthentication):

Deprecation

There is no active plan.

  • The BearerAuthentication class is not currently marked as deprecated, but it could be.
  • We could mark as deprecated when access tokens are requested in the form of Bearer (opaque) tokens.

Migration

It should be pretty simple for clients to request a JWT access token, in place of a Bearer token, and pass it in the request header instead.

Possible migration issues

  1. This might be used by third parties, like other enterprises, and a long enough per-operator communication effort would be needed. Or, we could attempt to automatically fix requests.
  2. Requests currently require a separate authorization header prefix (e.g. "JWT" vs "Bearer" ), so when we ultimately switch default access token requests from Bearer to JWT, we'd either start failing a lot of requests, or we'd need some code to try to fix the header if the wrong one was used (or some other code like this).
    a. See Open edX docs on using APIs.
    b. If "token_type": "jwt" is not supplied, I believe we return a Bearer token by default. I assume we'd want to update the default?
    c. If "token_type": "bearer" is used, would we want to fail? The alternative would be to return a JWT and allow JWTs to also work with the Bearer authorization header, which I believe is the default outside of the Open edX platform for JwtAuthentication. I'm not sure if this would take some thought for an expand phase where Bearer tokens might still be in use. Or maybe clients will just get a taste of the 1 hour expiration issue (see next point) a little faster.
  3. Depending on your config, it is likely that JWTs will expire after an hour, but Bearer tokens would have lasted for 2 weeks? If a third-party is running a long job (> an hour) and reusing a token without checking its expiration, they would run into issues once the token expires.3. When we start switching to JWTs where opaque tokens were formerly used, the new token will be much larger than the old token. In general this shouldn't be an issue, but if anyone has special code that make assumptions about the max size of this token (like some proctoring code had), it could cause unexpected issues.

Additional Info

There is a custom attribute that allows for monitoring of BearerAuthentication usage.

UPDATE: The edx-platform implementation uses the same custom attribute, which is very misleading. Additional monitoring is required to ensure we know which version of the class is in-use so that we can retire the edx-drf-extensions version, and then ultimately retire the edx-platform version.

Activity

  1. robrap
    added
    deprProposal for deprecation & removal per OEP-21
    on Dec 8, 2022
  2. openedx-workflow-automation
    added this to DEPR: Deprecation & Removalon Dec 8, 2022
  3. openedx-workflow-automation
    moved this to Proposed in DEPR: Deprecation & Removalon Dec 8, 2022
  4. robrap
    moved this from Proposed to Communicated in DEPR: Deprecation & Removalon Dec 9, 2022
  5. robrap
    self-assigned this
    on Dec 9, 2022
  6. robrap
    removed their assignment
    on Jan 12, 2023
  7. dianakhuang
    moved this from Communicated to Accepted in DEPR: Deprecation & Removalon Jan 12, 2023

  8. robrap commented on May 11, 2023

    @robrap
    robrap
    on May 11, 2023
    ContributorAuthor

    Note: When we start switching to JWTs where opaque tokens were formerly used, the new token will be much larger than the old token. In general this shouldn't be an issue, but if anyone has special code that make assumptions about the max size of this token (like some proctoring code had), it could cause unexpected issues.

  9. robrap commented on Aug 17, 2023

    @robrap
    robrap
    on Aug 17, 2023
    ContributorAuthor

    Additional details:

    1. Ecommerce is configured with its [own subclass of BearerAuthentication](See https://github.com/search?q=repo%3Aopenedx%2Fecommerce%20BearerAuthentication&type=code.). However, since the tokens are all in the LMS database, it makes no sense for this to be used. According to monitoring, all uses have the result of None as reported by this line, so it should be a no-op to just remove this from ecommerce.
    2. Edx-platform has its own versions of BearerAuthentication (and related authentication classes), and are really what this DEPR is about. See https://github.com/openedx/edx-platform/blob/f20b7ec985e9a5450b48b9725c4f76821041e844/openedx/core/lib/api/authentication.py. I'm not clear on how we ended up with a version in edx-drf-extensions, since this form of authentication was only ever available inside edx-platform.

    Based on the above, it seems like clean up of ecommerce should be the simplest. Clean-up of edx-drf-extensions versions of BearerAuthentication should be done next, simply switching to the edx-platform implementation. Finally, there would be the work of getting people to stop using these Bearer tokens, which is the harder part of this DEPR.

  10. dianakhuang
    moved this from Accepted to Proposed in DEPR: Deprecation & Removalon Apr 4, 2024

  11. robrap commented on May 23, 2025

    @robrap
    robrap
    on May 23, 2025
    ContributorAuthor

    [inform] This DEPR is in the Draft state. It can't move forward without a DEPR coordinator to help update it to match the updated DEPR template. No action is required, unless anyone wants to move this out of Draft.

  12. arbrandes
    added the
    DEPR
    issue type on Jan 28, 2026
  13. Faraz32123
    added a commit that references this issue on May 5, 2026

    docs: sync ADR with edx-drf-extensions issue 284

    0ed80d7
  14. github-project-automation
    added this to Arch-BOMon May 7, 2026

  15. Faraz32123 commented on May 18, 2026

    @Faraz32123
    Faraz32123
    on May 18, 2026

    Hi @robrap, as discussed in openedx-platform#38301, I moved the BearerAuthentication deprecation/removal steps out of the ADR. Here are the items I'd like to propose be added to the DEPR ticket description:

    Proposed additions to "Possible Migration Issues" section:

    1. Bearer tokens last ~2 weeks depending on config; JWTs expire in ~1 hour. Long-running jobs that reuse a token without checking expiry will start failing after migration. Clients should use refresh tokens (grant_type=refresh_token at /oauth2/access_token/) or check the exp claim before each request.
    2. Both openedx/core/lib/api/authentication.py (edx-platform) and edx_rest_framework_extensions/auth/bearer/authentication.py (edx-drf-extensions) use the same custom monitoring attribute name for BearerAuthentication. When checking active usage via that attribute, correlate carefully to distinguish which class is actually in use.

    Proposed additions to "Removal Steps" / Rollout section:

    1. Audit existing APIs — flag any explicitly setting BearerAuthentication or BearerAuthenticationAllowInactiveUser in authentication_classes.
    2. Check active Bearer token usage via the custom monitoring attribute before removing anything.
    3. The primary migration target in edx-platform is the view_auth_classes decorator in openedx/core/lib/api/view_utils.py, one change there removes BearerAuthenticationAllowInactiveUser from 49+ endpoints.
    4. Mark BearerAuthentication / BearerAuthenticationAllowInactiveUser deprecated in source with a deprecation warning
    5. Verify no active external clients are still sending Bearer tokens before removal
    6. Migrate external clients from Bearer tokens to JWT (requires proper notice, community post, deprecation announcement)
    7. Remove BearerAuthentication and its OAuth2Authentication / OAuth2AuthenticationAllowInactiveUser aliases once migration is complete.

    Feel free to adjust the ticket description, Or we can do it once the ADR is approved.
    -- @feanil

  16. Faraz32123
    added 5 commits that reference this issue on Jun 17, 2026

    docs: sync ADR with edx-drf-extensions issue 284

    9dacd49

    docs: add ADR for standardizing authentication patterns (#38301)

    a961dd3

    docs: add ADR for standardizing authentication patterns (#38301)

    28ebcd5

    docs: add ADR for standardizing authentication patterns (#38301)

    9dfca5b

    docs: ADRs for axim api improvements (#38738)

    36a192d
  17. blarghmatey
    added a commit that references this issue on Sep 17, 2026

    docs: ADRs for axim api improvements (openedx#38738)

    19efa5b
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    deprProposal for deprecation & removal per OEP-21

    Type

    DEPR

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions