update auth docs

1. clarify asymmetric jwt decision.
2. move relevant auth docs to edx-drf-extensions and
edx-rest-api-client.

openedx/core/djangoapps/oauth_dispatch/docs/README.rst

@@ -9,9 +9,10 @@ The OAuth Dispatch app is the topmost interface to `OAuth2`_ provider functional
 Background
 ----------
 
-This section provides a few highlights on the code to provide a high-level perspective on where different aspects of the OAuth2 flow reside. For additional information, see `Open edX Authentication`_.
+This section provides a few highlights on the code to provide a high-level perspective on where different aspects of the OAuth2 flow reside. For additional information, see `Open edX Authentication and Authorization`_.
+
+.. _Open edX Authentication and Authorization: https://openedx.atlassian.net/wiki/spaces/PLAT/pages/160912480/Open+edX+Authentication
 
-.. _Open edX Authentication: https://openedx.atlassian.net/wiki/spaces/PLAT/pages/160912480/Open+edX+Authentication
 
 Provider code
 ~~~~~~~~~~~~~
@@ -36,42 +37,14 @@ Provider code
 Clients & REST API Clients code
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* edX services, including LMS, use the edx-rest-api-client_ library to make OAuth2 client requests and REST API calls.
-
-  * Built on top of slumber_, the edx-rest-api-client_ provides a utility to retrieve an access token from the LMS. Its Auth_ classes create appropriate HTTP Authorization headers with *Bearer* or *JWT* insertions as needed.
-
-  * It makes use of the PyJWT_ library for cryptographically creating JWT tokens.
-
-    * **Note:** Creation of JWT tokens in our system should only be done by the OAuth Provider. This will break once we use *asymmetric* signing keys, for which remote services will not have the private keys.
-
-.. _edx-rest-api-client: https://github.com/edx/edx-rest-api-client
-.. _slumber: https://github.com/samgiles/slumber
-.. _Auth: https://github.com/edx/edx-rest-api-client/blob/master/edx_rest_api_client/auth.py
-.. _PyJWT: https://github.com/jpadilla/pyjwt
+* Open edX services, including LMS, use the OAuthAPIClient class from the edx-rest-api-client_ library to make OAuth2 client requests and REST API calls.
 
 Authentication by REST endpoints
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * Recently created edX REST endpoints use the `Django Rest Framework (DRF)`_. The REST endpoint declares which type(s) of authentication it supports or defaults to the *DEFAULT_AUTHENTICATION_CLASSES* value in DRF's *REST_FRAMEWORK* Django setting.
 
-* edX REST endpoints that support JWTs as access tokens declare the custom edX JwtAuthentication_ class in its DRF authentication_classes_ scheme.
-
-  * JwtAuthentication_ is implemented in the edx-drf-extensions_ library.
-
-  * JwtAuthentication_ extends the JSONWebTokenAuthentication_ class implemented in the django-rest-framework-jwt_ library.
-
-  * JwtAuthentication_ is used to authenticate an API request only if it is listed in the endpoint's authentication_classes_ and the request's Authorization header specifies "JWT" instead of "Bearer".
-
-  * **Note:** The Credentials service has its own implementation of JwtAuthentication_ and should be converted to use the common implementation in edx-drf-extensions_.
-
-* **Note:** There is also an auth-backends_ repo that should eventually go away once Open ID Connect is no longer used. The only remaining user of its EdXOpenIdConnect_ class is the edx-analytics-dashboard_.
+* Open edX REST endpoints that support JWTs as access tokens use JwtAuthentication_ as implemented by the edx-drf-extensions library.
 
 .. _Django Rest Framework (DRF): https://github.com/encode/django-rest-framework
-.. _JwtAuthentication: https://github.com/edx/edx-drf-extensions/blob/4569b9bf7e54a917d4acdd545b10c058c960dd1a/edx_rest_framework_extensions/auth/jwt/authentication.py#L17
-.. _authentication_classes: http://www.django-rest-framework.org/api-guide/authentication/#setting-the-authentication-scheme
-.. _edx-drf-extensions: https://github.com/edx/edx-drf-extensions
-.. _django-rest-framework-jwt: https://github.com/GetBlimp/django-rest-framework-jwt
-.. _JSONWebTokenAuthentication: https://github.com/GetBlimp/django-rest-framework-jwt/blob/0a0bd402ec21fd6b9a5f715d114411836fbb2923/rest_framework_jwt/authentication.py#L71
-.. _auth-backends: https://github.com/edx/auth-backends
-.. _EdXOpenIdConnect: https://github.com/edx/auth-backends/blob/31c944289da0eec7148279d7ada61553dbb61f9e/auth_backends/backends.py#L63
-.. _edx-analytics-dashboard: https://github.com/edx/edx-analytics-dashboard
+.. _JwtAuthentication: https://github.com/edx/edx-drf-extensions/blob/master/edx_rest_framework_extensions/auth/jwt/README.rst

openedx/core/djangoapps/oauth_dispatch/docs/decisions/0008-use-asymmetric-jwts.rst

@@ -34,7 +34,7 @@ allow a Client to forward a verifiable token to other Clients.
 
 Looking forward, we want to support Single Page Apps (a.k.a., Microfronteds), where users can seamlessly
 traverse from one microfronted to another and access APIs on various backends. This *Single Sign On*
-capability cannot be achieved unless verifiable tokens can be forwarded from one service to another. 
+capability cannot be achieved unless verifiable tokens can be forwarded from one service to another.
 
 Decisions
 ---------
@@ -45,6 +45,7 @@ Asymmetric JWTs
 We will introduce identified "asymmetric" cryptographic keys for signing JWTs. The OAuth Provider will
 be the only service configured with the aymmetric keypair, including its Private and Public key portions.
 All other OAuth Clients will be configured with only the Public key portion of the asymmetric key pair.
+This will ultimately replace all uses of "symmetric" keys for signing JWTs.
 
 "kid" Key Identifier
 ~~~~~~~~~~~~~~~~~~~~
@@ -183,3 +184,7 @@ Consequences
   asymmetric JWTs introduces yet another. The sooner we upgrade our dependent services
   and remove these other mechanisms, the better - in the meantime, we are increasing
   code complexity.
+
+* All uses of "symmetric" keys used for signing JWTs should be marked as deprecated
+  until they can be removed. Pointing to this decision record from other code will
+  quickly explain and help identify outstanding work for removal.