squash! add docstring and update changelog

CHANGELOG.rst

@@ -15,6 +15,11 @@ Unreleased
 [8.9.2] - 2023-08-31
 --------------------
 
+Added
+~~~~~
+* PR#354: Implemented `verify_jwk_signature_using_keyset` function.
+  This function allows for easy verification of JSON Web Key (JWK) signatures using a provided keyset.
+
 Fixed
 ~~~~~
 * Fixes exceptional case where JwtAuthentication should not CSRF protect a request that has both a JWT token in the authorization header and a JWT cookie, since the cookie should be ignored.

edx_rest_framework_extensions/auth/jwt/decoder.py

@@ -252,12 +252,37 @@ def _verify_jwt_signature(token, jwt_issuer, decode_symmetric_token):
 
 def verify_jwk_signature_using_keyset(token, key_set, aud=None, iss=None, verify_signature=True, verify_exp=True):
     """
-    Verifies the JWS using the provided keyset.
-    It loops through the available keys in the keyset
-    to find that if there is any key which can be used to verify
-    the signature.
-    The audience and issuer arguments will be verified if they are passed
-    while calling the method.
+    Verifies the signature of a JSON Web Token (JWT) using a provided JSON Web Key (PyJWK) key set.
+
+    Args:
+        token (str): The JWT to be verified.
+        key_set (list -> PyJWK): A list containing PyJWKs (JSON Web Keys)
+            for signature verification.
+        aud (str or None): The expected "aud" (audience) claim in the JWT.
+            If provided, the JWT's "aud" claim must match this value for
+            the verification to succeed.
+        iss (str or None): The expected "iss" (issuer) claim in the JWT.
+            If provided, the JWT's "iss" claim must match this value for
+            the verification to succeed.
+        verify_signature (bool): Whether to verify the JWT's digital signature.
+            Set to False if you want to skip signature verification
+            (e.g., if the JWT is already pre-verified).
+        verify_exp (bool): Whether to verify the JWT's expiration time ("exp" claim).
+            Set to False if you want to skip expiration time verification.
+
+    Returns:
+        data (dict): Decoded JWT.
+
+    Raises:
+        ValueError: If the token is not a valid JWT or if the key_set is empty
+            or improperly formatted.
+        jwt.ExpiredSignatureError: If the JWT has expired and verify_exp
+            is set to True.
+        jwt.InvalidIssuerError: If the "iss" claim does not match the expected
+            issuer and iss is provided.
+        jwt.InvalidAudienceError: If the "aud" claim does not match the expected
+            audience and aud is provided.
+        jwt.DecodeError: If the JWT decoding fails for any reason.
     """
     options = {
         'verify_signature': verify_signature,