oauth2-cli-auth 1.6.2__tar.gz → 3.0.0__tar.gz

{oauth2_cli_auth-1.6.2 → oauth2_cli_auth-3.0.0}/PKG-INFO

@@ -1,11 +1,12 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: oauth2-cli-auth
-Version: 1.6.2
+Version: 3.0.0
 Summary: Authenticate against OAuth2 Provider in Python CLIs
 License: MIT
+License-File: LICENSE
 Author: Timo Reymann
 Author-email: mail@timo-reymann.de
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Environment :: MacOS X
@@ -15,11 +16,12 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: POSIX
 Classifier: Operating System :: Unix
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Project-URL: Bug Tracker, https://github.com/timo-reymann/python-oauth2-cli-auth/issues
 Project-URL: Repository, https://github.com/timo-reymann/python-oauth2-cli-auth
 Description-Content-Type: text/markdown

{oauth2_cli_auth-1.6.2 → oauth2_cli_auth-3.0.0}/oauth2_cli_auth/__init__.py

@@ -3,5 +3,5 @@ Authenticate against OAuth2 Provider in Python CLIs
 """
 from oauth2_cli_auth.__version__ import __version__
 from oauth2_cli_auth.http_server import OAuthCallbackHttpServer
-from oauth2_cli_auth.code_grant import OAuth2ClientInfo, exchange_code_for_access_token, get_auth_url, open_browser, load_oidc_config
+from oauth2_cli_auth.code_grant import OAuth2ClientInfo, refresh_access_token, exchange_code_for_access_token, exchange_code_for_response, get_auth_url, generate_pkce_pair, open_browser, load_oidc_config
 from oauth2_cli_auth.simplified_flow import get_access_token_with_browser_open

oauth2_cli_auth-3.0.0/oauth2_cli_auth/__version__.py

@@ -0,0 +1 @@
+__version__ = "3.0.0"

{oauth2_cli_auth-1.6.2 → oauth2_cli_auth-3.0.0}/oauth2_cli_auth/code_grant.py

@@ -2,6 +2,8 @@
 Functionality to work with OAuth2 code grant
 """
 import base64
+import hashlib
+import secrets
 import urllib.parse
 import urllib.request
 import webbrowser
@@ -26,11 +28,14 @@ class OAuth2ClientInfo:
     client_id: str
     """Id of the client to request for"""
 
+    client_secret: str | None
+    """Secret of the client to request for"""
+
     scopes: list[str]
     """List of scopes to request"""
 
     @staticmethod
-    def from_oidc_endpoint(oidc_config_endpoint: str, client_id: str, scopes: list[str]) -> "OAuth2ClientInfo":
+    def from_oidc_endpoint(oidc_config_endpoint: str, client_id: str, scopes: list[str] = [], client_secret: str | None = None) -> "OAuth2ClientInfo":
         """
         Create client information object from well known endpoint in format as specified in
         https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
@@ -45,6 +50,7 @@ class OAuth2ClientInfo:
             authorization_url=config.get("authorization_endpoint"),
             token_url=config.get("token_endpoint"),
             client_id=client_id,
+            client_secret=client_secret,
             scopes=scopes,
         )
 
@@ -72,25 +78,47 @@ def open_browser(url: str, print_open_browser_instruction: Optional[Callable[[st
     webbrowser.open(url)
 
 
-def get_auth_url(client_info: OAuth2ClientInfo, redirect_uri: str) -> str:
+def generate_pkce_pair() -> tuple[str, str]:
+    """
+    Generate a PKCE (RFC 7636) code verifier and its S256 code challenge
+
+    :return: Tuple of (code_verifier, code_challenge)
+    """
+    verifier = secrets.token_urlsafe(64)
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    return verifier, base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+
+def get_auth_url(client_info: OAuth2ClientInfo, redirect_uri: str, state: Optional[str] = None,
+                 code_challenge: Optional[str] = None) -> str:
     """
     Build authorization url for browser
 
     :param client_info: Info about oauth2 client
     :param redirect_uri: Callback URL
+    :param state: Opaque value to protect the callback against forged requests. Providers echo it back on the redirect.
+    :param code_challenge: PKCE S256 code challenge, see generate_pkce_pair
     :return: Ready to use URL
     """
-    return (f"{client_info.authorization_url}"
-            f"?client_id={client_info.client_id}"
-            f"&redirect_uri={redirect_uri}"
-            f"&scope={'+'.join(client_info.scopes)}"
-            f"&response_type=code")
+    params = {
+        "client_id": client_info.client_id,
+        "redirect_uri": redirect_uri,
+        "scope": " ".join(client_info.scopes),
+        "response_type": "code",
+    }
+    if state is not None:
+        params["state"] = state
+    if code_challenge is not None:
+        params["code_challenge"] = code_challenge
+        params["code_challenge_method"] = "S256"
+    return f"{client_info.authorization_url}?{urllib.parse.urlencode(params)}"
 
 
 def exchange_code_for_response(
         client_info: OAuth2ClientInfo,
         redirect_uri: str,
         code: str,
+        code_verifier: Optional[str] = None,
 ) -> dict:
     """
     Exchange a code for an access token using the endpoints from client info and return the entire response
@@ -98,11 +126,12 @@ def exchange_code_for_response(
     :param client_info: Info about oauth2 client
     :param redirect_uri: Callback URL
     :param code: Code to redeem
+    :param code_verifier: PKCE code verifier matching the code challenge of the authorization request
     :return: Response from OAuth2 endpoint
     """
     headers = {
         "Content-Type": "application/x-www-form-urlencoded",
-        "Authorization": "Basic " + base64.b64encode(f"{client_info.client_id}:".encode()).decode(),
+        "Authorization": "Basic " + base64.b64encode(f"{client_info.client_id}:{client_info.client_secret if client_info.client_secret is not None else ''}".encode()).decode(),
     }
 
     data = {
@@ -110,6 +139,8 @@ def exchange_code_for_response(
         "redirect_uri": redirect_uri,
         "grant_type": "authorization_code",
     }
+    if code_verifier is not None:
+        data["code_verifier"] = code_verifier
     encoded_data = urllib.parse.urlencode(data).encode('utf-8')
 
     request = urllib.request.Request(client_info.token_url, data=encoded_data, headers=headers)
@@ -117,12 +148,39 @@ def exchange_code_for_response(
 
     return json_response
 
+def refresh_access_token(
+        client_info: OAuth2ClientInfo,
+        refresh_token: str,
+) -> dict:
+    """
+    Refresh an access token using the endpoints from client info
+
+    :param client_info: Info about oauth2 client
+    :param refresh_token: Refresh token to use
+    :return: Response from OAuth2 endpoint
+    """
+    headers = {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Authorization": "Basic " + base64.b64encode(f"{client_info.client_id}:{client_info.client_secret if client_info.client_secret is not None else ''}".encode()).decode(),
+    }
+
+    data = {
+        "refresh_token": refresh_token,
+        "grant_type": "refresh_token",
+    }
+    encoded_data = urllib.parse.urlencode(data).encode('utf-8')
+
+    request = urllib.request.Request(client_info.token_url, data=encoded_data, headers=headers)
+    json_response = _load_json(request)
+
+    return json_response
 
 def exchange_code_for_access_token(
         client_info: OAuth2ClientInfo,
         redirect_uri: str,
         code: str,
-        access_token_field: str = "access_token"
+        access_token_field: str = "access_token",
+        code_verifier: Optional[str] = None,
 ) -> str:
     """
     Exchange a code for an access token using the endpoints from client info
@@ -132,8 +190,9 @@ def exchange_code_for_access_token(
     :param code: Code to redeem
     :param access_token_field: Name of the field containing the access token to use. This might differ depending on
                                the provider you are using. For example for Auth0 you have to set this to id_token
+    :param code_verifier: PKCE code verifier matching the code challenge of the authorization request
     :return: Extracted access token from response
     """
-    json_response = exchange_code_for_response(client_info, redirect_uri, code)
+    json_response = exchange_code_for_response(client_info, redirect_uri, code, code_verifier)
 
     return json_response.get(access_token_field)

{oauth2_cli_auth-1.6.2 → oauth2_cli_auth-3.0.0}/oauth2_cli_auth/http_server.py

@@ -1,6 +1,9 @@
 """
 Local HTTP server logic
 """
+import hmac
+import secrets
+import time
 from http.server import BaseHTTPRequestHandler, HTTPServer
 from string import Template
 from typing import Optional
@@ -198,6 +201,15 @@ class OAuthRedirectHandler(BaseHTTPRequestHandler):
         )
         self._serve_html(rendered_callback_page)
 
+    def _state_matches(self, params: dict) -> bool:
+        """
+        Check the state parameter of the callback against the state of the running flow (constant time)
+        """
+        received = params.get("state", [])
+        if len(received) != 1:
+            return False
+        return hmac.compare_digest(received[0].encode("utf-8"), self.server.state.encode("utf-8"))
+
     # noinspection PyPep8Naming
     def do_GET(self) -> None:
         """
@@ -207,7 +219,8 @@ class OAuthRedirectHandler(BaseHTTPRequestHandler):
 
         has_error = ("code" not in params
                      or len(params['code']) != 1
-                     or params['code'][0].strip() == "")
+                     or params['code'][0].strip() == ""
+                     or not self._state_matches(params))
 
         if has_error:
             self.send_response(400)
@@ -231,10 +244,18 @@ class OAuthCallbackHttpServer(HTTPServer):
     Simplistic HTTP Server to provide local callback URL for oauth2 provider
     """
 
-    def __init__(self, port):
-        super().__init__(("", port), OAuthRedirectHandler)
+    def __init__(self, port, host: str = "127.0.0.1", state: Optional[str] = None):
+        """
+        :param port: Port to listen on
+        :param host: Address to bind to. Defaults to loopback so the callback is not reachable from the network.
+        :param state: Value for the OAuth2 state parameter. A random one is generated if omitted.
+                      Callbacks not carrying exactly this state are rejected.
+        """
+        super().__init__((host, port), OAuthRedirectHandler)
 
         self._code: Optional[str] = None
+        self.state: str = state if state is not None else secrets.token_urlsafe(32)
+        """State that has to be sent with the authorization request and is expected on the callback"""
 
     def get_code(self) -> Optional[str]:
         """
@@ -262,12 +283,15 @@ class OAuthCallbackHttpServer(HTTPServer):
         :param timeout_per_attempt: Timeout for each attempt to be successful
         :return: Code from callback page or None if the callback page is not called successfully
         """
-        for _ in range(0, attempts):
+        deadline = time.monotonic() + attempts * timeout_per_attempt
+        while True:
+            remaining = int(deadline - time.monotonic())
+            if remaining < 1:
+                return None
             try:
-                _method_with_timeout(self.handle_request, timeout_seconds=timeout_per_attempt)
+                _method_with_timeout(self.handle_request, timeout_seconds=min(timeout_per_attempt, remaining))
             except TimeoutException:
                 continue
+            # requests without a valid code/state are rejected by the handler and do not end the wait
             if self.get_code() is not None:
                 return self.get_code()
-
-        return None

{oauth2_cli_auth-1.6.2 → oauth2_cli_auth-3.0.0}/oauth2_cli_auth/simplified_flow.py

@@ -3,6 +3,7 @@ Ready to use workflows
 """
 from oauth2_cli_auth import OAuthCallbackHttpServer, get_auth_url, exchange_code_for_access_token, OAuth2ClientInfo, \
     open_browser
+from oauth2_cli_auth.code_grant import generate_pkce_pair
 
 
 def get_access_token_with_browser_open(client_info: OAuth2ClientInfo, server_port: int = 8080) -> str:
@@ -19,9 +20,12 @@ def get_access_token_with_browser_open(client_info: OAuth2ClientInfo, server_por
     :return: Access Token
     """
     callback_server = OAuthCallbackHttpServer(server_port)
-    auth_url = get_auth_url(client_info, callback_server.callback_url)
+    code_verifier, code_challenge = generate_pkce_pair()
+    auth_url = get_auth_url(client_info, callback_server.callback_url, state=callback_server.state,
+                            code_challenge=code_challenge)
     open_browser(auth_url)
     code = callback_server.wait_for_code()
     if code is None:
         raise ValueError("No code could be obtained from browser callback page")
-    return exchange_code_for_access_token(client_info, callback_server.callback_url, code)
+    return exchange_code_for_access_token(client_info, callback_server.callback_url, code,
+                                           code_verifier=code_verifier)

{oauth2_cli_auth-1.6.2 → oauth2_cli_auth-3.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "oauth2-cli-auth"
-version = "1.6.2"
+version = "3.0.0"
 description = "Authenticate against OAuth2 Provider in Python CLIs"
 authors = ["Timo Reymann <mail@timo-reymann.de>"]
 license = "MIT"
@@ -26,7 +26,7 @@ include = [
     "LICENSE"
 ]
 [tool.poetry.dependencies]
-python = ">=3.9"
+python = ">=3.10"
 
 [tool.poetry.urls]
 "Bug Tracker" = "https://github.com/timo-reymann/python-oauth2-cli-auth/issues"
@@ -37,9 +37,9 @@ url = "https://test.pypi.org/legacy/"
 priority="explicit"
 
 [tool.poetry.group.dev.dependencies]
-pytest = "^8.0.0"
+pytest = "^9.0.0"
 coverage = "^7.3.2"
-setuptools = "^78.0.0"
+setuptools = "^84.0.0"
 pydoctor = "^24.0.0"
 
 [tool.coverage.run]

oauth2_cli_auth-1.6.2/oauth2_cli_auth/__version__.py

@@ -1 +0,0 @@
-__version__ = "1.6.2"