blade-auth-client 0.4.0

Shared Casdoor authentication client for Blade ecosystem services.

blade-auth-client

blade-auth-client 是 Blade 生态的共享 Casdoor 认证客户端包。它抽离了统一的 token 校验、FastAPI 装配和 Socket.IO 握手接口，供各个服务复用。

安装

pip install blade-auth-client[fastapi,socketio]

Casdoor 配置要求

Casdoor 的 application、scope 和 redirect URI 约束见 docs/casdoor-setup.md。

快速上手(0.4.0+)

from fastapi import FastAPI, Depends
from blade_auth_client import AuthConfig, BladeAuth, CasdoorClaims, LazyProvisioner

class MyProvisioner(LazyProvisioner["MyUser"]):
    async def provision_user(self, claims: CasdoorClaims) -> "MyUser":
        # 首次登录:建用户并绑定 claims.sub;非首次:查出来刷字段
        ...

auth = BladeAuth(
    AuthConfig.from_yaml("configs/oauth_config.yaml"),
    provisioner=MyProvisioner(),
)

app = FastAPI()
app.include_router(auth.router, prefix="/api/v1/auth")

@app.get("/me")
def me(user = auth.require()):
    return user

详细流程见 docs/接入指南.md;多 app 共享鉴权 / BladeAuth 设计背景见 docs/设计-API暴露面收敛.md。

从 0.3.x 升级

• 推荐迁到 BladeAuth facade(上面那段)。老零件(OidcClient / TokenVerifier / create_auth_router / make_require_auth_dep / 等)0.4.0 仍可从顶层 import,但会 DeprecationWarning,0.5.0 移除。
• LazyProvisioner.ensure_user → provision_user。老名字继续可用且 SDK 内部自动回落,调用时 warn 一次。

版本策略

0.0.x 版本仅用于占位发布和联调验证，不承诺可用性。0.2.0 起采用仅校验 iss + 签名 + exp 的简化策略。

发布

仓库已经预留了 GitHub Actions 发布流水线：

• PR 校验：.github/workflows/python-sdk-ci.yml
• PyPI 发布：.github/workflows/python-sdk-publish.yml

首次配置 Trusted Publishing 时，在 PyPI 项目的 Publishing 页面添加 GitHub publisher，填写：

• Owner: blade-hq
• Repository name: blade-oauth
• Workflow name: python-sdk-publish.yml

日常发版流程：

# 1. 修改 sdk/python/pyproject.toml 里的 version

# 2. 推送代码到默认分支后，创建并推送同版本 tag
git tag blade-auth-client-vX.Y.Z
git push origin blade-auth-client-vX.Y.Z

发布 workflow 会校验 tag 版本与 pyproject.toml 一致，然后自动构建并发布到 PyPI。