IWish Auth 开发者文档

FastAPI 使用 iwish_auth.fastapi.IWishFastAPIAuth。Adapter 提供登录、callback、登出和依赖注入，并将 SDK 稳定错误转换为 HTTP 状态。

1. 配置 Adapter

import os
from iwish_auth.fastapi import IWishFastAPIAuth, IWishFastAPIAuthOptions

auth = IWishFastAPIAuth(IWishFastAPIAuthOptions(
    api_url=os.environ["IWISH_AUTH_API_URL"],
    portal_url=os.environ["IWISH_AUTH_PORTAL_URL"],
    app_key=os.environ["IWISH_AUTH_APP_KEY"],
    client_id=os.environ["IWISH_AUTH_CLIENT_ID"],
    client_secret=os.environ["IWISH_AUTH_CLIENT_SECRET"],
    redirect_uri=os.environ["IWISH_AUTH_REDIRECT_URI"],
))

client_secret 只能从服务端环境或 secret manager 读取。

2. 登录、Callback 和登出

from fastapi import FastAPI, Request

app = FastAPI()

@app.get("/auth/login")
async def login(request: Request, return_to: str = "/"):
    return await auth.login(request, return_to=return_to)

@app.get("/auth/callback")
async def callback(request: Request):
    return await auth.callback(request)

@app.post("/auth/logout")
async def logout(request: Request):
    return await auth.logout(request)

3. 保护接口

from fastapi import Depends

@app.get("/api/reports")
async def reports(
    session=Depends(auth.require_permission("reporting.report.read")),
):
    return {
        "user": session["user"],
        "organization": session["organization"],
        "clientAssignments": session.get("clientAssignments", []),
    }

可用依赖：

auth.require_auth：要求有效 App session。
auth.require_app_access：同时确认 session 属于当前 App。
auth.require_organization：返回当前授权域。
auth.require_permission(permission)：检查 App scoped permission。
auth.get_client_assignments：返回当前有效项目分工。

4. 直接使用 Python Client

后台任务或非 FastAPI 服务可以直接使用异步 Client：

from iwish_auth import IWishAuthClient

async with IWishAuthClient(
    api_url=IWISH_AUTH_API_URL,
    token=app_session_token,
) as client:
    session = await client.get_app_session()
    decision = await client.check_permission("reporting.report.read")

Client 使用短 TTL session 缓存，且缓存有效期不会超过 Auth session 的 expiresAt。

5. 错误映射

SDK 错误	HTTP	业务处理
`IWishAuthUnauthorizedError`	401	清理本 App cookie 并重新登录
`IWishAuthForbiddenError`	403	展示无权限，不循环登录
`IWishAuthError`	原始状态	记录稳定错误码和 request id

6. 测试

FastAPI TestClient 或 httpx.AsyncClient 测试至少覆盖：登录 302、callback state、session cookie、允许权限、缺少权限、跨 App 权限和登出。完整实现见 examples/fastapi-app。