USTB-SSO 1.0.0__tar.gz

ustb_sso-1.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.1
+Name: USTB-SSO
+Version: 1.0.0
+Summary: USTB Single Sign-On Authentication Library
+License: MIT
+Author: Harry Huang
+Author-email: harryhuang2652@qq.com
+Requires-Python: >=3.8,<4
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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
+Provides-Extra: httpx
+Requires-Dist: httpx (>=0.28,<0.29) ; extra == "httpx"
+Description-Content-Type: text/markdown
+
+USTB-SSO (Py)
+==========
+USTB Single Sign-On Authentication Library (Python)  
+北京科技大学单点登录（SSO）身份认证实现库（Python）
+
+> This module is the Python implementation of [USTB-SSO](https://github.com/isHarryh/USTB-SSO).  
+> 此模块是 [USTB-SSO](https://github.com/isHarryh/USTB-SSO) 项目的 Python 实现。
+
+<sup> This project only supports Chinese docs. If you are an English user, feel free to contact us. </sup>
+
+## 介绍 <sub>Intro</sub>
+
+**特点：** 简单易用；自文档化；依赖最少原则；良好的类型注解；全面的错误反馈。
+
+### 实现的功能
+
+- **发起认证：**  
+  支持向[北科大 SSO 服务器](https://sso.ustb.edu.cn)发起针对指定应用的身份认证请求；
+- **进行认证：**  
+  支持使用微信二维码来完成身份认证；
+- **完成认证：**  
+  支持在认证成功后，获取已被认证的客户端实例或 Cookie 实例。
+
+## 使用方法 <sub>Usage</sub>
+
+### 安装
+
+要求 [Python](https://www.python.org) >= 3.8，且安装有 [httpx](https://www.python-httpx.org/) 库（一个类似于 requests 的库）。使用 `pip` 安装：
+
+```bash
+pip install httpx ustb_sso
+```
+
+### 前置知识
+
+要想实现通过 SSO 来北科大的某个指定的应用，需要先准备 3 个参数：
+
+1. 该应用的实体编号（`entity_id`）；
+2. 该应用的认证终点 URL（`redirect_uri`）；
+3. 该应用的内部状态名（`state`）。
+
+我们已经在 `ustb_sso.prefabs` 中以常量的形式存储了部分已知应用的参数。如果您需要接入其他应用，请自行在网页中抓取 `https://sso.ustb.edu.cn/idp/authCenter/authenticate` 这个请求的请求参数来获得。
+
+### 示例代码
+
+以下代码演示了如何获取[北科大 AI 助手](http://chat.ustb.edu.cn)（2025 年版）的令牌 Cookie。
+
+```py
+from ustb_sso import HttpxAuthSession, prefabs
+
+auth = HttpxAuthSession(**prefabs.CHAT_USTB_EDU_CN)  # ※
+
+print("Starting authentication...")
+auth.open_auth().use_wechat_auth().use_qr_code()
+
+with open(f"qr.png", "wb") as f:
+    f.write(auth.get_qr_image())  # ▲
+
+print("Waiting for confirmation... Please scan the QR code")
+pass_code = auth.wait_for_pass_code()
+
+print("Validating...")
+rsp = auth.complete_auth(pass_code)
+
+print("Response status:", rsp.status_code)
+
+cookie_name = "cookie_vjuid_login"
+print("Cookie:", cookie_name, "=", auth.client.cookies[cookie_name])
+```
+
+当代码运行到 `▲` 位置时，您需要使用微信来扫描文件夹中生成的 `qr.png` 图片中的二维码，并在微信上确认登录。
+
+#### 输出样例
+
+```txt
+Starting authentication...
+Waiting for confirmation... Please scan the QR code
+Validating...
+Response status: 200
+Cookie: cookie_vjuid_login = xxxxxxxx...
+```
+
+#### 补充解释
+
+代码的 `※` 位置使用了字典解包（`**`）操作符。它等价于：
+
+```python
+auth = HttpxAuthSession(
+    entity_id=prefabs.CHAT_USTB_EDU_CN["entity_id"],
+    redirect_uri=prefabs.CHAT_USTB_EDU_CN["redirect_uri"],
+    state=prefabs.CHAT_USTB_EDU_CN["state"]
+)
+```
+
+这里的 `prefabs.CHAT_USTB_EDU_CN` 就是我们预设的应用参数。
+
+`auth.client` 是一个 `httpx.Client` 实例（类似于 `request.Session`），用于存储 Cookie 等客户端数据。后续如果需要使用 Cookie 令牌去做其他的 API 请求，可以直接调用 `auth.client` 的相关方法。
+
+## 开发指南 <sub>Dev Guide</sub>
+
+如果您想对 USTB-SSO (Py) 进行开发，以下指引可能有所帮助。
+
+### 开始开发
+
+1. 安装 Python；
+2. 安装依赖管理工具 [Poetry](https://python-poetry.org/docs/1.8) 1.8；
+3. 克隆仓库到本地；
+4. 使用 Poetry 创建虚拟环境，并安装所有依赖项：
+   ```bash
+   poetry env use python
+   poetry install -E httpx
+   ```
+
+### 测试
+
+1. 激活虚拟环境：
+   - 在 VS Code 中选择虚拟环境中的 Python 解释器（推荐）；
+   - 或者，使用 `poetry shell` 命令进入虚拟环境。
+2. 运行测试代码：
+   - 在 VS Code 中运行任务 `Python: Test USTB-SSO`（推荐）；
+   - 或者，使用 `python <文件名>` 命令来手动运行代码。
+
+## 许可证 <sub>Licensing</sub>
+
+本项目基于 **MIT 开源许可证**，详情参见 [License](https://github.com/isHarryh/USTB-SSO/blob/main/LICENSE) 页面。
+

ustb_sso-1.0.0/README.md

@@ -0,0 +1,125 @@
+USTB-SSO (Py)
+==========
+USTB Single Sign-On Authentication Library (Python)  
+北京科技大学单点登录（SSO）身份认证实现库（Python）
+
+> This module is the Python implementation of [USTB-SSO](https://github.com/isHarryh/USTB-SSO).  
+> 此模块是 [USTB-SSO](https://github.com/isHarryh/USTB-SSO) 项目的 Python 实现。
+
+<sup> This project only supports Chinese docs. If you are an English user, feel free to contact us. </sup>
+
+## 介绍 <sub>Intro</sub>
+
+**特点：** 简单易用；自文档化；依赖最少原则；良好的类型注解；全面的错误反馈。
+
+### 实现的功能
+
+- **发起认证：**  
+  支持向[北科大 SSO 服务器](https://sso.ustb.edu.cn)发起针对指定应用的身份认证请求；
+- **进行认证：**  
+  支持使用微信二维码来完成身份认证；
+- **完成认证：**  
+  支持在认证成功后，获取已被认证的客户端实例或 Cookie 实例。
+
+## 使用方法 <sub>Usage</sub>
+
+### 安装
+
+要求 [Python](https://www.python.org) >= 3.8，且安装有 [httpx](https://www.python-httpx.org/) 库（一个类似于 requests 的库）。使用 `pip` 安装：
+
+```bash
+pip install httpx ustb_sso
+```
+
+### 前置知识
+
+要想实现通过 SSO 来北科大的某个指定的应用，需要先准备 3 个参数：
+
+1. 该应用的实体编号（`entity_id`）；
+2. 该应用的认证终点 URL（`redirect_uri`）；
+3. 该应用的内部状态名（`state`）。
+
+我们已经在 `ustb_sso.prefabs` 中以常量的形式存储了部分已知应用的参数。如果您需要接入其他应用，请自行在网页中抓取 `https://sso.ustb.edu.cn/idp/authCenter/authenticate` 这个请求的请求参数来获得。
+
+### 示例代码
+
+以下代码演示了如何获取[北科大 AI 助手](http://chat.ustb.edu.cn)（2025 年版）的令牌 Cookie。
+
+```py
+from ustb_sso import HttpxAuthSession, prefabs
+
+auth = HttpxAuthSession(**prefabs.CHAT_USTB_EDU_CN)  # ※
+
+print("Starting authentication...")
+auth.open_auth().use_wechat_auth().use_qr_code()
+
+with open(f"qr.png", "wb") as f:
+    f.write(auth.get_qr_image())  # ▲
+
+print("Waiting for confirmation... Please scan the QR code")
+pass_code = auth.wait_for_pass_code()
+
+print("Validating...")
+rsp = auth.complete_auth(pass_code)
+
+print("Response status:", rsp.status_code)
+
+cookie_name = "cookie_vjuid_login"
+print("Cookie:", cookie_name, "=", auth.client.cookies[cookie_name])
+```
+
+当代码运行到 `▲` 位置时，您需要使用微信来扫描文件夹中生成的 `qr.png` 图片中的二维码，并在微信上确认登录。
+
+#### 输出样例
+
+```txt
+Starting authentication...
+Waiting for confirmation... Please scan the QR code
+Validating...
+Response status: 200
+Cookie: cookie_vjuid_login = xxxxxxxx...
+```
+
+#### 补充解释
+
+代码的 `※` 位置使用了字典解包（`**`）操作符。它等价于：
+
+```python
+auth = HttpxAuthSession(
+    entity_id=prefabs.CHAT_USTB_EDU_CN["entity_id"],
+    redirect_uri=prefabs.CHAT_USTB_EDU_CN["redirect_uri"],
+    state=prefabs.CHAT_USTB_EDU_CN["state"]
+)
+```
+
+这里的 `prefabs.CHAT_USTB_EDU_CN` 就是我们预设的应用参数。
+
+`auth.client` 是一个 `httpx.Client` 实例（类似于 `request.Session`），用于存储 Cookie 等客户端数据。后续如果需要使用 Cookie 令牌去做其他的 API 请求，可以直接调用 `auth.client` 的相关方法。
+
+## 开发指南 <sub>Dev Guide</sub>
+
+如果您想对 USTB-SSO (Py) 进行开发，以下指引可能有所帮助。
+
+### 开始开发
+
+1. 安装 Python；
+2. 安装依赖管理工具 [Poetry](https://python-poetry.org/docs/1.8) 1.8；
+3. 克隆仓库到本地；
+4. 使用 Poetry 创建虚拟环境，并安装所有依赖项：
+   ```bash
+   poetry env use python
+   poetry install -E httpx
+   ```
+
+### 测试
+
+1. 激活虚拟环境：
+   - 在 VS Code 中选择虚拟环境中的 Python 解释器（推荐）；
+   - 或者，使用 `poetry shell` 命令进入虚拟环境。
+2. 运行测试代码：
+   - 在 VS Code 中运行任务 `Python: Test USTB-SSO`（推荐）；
+   - 或者，使用 `python <文件名>` 命令来手动运行代码。
+
+## 许可证 <sub>Licensing</sub>
+
+本项目基于 **MIT 开源许可证**，详情参见 [License](https://github.com/isHarryh/USTB-SSO/blob/main/LICENSE) 页面。

ustb_sso-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[tool.poetry]
+name = "USTB-SSO"
+version = "1.0.0"
+description = "USTB Single Sign-On Authentication Library"
+authors = ["Harry Huang <harryhuang2652@qq.com>"]
+license = "MIT"
+readme = "README.md"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[tool.poetry.dependencies]
+python = ">=3.8,<4"
+httpx = { version = "~0.28", optional = true }
+
+[tool.poetry.extras]
+httpx = ["httpx"]
+
+[[tool.poetry.source]]
+name = "PyPI-Tsinghua"
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+priority = "primary"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

ustb_sso-1.0.0/ustb_sso/__init__.py

@@ -0,0 +1,15 @@
+from . import _exceptions as exceptions
+from . import _prefabs as prefabs
+
+try:
+    from ._auth_session import HttpxAuthSession
+except ImportError:
+    pass
+
+_all_impl = ('HttpxAuthSession',)
+
+if all(i not in globals() for i in _all_impl):
+    raise ImportError(
+        f"None of these implementations is available: {_all_impl}"
+        + " , you may install httpx lib."
+    )

ustb_sso-1.0.0/ustb_sso/_auth_session.py

@@ -0,0 +1,290 @@
+from typing import Generic, Optional, TypeVar
+from typing_extensions import override, Self
+
+import re
+import time
+from urllib.parse import parse_qs, unquote, urlparse
+from html import unescape
+
+from ._exceptions import (
+    APIError,
+    BadResponseError,
+    IllegalStateError,
+    TimeoutError,
+    UnsupportedMethodError
+)
+
+_T_CLI = TypeVar("_T_CLI")
+_T_RSP = TypeVar("_T_RSP")
+
+
+class AuthSessionBase(Generic[_T_CLI, _T_RSP]):
+    _SSO_AUTH_ENTRY = "https://sso.ustb.edu.cn/idp/authCenter/authenticate"
+    _SSO_QR_INFO = "https://sso.ustb.edu.cn/idp/authn/getMicroQr"
+    _SIS_QR_PAGE = "https://sis.ustb.edu.cn/connect/qrpage"
+    _SIS_QR_IMG = "https://sis.ustb.edu.cn/connect/qrimg"
+    _SIS_QR_STATE = "https://sis.ustb.edu.cn/connect/state"
+    QR_CODE_TIMEOUT = 180
+    POLLING_TIMEOUT = 16
+
+    _client: _T_CLI
+    _entity_id: str
+    _redirect_uri: str
+    _state: str
+    _lck: Optional[str]
+    _app_id: Optional[str]
+    _return_url: Optional[str]
+    _random_token: Optional[str]
+    _sid: Optional[str]
+
+    def __init__(
+        self,
+        entity_id: str,
+        redirect_uri: str,
+        state: str = "ustb",
+        client: Optional[_T_CLI] = None
+    ):
+        """Initializes a USTB SSO authentication session.
+
+        :param entity_id: The application's entity id;
+        :param redirect_uri: The redirection URI to the authentication destination;
+        :param state: The internal state of the application;
+        :param client: The optional networking client, leave `None` to create a new one;
+        """
+        self._client = self._new_client() if not client else client
+        self._entity_id = entity_id
+        self._redirect_uri = redirect_uri
+        self._state = state
+
+        self._lck = None
+        self._app_id = None
+        self._return_url = None
+        self._random_token = None
+        self._sid = None
+
+    def _get(self, url: str, redirect: bool = False, **kwargs) -> _T_RSP:
+        raise NotImplementedError()
+
+    def _post(self, url: str, redirect: bool = False, **kwargs) -> _T_RSP:
+        raise NotImplementedError()
+
+    def _dict(self, rsp: _T_RSP) -> dict:
+        raise NotImplementedError()
+
+    def _new_client(self) -> _T_CLI:
+        raise NotImplementedError()
+
+    @property
+    def client(self) -> _T_CLI:
+        """Gets the networking client.
+        """
+        return self._client
+
+    def open_auth(self) -> Self:
+        """Initiates the authentication workflow.
+        """
+        rsp = self._get(
+            AuthSessionBase._SSO_AUTH_ENTRY,
+            params={
+                "client_id": self._entity_id,
+                "redirect_uri": self._redirect_uri,
+                "login_return": "true",
+                "state": self._state,
+                "response_type": "code"
+            },
+            redirect=False
+        )
+
+        if rsp.status_code // 100 != 3:
+            raise APIError(f"HTTP status code: {rsp.status_code}, expected 3xx")
+
+        location = rsp.headers.get("Location")
+        if not location:
+            raise BadResponseError("Missing \"Location\" header in response")
+
+        qs = parse_qs(urlparse(location.replace("/#/", "/")).query)
+        self._lck = qs.get("lck", [None])[0]
+        if not self._lck:
+            raise BadResponseError("Failed to extract \"lck\" from Location header")
+
+        return self
+
+    def use_wechat_auth(self) -> Self:
+        """Prepares WeChat authentication info.
+        """
+        if not self._lck:
+            raise IllegalStateError("Authentication not initiated. Call `open_auth` first.")
+
+        rsp = self._post(
+            self._SSO_QR_INFO,
+            json={
+                "entityId": self._entity_id,
+                "lck": self._lck
+            }
+        )
+
+        data = self._dict(rsp)
+
+        if data.get("code") != "200":
+            raise APIError(f"API code {data.get('code')}: {data.get('message', '')}")
+
+        try:
+            self._app_id = data["data"]["appId"]
+            self._return_url = data["data"]["returnUrl"]
+            self._random_token = data["data"]["randomToken"]
+        except KeyError as e:
+            raise BadResponseError(f"Missing key in response") from e
+
+        return self
+
+    def use_qr_code(self) -> Self:
+        """Prepares QR code SID from QR page.
+        """
+        if any(not i for i in (self._app_id, self._return_url, self._random_token)):
+            raise IllegalStateError("Not in WeChat mode yet. Call `use_wechat_auth` first.")
+
+        rsp = self._get(
+            self._SIS_QR_PAGE,
+            params={
+                "appid": self._app_id,
+                "return_url": self._return_url,
+                "rand_token": self._random_token,
+                "embed_flag": "1"
+            }
+        )
+
+        if rsp.status_code != 200:
+            raise APIError(f"HTTP status code {rsp.status_code}, expected 200")
+
+        match = re.search(r"sid\s?=\s?(\w{32})", rsp.text)
+        if not match:
+            raise BadResponseError("SID not found in QR page")
+        self._sid = match.group(1)
+
+        return self
+
+    def get_qr_image(self) -> bytes:
+        """Downloads QR code image and returns it in bytes.
+        """
+        if not self._sid:
+            raise IllegalStateError("SID not available. Call `use_qr_code` first.")
+
+        rsp = self._get(
+            self._SIS_QR_IMG,
+            params={"sid": self._sid}
+        )
+
+        if rsp.status_code != 200:
+            raise APIError(
+                f"QR image request failed with HTTP status code {rsp.status_code}"
+            )
+
+        return rsp.content
+
+    def wait_for_pass_code(self) -> str:
+        """Polls the authentication status until completion or timeout.
+
+        Returns the pass code if completed. Raises exception when timed out.
+        """
+        if not self._sid:
+            raise IllegalStateError("SID not available. Call `use_qr_code` first.")
+
+        start_time = time.time()
+        while time.time() - start_time < self.QR_CODE_TIMEOUT:
+            try:
+                rsp = self._get(
+                    self._SIS_QR_STATE,
+                    params={
+                        "sid": self._sid
+                    },
+                    timeout=self.POLLING_TIMEOUT
+                )
+            except Exception:
+                time.sleep(1)
+                continue
+
+            data = self._dict(rsp)
+
+            code = data.get("code")
+            if code == 1:  # Success
+                return data["data"]
+            elif code in (3, 202):  # Expired
+                raise TimeoutError("QR code expired")
+            elif code == 4:  # Timeout
+                continue
+            elif code in (101, 102):  # Invalid
+                raise APIError(f"API code {code}: {data.get('message', '')}")
+
+        raise TimeoutError("Authentication polling timed out")
+
+    def complete_auth(self, pass_code: str) -> _T_RSP:
+        """Completes authentication workflow.
+        """
+        if any(not i for i in (self._app_id, self._return_url, self._random_token)):
+            raise IllegalStateError("Authentication not well established")
+
+        params = {
+            "appid": self._app_id,
+            "auth_code": pass_code,
+            "rand_token": self._random_token
+        }
+        params.update(parse_qs(urlparse(self._return_url).query))
+
+        rsp = self._get(
+            self._return_url,
+            params=params,
+            redirect=True
+        )
+
+        action_type_match = re.search(r'var actionType\s*=\s*"([^"]+)"', rsp.text)
+        location_value_match = re.search(r'var locationValue\s*=\s*"([^"]+)"', rsp.text)
+        if action_type_match and location_value_match:
+            action_type = unescape(unquote(action_type_match.group(1)))
+            location_value = unescape(unquote(location_value_match.group(1)))
+        else:
+            raise BadResponseError("Failed to get authentication destination")
+
+        if action_type.upper() != "GET":
+            raise UnsupportedMethodError("Unsupported authentication destination method")
+
+        rsp_ = self._get(
+            location_value,
+            redirect=True
+        )
+
+        return rsp_
+
+
+try:
+    import httpx
+
+    class HttpxAuthSession(AuthSessionBase[httpx.Client, httpx.Response]):
+        @override
+        def _get(self, url: str, redirect: bool = False, **kwargs) -> httpx.Response:
+            return self._client.get(url, follow_redirects=redirect, **kwargs)
+
+        @override
+        def _post(self, url: str, redirect: bool = False, **kwargs) -> httpx.Response:
+            return self._client.post(url, follow_redirects=redirect, **kwargs)
+
+        @override
+        def _dict(self, rsp: httpx.Response) -> dict:
+            if rsp.status_code != 200:
+                raise APIError(
+                    f"HTTP status code: {rsp.status_code}, expected 200"
+                )
+
+            try:
+                data = rsp.json()
+                if not isinstance(data, dict):
+                    raise TypeError("Not a dict")
+                return data
+            except Exception as e:
+                raise BadResponseError("Invalid JSON response") from e
+
+        @override
+        def _new_client(self):
+            return httpx.Client()
+
+except ImportError:
+    pass

ustb_sso-1.0.0/ustb_sso/_exceptions.py

@@ -0,0 +1,28 @@
+class AuthException(Exception):
+    """Base exception for authentication errors.
+    """
+
+
+class APIError(AuthException):
+    """Exception raised for unexpected HTTP status code or API status code.
+    """
+
+
+class BadResponseError(AuthException):
+    """Exception raised for unparsable API response.
+    """
+
+
+class IllegalStateError(AuthException):
+    """Exception raised when authentication gets into illegal state.
+    """
+
+
+class TimeoutError(AuthException):
+    """Exception raised when authentication times out or expired.
+    """
+
+
+class UnsupportedMethodError(AuthException):
+    """Exception raised when an unsupported authentication method is given.
+    """

ustb_sso-1.0.0/ustb_sso/_prefabs.py

@@ -0,0 +1,21 @@
+from typing import TypedDict
+
+
+class ApplicationParam(TypedDict):
+    entity_id: str
+    redirect_uri: str
+    state: str
+
+# Last updated: 2025-2-28
+
+JWGL_USTB_EDU_CN: ApplicationParam = {
+    "entity_id": "NS2022062",
+    "redirect_uri": "https://jwgl.ustb.edu.cn/glht/Logon.do?method=weCharLogin",
+    "state": "test"
+}
+
+CHAT_USTB_EDU_CN: ApplicationParam = {
+    "entity_id": "YW2025007",
+    "redirect_uri": "http://chat.ustb.edu.cn/common/actionCasLogin?redirect_url=http%3A%2F%2Fchat.ustb.edu.cn%2Fpage%2Fsite%2FnewPc%3Flogin_return%3Dtrue",
+    "state": "ustb"
+}