跳到主内容

FastAPI

casbin-fastapi-decorator 是一个社区库,用装饰器保护 FastAPI 路由。它的 Casdoor 包 casbin-fastapi-decorator-casdoor 通过 Casdoor(OAuth2)登录用户,并调用 Casdoor 的 /api/enforce 接口检查权限,策略保存在 Casdoor 而不是你的应用里。

备注

这个库由社区维护,不是 Casdoor 团队维护的。问题请在它的 GitHub 仓库 中反馈。

以下是配置中的一些名称:

CASDOOR_HOSTNAME:Casdoor 服务器部署的域名或 IP,例如 http://localhost:8000。

FASTAPI_HOSTNAME:FastAPI 应用部署的域名或 IP,例如 http://localhost:8080。

步骤1:部署Casdoor​

部署 Casdoor,确认能登录。

步骤 2:配置 Casdoor​

  1. 新建一个 应用 或使用已有的应用。
  2. 把 FASTAPI_HOSTNAME/callback 加到应用的 Redirect URLs。
  3. 复制 Client ID、Client Secret、组织名和应用名。
  4. 打开应用所用的证书(Certs 页面),复制公钥。
  5. 创建应用要检查的权限规则。目标可以是 执行器、权限、模型、资源或整个组织;第 4 步会传入它的 ID。

第 3 步:安装库​

pip install "casbin-fastapi-decorator[casdoor]"

需要 Python 3.10 或更高版本。

第 4 步:保护路由​

CasdoorIntegration 一次调用就能创建 Casdoor SDK 客户端、登录路由和 PermissionGuard:

from fastapi import FastAPI
from casbin_fastapi_decorator_casdoor import CasdoorEnforceTarget, CasdoorIntegration

casdoor = CasdoorIntegration(
endpoint="http://localhost:8000",
client_id="<client-id>",
client_secret="<client-secret>",
certificate="-----BEGIN CERTIFICATE-----\n...",
org_name="built-in",
application_name="app-built-in",
target=CasdoorEnforceTarget(
# the enforcer ID is built from the signed-in user's organization
enforce_id=lambda parsed: f"{parsed['owner']}/my-enforcer",
),
cookie_secure=False, # only for local HTTP testing; keep the default True in production
)

app = FastAPI()
app.include_router(casdoor.router) # GET /login, GET /callback, POST /logout, GET /me
guard = casdoor.create_guard()

@app.get("/articles")
@guard.require_permission("articles", "read")
async def list_articles():
return []

@app.get("/profile")
@guard.auth_required()
async def profile():
return {"ok": True}

如何操作?

  1. 让用户访问 FASTAPI_HOSTNAME/login。应用带着随机的 state 值跳转到 Casdoor。
  2. 登录后,Casdoor 跳回 /callback。应用检查 state,用 code 换取令牌,并保存在 access_token 和 refresh_token Cookie 中。
  3. 每个受保护的请求,应用都会用证书校验令牌,并以 ["<owner>/<name>", "articles", "read"] 调用 Casdoor 的 /api/enforce。被拒绝的请求返回 403 Forbidden。
  4. POST /logout 会让用户退出 Casdoor 并清除 Cookie。

第 5 步:选择执行目标​

CasdoorEnforceTarget 决定由哪个 Casdoor 对象存放规则。只设置其中一个字段,值可以是固定 ID,也可以是一个接收解析后 JWT 的函数:

字段Casdoor 对象
enforce_id执行器,例如 built-in/my-enforcer
permission_id权限,例如 built-in/can-read-articles
model_id模型,例如 built-in/rbac-model
resource_id资源
所属者组织的所有权限,例如 built-in
CasdoorEnforceTarget(permission_id="built-in/can-read-articles")

高级用法​

要使用自己的用户 ID 格式、每个 guard 不同的目标,或者自定义错误响应,可以自己组装各部分:

from casdoor import AsyncCasdoorSDK
from fastapi import FastAPI, HTTPException
from casbin_fastapi_decorator import PermissionGuard
from casbin_fastapi_decorator_casdoor import (
CasdoorEnforcerProvider,
CasdoorEnforceTarget,
CasdoorUserProvider,
make_casdoor_router,
)

sdk = AsyncCasdoorSDK(
endpoint="http://localhost:8000",
client_id="<client-id>",
client_secret="<client-secret>",
certificate="<certificate>",
org_name="built-in",
application_name="app-built-in",
)

guard = PermissionGuard(
user_provider=CasdoorUserProvider(sdk=sdk),
enforcer_provider=CasdoorEnforcerProvider(
sdk=sdk,
target=CasdoorEnforceTarget(enforce_id="built-in/my-enforcer"),
user_factory=lambda parsed: parsed["email"], # default is "owner/name"
),
error_factory=lambda user, *rvals: HTTPException(403, "Forbidden"),
)

app = FastAPI()
app.include_router(make_casdoor_router(sdk, redirect_after_login="/docs"))

全部选项(例如 Cookie 名称、Cookie 域和自定义 state 存储)见 库的 README。