actix-web-grants

Authorization extension for actix-web to protect your endpoints.

To check user access to specific services, you can use built-in proc-macro, AuthorityGuard or manual.

The library can also be integrated with third-party solutions (like actix-web-httpauth).

How to use

1. Declare your own authority extractor

The easiest way is to declare a function with the following signature (trait is already implemented for such Fn):

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

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

2. Add middleware to your application using the extractor defined in step 1

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

Steps 1 and 2 can be replaced by custom middleware or integration with another libraries. Take a look at an jwt-httpauth example

3. Protect your endpoints in any convenient way from the examples below:

Example of proc-macro way protection

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

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")
}

Example of Guard way protection

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") // fallback endpoint if you want to return a 403 HTTP code 
            .to(|| async { HttpResponse::Forbidden().finish() }))

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()
        }))

Example of manual way protection

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")
}

You can find more examples in the git repository folder and documentation.

Supported actix-web versions

• For actix-web-grants: 2.* supported version of actix-web is 3.*
• For actix-web-grants: 3.* & 4.* supported version of actix-web is 4.*