feat: Add scope user_id to JWT payload

openedx/core/djangoapps/oauth_dispatch/docs/decisions/0015-add-scope-user-id-for-jwt.rst

@@ -0,0 +1,36 @@
+15. Add scope user_id for JWT token
+###################################
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+In Feb 2018, to enable analytics (Segment) from Microfrontends (MFEs), a ``user_id`` claim was added to the JWT token `in this PR<https://github.com/openedx/edx-platform/pull/19765>`__.
+
+The LMS API `to create authentication tokens`_ is used by external organizations to request a token on behalf of their users, mostly using grant_type ``client_credentials`` in the request. Since ``user_id`` is considered sensitive information, especially when combined with email and username which were already available in the JWT, it was decided to only add the ``user_id`` claim when a ``user_id`` scope was supplied. All MFE JWT cookies, which are known to only be used directly by the user, automatically used the ``user_id`` scope in order to get the required ``user_id`` claim.
+
+No ADR could be found for the Feb 2018 decision detailed above.
+
+In June 2019, an `ADR was captured in ecommerce`_ around the requirements to have the LMS user_id available for requests to ecommerce.
+
+In 2022, the mobile apps switched to using JWTs for authentication. However, these JWTs were missing the ``user_id`` scope and claim required by the ecommerce service.
+
+.. _to create authentication tokens: https://github.com/openedx/edx-platform/blob/caf8e456e28f9b9a1f5fa7186d3d155112fb75be/openedx/core/djangoapps/oauth_dispatch/urls.py#L14
+.. _ADR was captured in ecommerce: https://github.com/openedx/ecommerce/blob/master/docs/decisions/0004-unique-identifier-for-users.rst
+
+Decisions
+---------
+
+- The original decision to add the ``user_id`` claim to the JWT token using the ``user_id`` scope has been captured in the context of this ADR, because no ADR could be found.
+- The scope ``user_id`` will be added to all requests having grant_type ``password`` in the API `/oauth2/access_token/`.
+
+Consequences
+------------
+
+- The claim ``user_id`` will be present in the JWT token for all requesters who already have access to the login credentials of the user account.
+- The ``user_id`` scope will continue to protect other JWT requests that don't require this sensitive information.
+- This pattern could potentially be used to clean-up the manually added ``user_id`` scope for oauth clients involved in the social auth flow in the future.

openedx/core/djangoapps/oauth_dispatch/jwt.py

@@ -12,6 +12,7 @@
 from edx_toggles.toggles import SettingToggle
 from jwt import PyJWK
 from jwt.utils import base64url_encode
+from oauth2_provider.models import Application
 
 from common.djangoapps.student.models import UserProfile, anonymous_id_for_user
 
@@ -170,7 +171,8 @@ def _create_jwt(
     # Default scopes should only contain non-privileged data.
     # Do not be misled by the fact that `email` and `profile` are default scopes. They
     # were included for legacy compatibility, even though they contain privileged data.
-    scopes = scopes or ['email', 'profile']
+    # The scope `user_id` must be added for requests with grant_type password.
+    scopes = _update_user_id_in_scopes(scopes or ['email', 'profile'], grant_type)
     iat, exp = _compute_time_fields(expires_in)
 
     payload = {
@@ -285,3 +287,9 @@ def _encode_and_sign(payload, use_asymmetric_key, secret):
 
     jwk = PyJWK(key, algorithm)
     return jwt.encode(payload, jwk.key, algorithm=algorithm)
+
+
+def _update_user_id_in_scopes(scopes, grant_type):
+    if grant_type == Application.GRANT_PASSWORD and 'user_id' not in scopes:
+        scopes.append('user_id')
+    return scopes

openedx/core/djangoapps/oauth_dispatch/tests/test_jwt.py

@@ -21,6 +21,7 @@ def setUp(self):
         super().setUp()
         self.user = UserFactory()
         self.default_scopes = ['email', 'profile']
+        self.default_scopes_password_grant_type = ['email', 'profile', 'user_id']
 
     def _create_client(self, oauth_adapter, client_restricted, grant_type=None):
         """
@@ -176,7 +177,7 @@ def test_password_grant_type(self):
         jwt_token_dict = jwt_api.create_jwt_token_dict(token_dict, oauth_adapter, use_asymmetric_key=False)
 
         self.assert_valid_jwt_access_token(
-            jwt_token_dict["access_token"], self.user, self.default_scopes,
+            jwt_token_dict["access_token"], self.user, self.default_scopes_password_grant_type,
             grant_type='password',
         )
 

openedx/core/djangoapps/oauth_dispatch/tests/test_views.py

@@ -174,16 +174,22 @@ def _test_jwt_access_token(self, client_attr, token_type=None, headers=None, gra
         expected_default_expires_in = 60 * 60
         assert data['expires_in'] == expected_default_expires_in
         assert data['token_type'] == 'JWT'
+        expected_scopes = data['scope'].split(' ')
+        self._update_expected_scopes_with_user_id(expected_scopes, grant_type)
         self.assert_valid_jwt_access_token(
             data['access_token'],
             self.user,
-            data['scope'].split(' '),
+            expected_scopes,
             grant_type=grant_type,
             should_be_restricted=False,
             expires_in=expected_default_expires_in,
             should_be_asymmetric_key=asymmetric_jwt
         )
 
+    def _update_expected_scopes_with_user_id(self, expected_scopes, grant_type):
+        if grant_type == 'password' and 'user_id' not in expected_scopes:
+            expected_scopes.append('user_id')
+
     @ddt.data('dot_app')
     def test_access_token_fields(self, client_attr):
         client = getattr(self, client_attr)
@@ -258,18 +264,20 @@ def test_restricted_jwt_access_token(self):
         response = self._post_request(self.user, self.restricted_dot_app, token_type='jwt')
         assert response.status_code == 200
         data = json.loads(response.content.decode('utf-8'))
-
+        grant_type = 'password'
+        expected_scopes = data['scope'].split(' ')
+        self._update_expected_scopes_with_user_id(expected_scopes, grant_type)
         assert 'expires_in' in data
         assert data['expires_in'] > 0
         assert data['token_type'] == 'JWT'
         self.assert_valid_jwt_access_token(
             data['access_token'],
             self.user,
-            data['scope'].split(' '),
+            expected_scopes,
             should_be_expired=False,
             should_be_asymmetric_key=True,
             should_be_restricted=True,
-            grant_type='password'
+            grant_type=grant_type
         )
 
     def test_restricted_access_token(self):
@@ -322,6 +330,7 @@ def test_jwt_access_token_scopes_and_filters(self, grant_type):
         response = self._post_request(self.user, dot_app, token_type='jwt', scope=scopes)
         assert response.status_code == 200
         data = json.loads(response.content.decode('utf-8'))
+        self._update_expected_scopes_with_user_id(scopes, grant_type)
         self.assert_valid_jwt_access_token(
             data['access_token'],
             self.user,
@@ -427,14 +436,20 @@ def _test_jwt_access_token(self, client_attr, token_type=None, headers=None, gra
         assert data['expires_in'] > 0
         assert data['token_type'] == 'JWT'
 
+        expected_scopes = data['scope'].split(' ')
+        self._update_expected_scopes_with_user_id(expected_scopes, grant_type)
         self.assert_valid_jwt_access_token(
             data['access_token'],
             self.user,
-            data['scope'].split(' '),
+            expected_scopes,
             grant_type=grant_type,
             should_be_asymmetric_key=asymmetric_jwt
         )
 
+    def _update_expected_scopes_with_user_id(self, expected_scopes, grant_type):
+        if grant_type == 'password' and 'user_id' not in expected_scopes:
+            expected_scopes.append('user_id')
+
     @ddt.data('dot_app')
     def test_access_token_exchange_calls_dispatched_view(self, client_attr):
         client = getattr(self, client_attr)
@@ -451,11 +466,14 @@ def test_jwt_access_token_exchange_calls_dispatched_view(self, client_attr):
         response = self._post_request(self.user, client, token_type='jwt')
         assert response.status_code == 200
         data = json.loads(response.content.decode('utf-8'))
+        grant_type = 'password'
+        expected_scopes = data['scope'].split(' ')
+        self._update_expected_scopes_with_user_id(expected_scopes, grant_type)
         self.assert_valid_jwt_access_token(
             data['access_token'],
             self.user,
-            data['scope'].split(' '),
-            grant_type='password'
+            expected_scopes,
+            grant_type=grant_type
         )
 
         assert 'expires_in' in data
@@ -470,11 +488,14 @@ def test_asymmetric_jwt_access_token_exchange_calls_dispatched_view(self, client
         response = self._post_request(self.user, client, token_type='jwt', asymmetric_jwt=True)
         assert response.status_code == 200
         data = json.loads(response.content.decode('utf-8'))
+        grant_type = 'password'
+        expected_scopes = data['scope'].split(' ')
+        self._update_expected_scopes_with_user_id(expected_scopes, grant_type)
         self.assert_valid_jwt_access_token(
             data['access_token'],
             self.user,
-            data['scope'].split(' '),
-            grant_type='password',
+            expected_scopes,
+            grant_type=grant_type,
             should_be_asymmetric_key=True
         )