Overview

It is easy to cause issues when making changes to JWTs. This document is a place where we can capture things you should think about or be aware of when making these changes.

Understanding JWTs

If you need general background of JWTs, you can first learn what is a JWT and decisions around OAuth2 and JWTs in the Open edX platform in OEP-42: Authentication.

Known Authentication Challenges

If you want to make any change safely, having some awareness of known challenges may help you understand how to make your change safely.

• Search for “JWT” on the Authentication Challenges page to learn about known issues which you should keep in mind while making any changes related to JWTs.

• Code for JWT creation and decoding is unfortunately sprinkled through the platform, and is unnecessarily inconsistent.

  • The ticket Enable asymmetric JWTs everywhere · Issue #333 · openedx/edx-drf-extensions has many ideas on how to better observe and eventually avoid this situation.

  • Two known hotspots are edx-notes-api and Proctoring, both of which should be watched during any JWT related changes.

Rolling out JWT changes, including expiration

• Reminder that JWT tokens are requested by third-parties, so you’ll need to pay extra attention when monitoring and communicating around changes that may affect these tokens.

  • Although docs like 2. Authenticating as an edX REST Web Service User — EdX Course Catalog API User Guide documentation explain expiration, if the requester is not looking at the expiration and their script takes longer than the target expiration, errors will begin once the token expires.

• Reminder that client credential JWTs used for server-to-server calls are cached in each service. We've seen issues during rollout that weren’t seen until these JWTs expire and new ones are requested.

• Reminder of the current inconsistency around JWT creation and decoding documented under known challenges. This can easily cause problems where you least expect it.

Observability

• There are a number of custom attributes related to JWTs that can be used for monitoring changes.

• Private New Relic dashboards for edX.org that may help in monitoring:

  • JWT change rollout dashboard (private link)

  • Asymmetric JWT rollout dashboard (private link)

  • TODO: These private dashboards should probably be consolidated and reviewed for what is providing useful information.

Communication of changes

• Communicate any changes to support.

  • Although problems are likely to affect authentication, we’ve seen a variety of issues that did not obviously relate to JWT changes, at least at first. Ensure that any new support issues in the following day are tracked back to a start time to see if it aligns.

• Potentially provide early warning to partners (e.g. enterprise or other third-party users using JWTs) for certain types of changes.

• Communicate any changes to warroom for visibility.