actix-web-grants

actix-web的授权扩展，用于保护你的端点。

如何使用

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

最简单的方式是声明一个具有以下签名的函数（这样的Fn已经实现了对应的trait）：

use actix_web::{dev::ServiceRequest, Error};

// 你可以使用自定义类型代替String
async fn extract(req: &ServiceRequest) -> Result<HashSet<String>, Error>

1. 使用第1步定义的提取器将中间件添加到你的应用中

App::new()
    .wrap(GrantsMiddleware::with_extractor(extract))

第1步和第2步可以用自定义中间件或与其他库的集成来替代。

1. 用下面任意一种方便的方式保护你的端点：

使用proc-macro方式保护的示例

#[get("/secure")]
#[actix_web_grants::protect("OP_READ_SECURED_INFO")]
async fn macro_secured() -> HttpResponse {
    HttpResponse::Ok().body("ADMIN_RESPONSE")
}

ABAC-like保护和自定义权限类型的示例：

use enums::Role::{self, ADMIN};
use dto::User;

#[get("/info/{user_id}")]
#[actix_web_grants::protect("ADMIN", expr = "user_id.into_inner() == user.id", ty = "Role")]
async fn macro_secured(user_id: web::Path<i32>, user: web::Data<User>) -> HttpResponse {
    HttpResponse::Ok().body("some secured response")
}

#[post("/info/{user_id}")]
#[actix_web_grants::protect(any("ADMIN", expr = "user.is_super_user()"), ty = "Role")]
async fn admin_or_super_user(user_id: web::Path<i32>, user: web::Data<User>) -> HttpResponse {
    HttpResponse::Ok().body("some secured response")
}

使用Guard方式保护的示例

use actix_web_grants::{AuthorityGuard, GrantsMiddleware};

App::new()
    .wrap(GrantsMiddleware::with_extractor(extract))
    .service(web::resource("/admin")
            .to(|| async { HttpResponse::Ok().finish() })
            .guard(AuthorityGuard::new("ROLE_ADMIN".to_string())))
    .service(web::resource("/admin") // 如果你想返回403 HTTP代码的备用端点
            .to(|| async { HttpResponse::Forbidden().finish() }))

使用Guard为Scope自定义备用端点的示例：

use actix_web_grants::{AuthorityGuard, GrantsMiddleware};
use actix_web::http::header;

App::new()
    .wrap(GrantsMiddleware::with_extractor(extract))
    .service(web::scope("/admin")
        .guard(AuthorityGuard::new("ROLE_ADMIN_ACCESS".to_string()))
        .service(web::resource("/users")
            .to(|| async { HttpResponse::Ok().finish() }))
    ).service(
        web::resource("/admin{regex:$|/.*?}").to(|| async { 
            HttpResponse::TemporaryRedirect().append_header((header::LOCATION, "/login")).finish()
        }))

手动方式保护的示例

use actix_web_grants::authorities::{AuthDetails, AuthoritiesCheck};

async fn manual_secure(details: AuthDetails) -> HttpResponse {
    if details.has_authority(ROLE_ADMIN) {
        return HttpResponse::Ok().body("ADMIN_RESPONSE");
    }
    HttpResponse::Ok().body("OTHER_RESPONSE")
}

支持的actix-web版本

• 对于actix-web-grants: 2.*，支持的actix-web版本是3.*
• 对于actix-web-grants: 3.*和4.*，支持的actix-web版本是4.*

完整示例代码

下面是一个完整的示例，展示如何使用actix-web-grants：

use actix_web::{web, App, HttpResponse, HttpServer};
use actix_web_grants::{GrantsMiddleware, AuthorityGuard};
use std::collections::HashSet;

// 权限提取函数
async fn extract(_req: &actix_web::dev::ServiceRequest) -> Result<HashSet<String>, actix_web::Error> {
    // 这里应该实现实际的权限提取逻辑
    // 示例中我们返回一个包含"ROLE_ADMIN"的集合
    Ok(HashSet::from(["ROLE_ADMIN".to_string()]))
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(move || {
        App::new()
            // 添加权限中间件
            .wrap(GrantsMiddleware::with_extractor(extract))
            
            // 使用proc-macro方式保护的路由
            .service(
                web::resource("/macro-secured")
                    .to(|| async { HttpResponse::Ok().body("Macro secured endpoint") })
            )
            
            // 使用Guard方式保护的路由
            .service(
                web::resource("/guard-secured")
                    .to(|| async { HttpResponse::Ok().body("Guard secured endpoint") })
                    .guard(AuthorityGuard::new("ROLE_ADMIN".to_string()))
            )
            
            // 手动检查方式
            .service(
                web::resource("/manual-secured")
                    .to(|details: actix_web_grants::authorities::AuthDetails| async move {
                        if details.has_authority("ROLE_ADMIN") {
                            HttpResponse::Ok().body("Manual secured endpoint - authorized")
                        } else {
                            HttpResponse::Forbidden().body("Manual secured endpoint - forbidden")
                        }
                    })
            )
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

这个示例展示了三种不同的保护方式：

1. proc-macro方式（需要在路由函数上添加#[protect]属性）
2. Guard方式（使用AuthorityGuard）
3. 手动检查方式（在handler中直接检查权限）

要运行这个示例，请确保在Cargo.toml中添加了以下依赖：

[dependencies]
actix-web = "4"
actix-web-grants = "4"

这个示例提供了一个基础框架，你可以根据自己的需求扩展权限提取逻辑和路由保护策略。