pypomes-jwt 0.5.9__tar.gz → 0.6.1__tar.gz

{pypomes_jwt-0.5.9 → pypomes_jwt-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pypomes_jwt
-Version: 0.5.9
+Version: 0.6.1
 Summary: A collection of Python pomes, penyeach (JWT module)
 Project-URL: Homepage, https://github.com/TheWiseCoder/PyPomes-JWT
 Project-URL: Bug Tracker, https://github.com/TheWiseCoder/PyPomes-JWT/issues
@@ -10,6 +10,6 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.12
+Requires-Dist: cryptography>=44.0.1
 Requires-Dist: pyjwt>=2.10.1
-Requires-Dist: pyopenssl>=25.0.0
-Requires-Dist: pypomes-core>=1.7.1
+Requires-Dist: pypomes-core>=1.7.7

{pypomes_jwt-0.5.9 → pypomes_jwt-0.6.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pypomes_jwt"
-version = "0.5.9"
+version = "0.6.1"
 authors = [
   { name="GT Nunes", email="wisecoder01@gmail.com" }
 ]
@@ -20,8 +20,8 @@ classifiers = [
 ]
 dependencies = [
     "PyJWT>=2.10.1",
-    "PyOpenSSL>=25.0.0",
-    "pypomes_core>=1.7.1"
+    "cryptography>=44.0.1",
+    "pypomes_core>=1.7.7"
 ]
 
 [project.urls]

{pypomes_jwt-0.5.9 → pypomes_jwt-0.6.1}/src/pypomes_jwt/__init__.py

@@ -5,9 +5,9 @@ from .jwt_pomes import (
     JWT_ENDPOINT_URL,
     JWT_ACCESS_MAX_AGE, JWT_REFRESH_MAX_AGE,
     JWT_HS_SECRET_KEY, JWT_RSA_PRIVATE_KEY, JWT_RSA_PUBLIC_KEY,
-    jwt_needed, jwt_verify_request,
-    jwt_get_claims, jwt_get_token, jwt_get_token_data,
-    jwt_service, jwt_set_service_access, jwt_remove_service_access
+    jwt_needed, jwt_verify_request, jwt_service,
+    jwt_get_token_claims, jwt_get_token, jwt_get_token_data,
+    jwt_assert_access, jwt_set_access, jwt_remove_access
 )
 
 __all__ = [
@@ -17,9 +17,9 @@ __all__ = [
     "JWT_ENDPOINT_URL",
     "JWT_ACCESS_MAX_AGE", "JWT_REFRESH_MAX_AGE",
     "JWT_HS_SECRET_KEY", "JWT_RSA_PRIVATE_KEY", "JWT_RSA_PUBLIC_KEY",
-    "jwt_needed", "jwt_verify_request",
-    "jwt_get_claims", "jwt_get_token", "jwt_get_token_data",
-    "jwt_service", "jwt_set_service_access", "jwt_remove_service_access"
+    "jwt_needed", "jwt_verify_request", "jwt_service",
+    "jwt_get_token_claims", "jwt_get_token", "jwt_get_token_data",
+    "jwt_assert_access", "jwt_set_access", "jwt_remove_access"
 ]
 
 from importlib.metadata import version

{pypomes_jwt-0.5.9 → pypomes_jwt-0.6.1}/src/pypomes_jwt/jwt_data.py

@@ -1,5 +1,4 @@
 import jwt
-import math
 import requests
 from datetime import datetime, timedelta, timezone
 from jwt.exceptions import InvalidTokenError
@@ -18,26 +17,35 @@ class JwtData:
         - access_data: list with dictionaries holding the JWT token data:
          [
            {
-             "standard-claims": {            # standard claims
-               "exp": <timestamp>,           # expiration time
-               "nbt": <timestamp>,           # not before time
-               "iss": <string>,              # issuer
-               "aud": <string>,              # audience
-               "iat": <string>               # issued at
+             "reserved-claims": {        # reserved claims
+               "exp": <timestamp>,       # expiration time
+               "iat": <timestamp>        # issued at
+               "iss": <string>,          # issuer (for remote providers, URL to obtain and validate the access tokens)
+               "jti": <string>,          # JWT id
+               "sub": <string>           # subject (the account identification)
+               # not used:
+               # "aud": <string>         # audience
+               # "nbt": <timestamp>      # not before time
              },
-             "custom-claims": {              # custom claims
+             "public-claims": {
+               "birthdate": <string>,    # subject's birth date
+               "email": <string>,        # subject's email
+               "gender": <string>,       # subject's gender
+               "name": <string>,         # subject's name
+               "roles": <List[str]>      # subject roles
+             },
+             "custom-claims": {          # custom claims
                "<custom-claim-key-1>": "<custom-claim-value-1>",
                ...
                "<custom-claim-key-n>": "<custom-claim-value-n>"
              },
              "control-data": {               # control data
+               "remote-provider": <bool>,    # whether the JWT provider is a remote server
                "access-token": <jwt-token>,  # access token
                "algorithm": <string>,        # HS256, HS512, RSA256, RSA512
-               "request-timeout": <float>,   # in seconds - defaults to no timeout
+               "request-timeout": <int>,     # in seconds - defaults to no timeout
                "access-max-age": <int>,      # in seconds - defaults to JWT_ACCESS_MAX_AGE
                "refresh-exp": <timestamp>,   # expiration time for the refresh operation
-               "reference-url": <url>,       # URL to obtain and validate the access tokens
-               "remote-provider": <bool>,    # whether the JWT provider is a remote server
                "secret-key": <bytes>,        # HS secret key
                "private-key": <bytes>,       # RSA private key
                "public-key": <bytes>,        # RSA public key
@@ -54,6 +62,7 @@ class JwtData:
         self.access_data: list[dict[str, dict[str, Any]]] = []
 
     def add_access_data(self,
+                        account_id: str,
                         reference_url: str,
                         claims: dict[str, Any],
                         algorithm: Literal["HS256", "HS512", "RSA256", "RSA512"],
@@ -62,33 +71,37 @@ class JwtData:
                         secret_key: bytes,
                         private_key: bytes,
                         public_key: bytes,
-                        request_timeout: float,
+                        request_timeout: int,
                         remote_provider: bool,
                         logger: Logger = None) -> None:
         """
-        Add to storage the parameters needed to obtain and validate JWT tokens for *reference_url*.
+        Add to storage the parameters needed to produce and validate JWT tokens for *account_id*.
+
+        The parameter *claims* may contain public and custom claims. Currently, the public claims supported
+        are *birthdate*, *email*, *gender*, *name*, and *roles*. Everything else are considered to be custom
+        claims, and are sent to the remote JWT provided, if applicable.
 
         Presently, the *refresh_max_age* data is not relevant, as the authorization parameters in *claims*
         (typically, an acess-key/secret-key pair), have been previously validated elsewhere.
         This situation might change in the future.
 
-        :param reference_url: the reference URL
+        :param account_id: the account identification
+        :param reference_url: the reference URL (for remote providers, URL to obtain and validate the JWT tokens)
         :param claims: the JWT claimset, as key-value pairs
         :param algorithm: the algorithm used to sign the token with
-        :param access_max_age: token duration
-        :param refresh_max_age: duration for the refresh operation
+        :param access_max_age: token duration (in seconds)
+        :param refresh_max_age: duration for the refresh operation (in seconds)
         :param secret_key: secret key for HS authentication
         :param private_key: private key for RSA authentication
         :param public_key: public key for RSA authentication
-        :param request_timeout: timeout for the requests to the service URL
+        :param request_timeout: timeout for the requests to the reference URL
         :param remote_provider: whether the JWT provider is a remote server
         :param logger: optional logger
         """
         # Do the access data already exist ?
-        if not self.assert_access_data(reference_url=reference_url):
+        if not self.retrieve_access_data(account_id=account_id):
             # no, build control data
             control_data: dict[str, Any] = {
-                "reference-url": reference_url,
                 "algorithm": algorithm,
                 "access-max-age": access_max_age,
                 "request-timeout": request_timeout,
@@ -102,55 +115,59 @@ class JwtData:
                 control_data["public-key"] = public_key
 
             # build claims
+            reserved_claims: dict[str, Any] = {
+                "sub": account_id,
+                "iss": reference_url,
+                "exp": "<numeric-UTC-datetime>",
+                "iat": "<numeric-UTC-datetime>",
+                "jti": "<jwt-id",
+            }
             custom_claims: dict[str, Any] = {}
-            standard_claims: dict[str, Any] = {}
+            public_claims: dict[str, Any] = {}
             for key, value in claims.items():
-                if key in ["nbt", "iss", "aud", "iat"]:
-                    standard_claims[key] = value
+                if key in ["birthdate", "email", "gender", "name", "roles"]:
+                    public_claims[key] = value
                 else:
                     custom_claims[key] = value
-            standard_claims["exp"] = datetime(year=2000,
-                                              month=1,
-                                              day=1,
-                                              tzinfo=timezone.utc)
             # store access data
             item_data = {
                 "control-data": control_data,
-                "standard-claims": standard_claims,
+                "reserved-claims": reserved_claims,
+                "public-claims": public_claims,
                 "custom-claims": custom_claims
             }
             with self.access_lock:
                 self.access_data.append(item_data)
             if logger:
-                logger.debug(f"JWT data added for '{reference_url}': {item_data}")
+                logger.debug(f"JWT data added for '{account_id}': {item_data}")
         elif logger:
-            logger.warning(f"JWT data already exists for '{reference_url}'")
+            logger.warning(f"JWT data already exists for '{account_id}'")
 
     def remove_access_data(self,
-                           reference_url: str,
+                           account_id: str,
                            logger: Logger) -> None:
         """
-        Remove from storage the access data for *reference_url*.
+        Remove from storage the access data for *account_id*.
 
-        :param reference_url: the reference URL
+        :param account_id: the account identification
         :param logger: optional logger
         """
         # obtain the access data item in storage
-        item_data: dict[str, dict[str, Any]] = self.retrieve_access_data(reference_url=reference_url,
+        item_data: dict[str, dict[str, Any]] = self.retrieve_access_data(account_id=account_id,
                                                                          logger=logger)
         if item_data:
             with self.access_lock:
                 self.access_data.remove(item_data)
             if logger:
-                logger.debug(f"Removed JWT data for '{reference_url}'")
+                logger.debug(f"Removed JWT data for '{account_id}'")
         elif logger:
-            logger.warning(f"No JWT data found for '{reference_url}'")
+            logger.warning(f"No JWT data found for '{account_id}'")
 
     def get_token_data(self,
-                       reference_url: str,
+                       account_id: str,
                        logger: Logger = None) -> dict[str, Any]:
         """
-        Obtain and return the JWT token for *reference_url*, along with its duration.
+        Obtain and return the JWT token for *account_id*, along with its duration.
 
         Structure of the return data:
         {
@@ -158,9 +175,9 @@ class JwtData:
           "expires_in": <seconds-to-expiration>
         }
 
-        :param reference_url: the reference URL for obtaining JWT tokens
+        :param account_id: the account identification
         :param logger: optional logger
-        :return: the JWT token data, or 'None' if error
+        :return: the JWT token data, or *None* if error
         :raises InvalidTokenError: token is invalid
         :raises InvalidKeyError: authentication key is not in the proper format
         :raises ExpiredSignatureError: token and refresh period have expired
@@ -171,69 +188,63 @@ class JwtData:
         :raises InvalidIssuerError: 'iss' claim does not match the expected issuer
         :raises InvalidIssuedAtError: 'iat' claim is non-numeric
         :raises MissingRequiredClaimError: a required claim is not contained in the claimset
-        :raises RuntimeError: access data not found for the given *reference_url*, or
+        :raises RuntimeError: access data not found for the given *account_id*, or
                               the remote JWT provider failed to return a token
         """
         # declare the return variable
         result: dict[str, Any]
 
         # obtain the item in storage
-        item_data: dict[str, Any] = self.retrieve_access_data(reference_url=reference_url,
+        item_data: dict[str, Any] = self.retrieve_access_data(account_id=account_id,
                                                               logger=logger)
         # was the JWT data obtained ?
         if item_data:
             # yes, proceed
             control_data: dict[str, Any] = item_data.get("control-data")
+            reserved_claims: dict[str, Any] = item_data.get("reserved-claims")
             custom_claims: dict[str, Any] = item_data.get("custom-claims")
-            standard_claims: dict[str, Any] = item_data.get("standard-claims")
-            just_now: datetime = datetime.now(tz=timezone.utc)
-
-            # is the current token still valid ?
-            if just_now > standard_claims.get("exp"):
-                # no, obtain a new token
-                reference_url: str = control_data.get("reference-url")
-                claims: dict[str, Any] = standard_claims.copy()
-                claims.update(custom_claims)
+            just_now: int = int(datetime.now(tz=timezone.utc).timestamp())
 
+            # obtain a new token, if the current token has expired
+            if just_now > reserved_claims.get("exp"):
                 # where is the locus of the JWT service provider ?
                 if control_data.get("remote-provider"):
                     # JWT service is being provided by a remote server
-                    if reference_url.find("?") > 0:
-                        reference_url = reference_url[:reference_url.index("?")]
-                    claims.pop("exp", None)
                     errors: list[str] = []
                     result = jwt_request_token(errors=errors,
-                                               reference_url=reference_url,
-                                               claims=claims,
+                                               reference_url=reserved_claims.get("iss"),
+                                               claims=custom_claims,
                                                timeout=control_data.get("request-timeout"),
                                                logger=logger)
                     if result:
                         with self.access_lock:
                             control_data["access-token"] = result.get("access_token")
                             duration: int = result.get("expires_in")
-                            standard_claims["exp"] = just_now + timedelta(seconds=duration)
+                            reserved_claims["exp"] = just_now + duration
                     else:
                         raise RuntimeError(" - ".join(errors))
                 else:
                     # JWT service is being provided locally
-                    claims["exp"] = just_now + timedelta(seconds=control_data.get("access-max-age") + 10)
+                    reserved_claims["iat"] = just_now
+                    reserved_claims["exp"] = just_now + control_data.get("access-max-age")
+                    claims: dict[str, Any] = item_data.get("public-claims").copy()
+                    claims.update(reserved_claims)
+                    claims.update(custom_claims)
                     # may raise an exception
                     token: str = jwt.encode(payload=claims,
                                             key=control_data.get("secret-key") or control_data.get("private-key"),
                                             algorithm=control_data.get("algorithm"))
                     with self.access_lock:
                         control_data["access-token"] = token
-                        standard_claims["exp"] = claims.get("exp")
 
             # return the token
-            diff: timedelta = standard_claims.get("exp") - just_now - timedelta(seconds=10)
             result = {
                 "access_token": control_data.get("access-token"),
-                "expires_in": math.trunc(diff.total_seconds())
+                "expires_in": reserved_claims.get("exp") - just_now
             }
         else:
             # JWT access data not found
-            err_msg: str = f"No JWT access data found for '{reference_url}'"
+            err_msg: str = f"No JWT access data found for '{account_id}'"
             if logger:
                 logger.error(err_msg)
             raise RuntimeError(err_msg)
@@ -275,50 +286,14 @@ class JwtData:
 
         return result
 
-    def assert_access_data(self,
-                           reference_url: str) -> bool:
-        # noinspection HttpUrlsUsage
-        """
-        Assert whether access data exists for *reference_url*.
-
-        For the purpose of locating access data, Protocol indication in *reference_url*
-        (typically, *http://* or *https://*), is disregarded. This guarantees
-        that processing herein will not be affected by in-transit protocol changes.
-
-        :param reference_url: the reference URL for obtaining JWT tokens
-        :return: *True" is access data is in storage, *False* otherwise
-        """
-        # initialize the return variable
-        result: bool = False
-
-        # disregard protocol
-        if reference_url.find("://") > 0:
-            reference_url = reference_url[reference_url.index("://")+3:]
-
-        # assert the data
-        with self.access_lock:
-            for item_data in self.access_data:
-                item_url: str = item_data.get("control-data").get("reference-url")
-                if item_url.find("://") > 0:
-                    item_url = item_url[item_url.index("://")+3:]
-                if reference_url == item_url:
-                    result = True
-                    break
-        
-        return result
-
     def retrieve_access_data(self,
-                             reference_url: str,
+                             account_id: str,
                              logger: Logger = None) -> dict[str, dict[str, Any]]:
         # noinspection HttpUrlsUsage
         """
-        Retrieve and return the access data in storage for *reference_url*.
-
-        For the purpose of locating access data, Protocol indication in *reference_url*
-        (typically, *http://* or *https://*), is disregarded. This guarantees
-        that processing herein will not be affected by in-transit protocol changes.
+        Retrieve and return the access data in storage for *account_id*.
 
-        :param reference_url: the reference URL for obtaining JWT tokens
+        :param account_id: the account identification
         :param logger: optional logger
         :return: the corresponding item in storage, or *None* if not found
         """
@@ -326,19 +301,11 @@ class JwtData:
         result: dict[str, dict[str, Any]] | None = None
     
         if logger:
-            logger.debug(f"Retrieve access data for reference URL '{reference_url}'")
-
-        # disregard protocol
-        if reference_url.find("://") > 0:
-            reference_url = reference_url[reference_url.index("://")+3:]
-
+            logger.debug(f"Retrieve access data for account id '{account_id}'")
         # retrieve the data
         with self.access_lock:
             for item_data in self.access_data:
-                item_url: str = item_data.get("control-data").get("reference-url")
-                if item_url.find("://") > 0:
-                    item_url = item_url[item_url.index("://")+3:]
-                if reference_url == item_url:
+                if account_id == item_data.get("reserved-claims").get("sub"):
                     result = item_data
                     break
         if logger:
@@ -350,7 +317,7 @@ class JwtData:
 def jwt_request_token(errors: list[str],
                       reference_url: str,
                       claims: dict[str, Any],
-                      timeout: float = None,
+                      timeout: int = None,
                       logger: Logger = None) -> dict[str, Any]:
     """
     Obtain and return the JWT token associated with *reference_url*, along with its duration.
@@ -389,7 +356,7 @@ def jwt_request_token(errors: list[str],
             logger.debug(f"JWT token obtained: {result}")
     else:
         # no, report the problem
-        err_msg: str = f"POST request of '{reference_url}' failed: {response.reason}"
+        err_msg: str = f"POST request to '{reference_url}' failed: {response.reason}"
         if response.text:
             err_msg += f" - {response.text}"
         if logger:
@@ -418,7 +385,9 @@ def jwt_validate_token(token: str,
     :raises InvalidSignatureError: signature does not match the one provided as part of the token
     """
     if logger:
-        logger.debug(msg=f"Verify request for JWT token '{token}'")
+        logger.debug(msg=f"Validate JWT token '{token}'")
     jwt.decode(jwt=token,
                key=key,
                algorithms=[algorithm])
+    if logger:
+        logger.debug(msg=f"Token '{token}' is valid")

{pypomes_jwt-0.5.9 → pypomes_jwt-0.6.1}/src/pypomes_jwt/jwt_pomes.py

@@ -1,7 +1,9 @@
 import contextlib
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey, RSAPublicKey
 from flask import Request, Response, request, jsonify
 from logging import Logger
-from OpenSSL import crypto
 from pypomes_core import APP_PREFIX, env_get_str, env_get_bytes, env_get_int
 from secrets import token_bytes
 from typing import Any, Final, Literal
@@ -15,18 +17,24 @@ JWT_ACCESS_MAX_AGE: Final[int] = env_get_int(key=f"{APP_PREFIX}_JWT_ACCESS_MAX_A
 JWT_REFRESH_MAX_AGE: Final[int] = env_get_int(key=f"{APP_PREFIX}_JWT_REFRESH_MAX_AGE",
                                               def_value=43200)
 JWT_HS_SECRET_KEY: Final[bytes] = env_get_bytes(key=f"{APP_PREFIX}_JWT_HS_SECRET_KEY",
-                                                def_value=token_bytes(32))
-# must invoke 'jwt_service()' below
+                                                def_value=token_bytes(nbytes=32))
+# the endpoint must invoke 'jwt_service()' below
 JWT_ENDPOINT_URL: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_ENDPOINT_URL")
 
-__priv_key: bytes = env_get_bytes(key=f"{APP_PREFIX}_JWT_RSA_PRIVATE_KEY")
-__pub_key: bytes = env_get_bytes(key=f"{APP_PREFIX}_JWT_RSA_PUBLIC_KEY")
-if not __priv_key or not __pub_key:
-    pk = crypto.PKey()
-    __priv_key = crypto.dump_privatekey(crypto.FILETYPE_PEM, pk)
-    __pub_key = crypto.dump_publickey(crypto.FILETYPE_PEM, pk)
-JWT_RSA_PRIVATE_KEY: Final[bytes] = __priv_key
-JWT_RSA_PUBLIC_KEY: Final[bytes] = __pub_key
+# obtain a RSA private/public key pair
+__priv_bytes: bytes = env_get_bytes(key=f"{APP_PREFIX}_JWT_RSA_PRIVATE_KEY")
+__pub_bytes: bytes = env_get_bytes(key=f"{APP_PREFIX}_JWT_RSA_PUBLIC_KEY")
+if not __priv_bytes or not __pub_bytes:
+    __priv_key: RSAPrivateKey = rsa.generate_private_key(public_exponent=65537,
+                                                         key_size=2048)
+    __priv_bytes = __priv_key.private_bytes(encoding=serialization.Encoding.PEM,
+                                            format=serialization.PrivateFormat.PKCS8,
+                                            encryption_algorithm=serialization.NoEncryption())
+    __pub_key: RSAPublicKey = __priv_key.public_key()
+    __pub_bytes = __pub_key.public_bytes(encoding=serialization.Encoding.PEM,
+                                         format=serialization.PublicFormat.SubjectPublicKeyInfo)
+JWT_RSA_PRIVATE_KEY: Final[bytes] = __priv_bytes
+JWT_RSA_PUBLIC_KEY: Final[bytes] = __pub_bytes
 
 # the JWT data object
 __jwt_data: JwtData = JwtData()
@@ -49,21 +57,33 @@ def jwt_needed(func: callable) -> callable:
     return wrapper
 
 
-def jwt_set_service_access(reference_url: str,
-                           claims: dict[str, Any],
-                           algorithm: Literal["HS256", "HS512", "RSA256", "RSA512"] = JWT_DEFAULT_ALGORITHM,
-                           access_max_age: int = JWT_ACCESS_MAX_AGE,
-                           refresh_max_age: int = JWT_REFRESH_MAX_AGE,
-                           secret_key: bytes = JWT_HS_SECRET_KEY,
-                           private_key: bytes = JWT_RSA_PRIVATE_KEY,
-                           public_key: bytes = JWT_RSA_PUBLIC_KEY,
-                           request_timeout: int = None,
-                           remote_provider: bool = True,
-                           logger: Logger = None) -> None:
+def jwt_assert_access(account_id: str) -> bool:
     """
-    Set the data needed to obtain JWT tokens from *reference_url*.
+    Determine whether access for *ccount_id* has been established.
 
-    :param reference_url: the reference URL
+    :param account_id: the account identification
+    :return: *True* if access data exists for *account_id*, *False* otherwise
+    """
+    return __jwt_data.retrieve_access_data(account_id=account_id) is not None
+
+
+def jwt_set_access(account_id: str,
+                   reference_url: str,
+                   claims: dict[str, Any],
+                   algorithm: Literal["HS256", "HS512", "RSA256", "RSA512"] = JWT_DEFAULT_ALGORITHM,
+                   access_max_age: int = JWT_ACCESS_MAX_AGE,
+                   refresh_max_age: int = JWT_REFRESH_MAX_AGE,
+                   secret_key: bytes = JWT_HS_SECRET_KEY,
+                   private_key: bytes = JWT_RSA_PRIVATE_KEY,
+                   public_key: bytes = JWT_RSA_PUBLIC_KEY,
+                   request_timeout: int = None,
+                   remote_provider: bool = True,
+                   logger: Logger = None) -> None:
+    """
+    Set the data needed to obtain JWT tokens for *account_id*.
+
+    :param account_id: the account identification
+    :param reference_url: the reference URL (for remote providers, URL to obtain and validate the JWT tokens)
     :param claims: the JWT claimset, as key-value pairs
     :param algorithm: the authentication type
     :param access_max_age: token duration, in seconds
@@ -71,23 +91,24 @@ def jwt_set_service_access(reference_url: str,
     :param secret_key: secret key for HS authentication
     :param private_key: private key for RSA authentication
     :param public_key: public key for RSA authentication
-    :param request_timeout: timeout for the requests to the service URL
+    :param request_timeout: timeout for the requests to the reference URL
     :param remote_provider: whether the JWT provider is a remote server
     :param logger: optional logger
     """
     if logger:
-        logger.debug(msg=f"Register access data for '{reference_url}'")
-    # extract the extra claims
+        logger.debug(msg=f"Register access data for '{account_id}'")
+
+    # extract the claims provided in the reference URL's query string
     pos: int = reference_url.find("?")
     if pos > 0:
-        if remote_provider:
-            params: list[str] = reference_url[pos+1:].split(sep="&")
-            for param in params:
-                claims[param.split("=")[0]] = param.split("=")[1]
+        params: list[str] = reference_url[pos+1:].split(sep="&")
+        for param in params:
+            claims[param.split("=")[0]] = param.split("=")[1]
         reference_url = reference_url[:pos]
 
     # register the JWT service
-    __jwt_data.add_access_data(reference_url=reference_url,
+    __jwt_data.add_access_data(account_id=account_id,
+                               reference_url=reference_url,
                                claims=claims,
                                algorithm=algorithm,
                                access_max_age=access_max_age,
@@ -100,40 +121,40 @@ def jwt_set_service_access(reference_url: str,
                                logger=logger)
 
 
-def jwt_remove_service_access(reference_url: str,
-                              logger: Logger = None) -> None:
+def jwt_remove_access(account_id: str,
+                      logger: Logger = None) -> None:
     """
-    Remove from storage the JWT access data for *reference_url*.
+    Remove from storage the JWT access data for *account_id*.
 
-    :param reference_url: the reference URL
+    :param account_id: the account identification
     :param logger: optional logger
     """
     if logger:
-        logger.debug(msg=f"Remove access data for '{reference_url}'")
+        logger.debug(msg=f"Remove access data for '{account_id}'")
 
-    __jwt_data.remove_access_data(reference_url=reference_url,
+    __jwt_data.remove_access_data(account_id=account_id,
                                   logger=logger)
 
 
 def jwt_get_token(errors: list[str],
-                  reference_url: str,
+                  account_id: str,
                   logger: Logger = None) -> str:
     """
-    Obtain and return a JWT token from *reference_url*.
+    Obtain and return a JWT token for *account_id*.
 
     :param errors: incidental error messages
-    :param reference_url: the reference URL
+    :param account_id: the account identification
     :param logger: optional logger
-    :return: the JWT token, or 'None' if an error ocurred
+    :return: the JWT token, or *None* if an error ocurred
     """
     # inicialize the return variable
     result: str | None = None
 
     if logger:
-        logger.debug(msg=f"Obtain a JWT token for '{reference_url}'")
+        logger.debug(msg=f"Obtain a JWT token for '{account_id}'")
 
     try:
-        token_data: dict[str, Any] = __jwt_data.get_token_data(reference_url=reference_url,
+        token_data: dict[str, Any] = __jwt_data.get_token_data(account_id=account_id,
                                                                logger=logger)
         result = token_data.get("access_token")
         if logger:
@@ -147,10 +168,10 @@ def jwt_get_token(errors: list[str],
 
 
 def jwt_get_token_data(errors: list[str],
-                       reference_url: str,
+                       account_id: str,
                        logger: Logger = None) -> dict[str, Any]:
     """
-    Obtain and return the JWT token associated with *reference_url*, along with its duration.
+    Obtain and return the JWT token associated with *account_id*, along with its duration.
 
     Structure of the return data:
     {
@@ -159,17 +180,17 @@ def jwt_get_token_data(errors: list[str],
     }
 
     :param errors: incidental error messages
-    :param reference_url: the reference URL for obtaining JWT tokens
+    :param account_id: the account identification
     :param logger: optional logger
-    :return: the JWT token data, or 'None' if error
+    :return: the JWT token data, or *None* if error
     """
     # inicialize the return variable
     result: dict[str, Any] | None = None
 
     if logger:
-        logger.debug(msg=f"Retrieve JWT token data for '{reference_url}'")
+        logger.debug(msg=f"Retrieve JWT token data for '{account_id}'")
     try:
-        result = __jwt_data.get_token_data(reference_url=reference_url,
+        result = __jwt_data.get_token_data(account_id=account_id,
                                            logger=logger)
         if logger:
             logger.debug(msg=f"Data is '{result}'")
@@ -181,11 +202,11 @@ def jwt_get_token_data(errors: list[str],
     return result
 
 
-def jwt_get_claims(errors: list[str],
-                   token: str,
-                   logger: Logger = None) -> dict[str, Any]:
+def jwt_get_token_claims(errors: list[str],
+                         token: str,
+                         logger: Logger = None) -> dict[str, Any]:
     """
-    Obtain and return the claimset of a JWT *token*.
+    Obtain and return the claims set of a JWT *token*.
 
     :param errors: incidental error messages
     :param token: the token to be inspected for claims
@@ -252,20 +273,22 @@ def jwt_verify_request(request: Request,
     return result
 
 
-def jwt_service(reference_url: str = None,
+def jwt_service(account_id: str = None,
                 service_params: dict[str, Any] = None,
                 logger: Logger = None) -> Response:
     """
     Entry point for obtaining JWT tokens.
 
-    In order to be serviced, the invoker must send, as parameter *service_params* or in the body of the request,
-    a JSON containing:
+    In order to be serviced, the invoker must send, as parameter *service_params* or in the body of the request:
     {
-      "reference-url": "<url>",                             - the JWT reference URL (if not as parameter)
-      "<custom-claim-key-1>": "<custom-claim-value-1>",     - the registered custom claims
+      "account-id": "<string>"                              - required account identification
+      "<custom-claim-key-1>": "<custom-claim-value-1>",     - optional custom claims
       ...
       "<custom-claim-key-n>": "<custom-claim-value-n>"
     }
+    If provided, the additional custom claims will be sent to the remote provider, if applicable
+    (custom claims currently registered for the account may be overridden).
+
 
     Structure of the return data:
     {
@@ -273,7 +296,7 @@ def jwt_service(reference_url: str = None,
       "expires_in": <seconds-to-expiration>
     }
 
-    :param reference_url: the JWT reference URL, alternatively passed in JSON
+    :param account_id: the account identification, alternatively passed in JSON
     :param service_params: the optional JSON containing the request parameters (defaults to JSON in body)
     :param logger: optional logger
     :return: the requested JWT token, along with its duration.
@@ -287,43 +310,39 @@ def jwt_service(reference_url: str = None,
             msg += f" from '{request.base_url}'"
         logger.debug(msg=msg)
 
-    # obtain the parameters
+    # retrieve the parameters
     # noinspection PyUnusedLocal
     params: dict[str, Any] = service_params or {}
     if not params:
         with contextlib.suppress(Exception):
             params = request.get_json()
+    if not account_id:
+        account_id = params.get("account-id")
 
-    # validate the parameters
-    valid: bool = False
-    if not reference_url:
-        reference_url = params.get("reference-url")
-    if reference_url:
+    # has the account been identified ?
+    if account_id:
+        # yes, proceed
         if logger:
-            logger.debug(msg=f"Reference URL is '{reference_url}'")
-        item_data: dict[str, dict[str, Any]] = __jwt_data.retrieve_access_data(reference_url=reference_url,
-                                                                               logger=logger)
-        if item_data:
-            valid = True
-            custom_claims: dict[str, Any] = item_data.get("custom-claims")
-            for key, value in custom_claims.items():
-                if key not in params or params.get(key) != value:
-                    valid = False
-                    break
-
-    # obtain the token data
-    if valid:
+            logger.debug(msg=f"Account identification is '{account_id}'")
+        item_data: dict[str, dict[str, Any]] = __jwt_data.retrieve_access_data(account_id=account_id,
+                                                                               logger=logger) or {}
+        custom_claims: dict[str, Any] = item_data.get("custom-claims").copy()
+        for key, value in params.items():
+            custom_claims[key] = value
+
+        # obtain the token data
         try:
-            token_data: dict[str, Any] = __jwt_data.get_token_data(reference_url=reference_url,
+            token_data: dict[str, Any] = __jwt_data.get_token_data(account_id=account_id,
                                                                    logger=logger)
             result = jsonify(token_data)
         except Exception as e:
-            # validation failed
+            # token validation failed
             if logger:
                 logger.error(msg=str(e))
             result = Response(response=str(e),
                               status=401)
     else:
+        # no, report the problem
         if logger:
             logger.debug(msg=f"Invalid parameters {service_params}")
         result = Response(response="Invalid parameters",