poem-grants

为 poem 提供授权扩展，以保护您的端点。

要检查用户对特定服务的访问权限，您可以使用内置的 proc-macro 或手动方式。

此库还可以与第三方解决方案或自定义中间件（如 jwt-auth 示例）集成。

注意：即使在 beta 标志下，它也是一个现成的库。然而，我计划很快准备一个包含更多功能的整个 *-grants 生态系统的重大更新。

如何使用

1. 声明自己的 权限提取器

最简单的方法是声明一个具有以下签名的函数（该特质已为此类 Fn 实现）

// You can use custom type instead of String
async fn extract(req: &poem::Request) -> poem::Result<HashSet<String>>

2. 使用步骤 1 中定义的提取器将中间件添加到您的应用程序中

Route::new()
    .at("/endpoint", your_endpoint)
    .with(GrantsMiddleware::with_extractor(extract))

步骤 1 和 2 可以用自定义中间件或与其他库的集成替换。请参阅 jwt-auth 示例

3. 以下是一些示例，说明如何以任何方便的方式保护您的端点

proc-macro 方式保护示例

use poem::{Response, http::StatusCode};

#[poem_grants::protect("OP_READ_SECURED_INFO")]
#[poem::handler]
async fn macro_secured() -> Response {
    Response::builder().status(StatusCode::OK).body("ADMIN_RESPONSE")
}

或针对 poem-openapi

use poem_openapi::{OpenApi, payload::PlainText};

struct Api;

#[poem_grants::open_api] // It's important to keep above of `OpenApi`
#[OpenApi]
impl Api {
    #[protect("OP_READ_ADMIN_INFO")]
    #[oai(path = "/admin", method = "get")]
    async fn macro_secured(&self) -> PlainText<String> {
        PlainText("ADMIN_RESPONSE".to_string())
    }
}

use poem::{Response, http::StatusCode, web};
use enums::Role::{self, ADMIN};
use dto::User;

#[poem_grants::protect("ADMIN", expr = "*user_id == user.id", ty = "Role")]
#[poem::handler]
async fn macro_secured(user_id: web::Path<i32>, user: web::Data<User>) -> Response {
    Response::builder().status(StatusCode::OK).body("some secured response")
}

#[poem_grants::protect(any("ADMIN", expr = "user.is_super_user()"), ty = "Role")]
#[poem::handler]
async fn admin_or_super_user(user_id: web::Path<i32>, user: web::Data<User>) -> Response {
    Response::builder().status(StatusCode::OK).body("some secured response")
}

手动保护示例

use poem::{Response, http::StatusCode};
use poem_grants::authorities::{AuthDetails, AuthoritiesCheck};

#[poem::handler]
async fn manual_secure(details: AuthDetails) -> Response {
    if details.has_authority("ROLE_ADMIN") {
        return Response::builder().status(StatusCode::OK).body("ADMIN_RESPONSE");
    }
    Response::builder().status(StatusCode::OK).body("OTHER_RESPONSE")
}

您可以在 Git 仓库文件夹和 文档 中找到更多 示例。

支持的 poem 版本

• 对于 poem-grants: 3.*，支持的 poem 版本是 3.*
• 对于 poem-grants: 2.*，支持的 poem 版本是 2.*
• 对于 poem-grants: 1.*，支持的 poem 版本是 1.*