skyplatform-iam 1.0.0

SkyPlatform IAM认证SDK，提供FastAPI中间件和认证路由

SkyPlatform IAM SDK

SkyPlatform IAM认证SDK，提供FastAPI中间件和认证路由，简化第三方服务的认证集成。

功能特性

• 🔐 FastAPI中间件: 自动拦截请求进行Token验证和权限检查
• 🚀 认证路由: 封装用户注册、登录、登出等认证接口
• ⚙️ 灵活配置: 支持环境变量和代码配置
• 🛡️ 白名单机制: 支持配置无需认证的路径
• 🔧 完整兼容: 基于现有ConnectAgenterraIam类，保持完全兼容
• 📝 类型提示: 完整的TypeScript风格类型提示
• 🚨 异常处理: 完善的错误处理和自定义异常

快速开始

安装

pip install skyplatform-iam

环境变量配置

创建 .env 文件或设置环境变量：

AGENTERRA_IAM_HOST=https://your-iam-host.com
AGENTERRA_SERVER_NAME=your-server-name
AGENTERRA_ACCESS_KEY=your-access-key

基本使用

方式1：一键设置（推荐）

from fastapi import FastAPI
from skyplatform_iam import setup_auth

app = FastAPI()

# 一键设置认证中间件和路由
setup_auth(app)

@app.get("/protected")
async def protected_endpoint(request):
    # 获取用户信息（由中间件自动设置）
    user = request.state.user
    return {"message": "访问成功", "user": user}

方式2：手动设置

from fastapi import FastAPI
from skyplatform_iam import AuthConfig, AuthMiddleware, create_auth_router

app = FastAPI()

# 创建配置
config = AuthConfig.from_env()

# 添加认证中间件
app.add_middleware(AuthMiddleware, config=config)

# 添加认证路由
auth_router = create_auth_router(config=config, prefix="/auth")
app.include_router(auth_router)

方式3：自定义配置

from skyplatform_iam import AuthConfig, setup_auth

# 自定义配置
config = AuthConfig(
    agenterra_iam_host="https://your-iam-host.com",
    server_name="your-server-name",
    access_key="your-access-key",
    whitelist_paths=[
        "/docs", "/redoc", "/openapi.json",
        "/health", "/public",
        "/auth/register", "/auth/login"
    ],
    enable_debug=True
)

setup_auth(app, config=config)

API接口

SDK自动提供以下认证接口：

• POST /auth/register - 用户注册
• POST /auth/login - 用户登录
• POST /auth/login_without_password - 免密登录
• POST /auth/logout - 用户登出
• POST /auth/reset_password - 重置密码
• POST /auth/refresh_token - 刷新Token
• POST /auth/assign_role - 分配角色
• POST /auth/user_info - 获取用户信息

中间件功能

自动Token验证

中间件会自动：

1. 检查请求路径是否在白名单中
2. 从请求头提取Authorization Token
3. 调用IAM服务验证Token和权限
4. 将用户信息设置到 request.state.user

白名单配置

默认白名单路径：

• /docs, /redoc, /openapi.json - API文档
• /health - 健康检查
• /auth/* - 认证相关接口

添加自定义白名单：

config = AuthConfig.from_env()
config.add_whitelist_path("/public")
config.add_whitelist_path("/status")

获取用户信息

在受保护的路由中获取用户信息：

@app.get("/user-profile")
async def get_user_profile(request):
    if hasattr(request.state, 'user'):
        user = request.state.user
        return {
            "user_id": user["user_id"],
            "username": user["username"],
            "session_id": user["session_id"]
        }
    else:
        raise HTTPException(status_code=401, detail="未认证")

异常处理

SDK提供完整的异常处理：

from skyplatform_iam.exceptions import (
    AuthenticationError,    # 认证失败
    AuthorizationError,     # 权限不足
    TokenExpiredError,      # Token过期
    TokenInvalidError,      # Token无效
    ConfigurationError,     # 配置错误
    IAMServiceError,        # IAM服务错误
    NetworkError           # 网络错误
)

配置选项

AuthConfig参数

参数	类型	必填	说明
agenterra_iam_host	str	✓	IAM服务地址
server_name	str	✓	服务名称
access_key	str	✓	访问密钥
whitelist_paths	List[str]	✗	白名单路径
token_header	str	✗	Token请求头名称（默认：Authorization）
token_prefix	str	✗	Token前缀（默认：Bearer ）
enable_debug	bool	✗	启用调试模式

开发和测试

运行测试

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
python examples/test_sdk.py

运行示例

# 启动示例应用
python examples/basic_usage.py

# 访问 http://localhost:8000/docs 查看API文档

兼容性

• Python 3.8+
• FastAPI 0.68.0+
• 完全兼容现有的 ConnectAgenterraIam 类

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

更新日志

v1.0.0

• 初始版本发布
• 提供FastAPI中间件和认证路由
• 支持完整的认证功能
• 兼容现有ConnectAgenterraIam类