#actix #auth #security #permissions #grants

actix-web-grants

Extension for actix-web to validate user permissions

15 releases (3 major breaking)

3.0.0-beta.3 Oct 11, 2021
3.0.0-beta.1 Apr 7, 2021
2.2.0 Oct 11, 2021
2.0.1 Mar 10, 2021
0.1.6 Jan 17, 2021

#11 in Authentication

Download history 109/week @ 2021-07-01 97/week @ 2021-07-08 95/week @ 2021-07-15 159/week @ 2021-07-22 160/week @ 2021-07-29 121/week @ 2021-08-05 218/week @ 2021-08-12 129/week @ 2021-08-19 117/week @ 2021-08-26 84/week @ 2021-09-02 162/week @ 2021-09-09 288/week @ 2021-09-16 281/week @ 2021-09-23 102/week @ 2021-09-30 156/week @ 2021-10-07 114/week @ 2021-10-14

673 downloads per month

MIT/Apache

37KB
278 lines

actix-web-grants

actix-web-grants

Extension for actix-web to validate user permissions.

CI Crates.io Downloads Badge crates.io Documentation dependency status Apache 2.0 or MIT licensed

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

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

How to use

  1. Declare your own permission 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};

async fn extract(req: &ServiceRequest) -> Result<Vec<String>, Error>
  1. 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. Look at jwt-httpauth example

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

Example of proc-macro way protection

use actix_web_grants::proc_macro::{has_permissions};

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

Example of Guard way protection

use actix_web_grants::{PermissionGuard, GrantsMiddleware};

App::new()
    .wrap(GrantsMiddleware::with_extractor(extract))
    .service(web::resource("/admin")
            .to(|| async { HttpResponse::Ok().finish() })
            .guard(PermissionGuard::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() }))
Example of custom fallback endpoint for `Scope` with `Guard`

Since Guard is intended only for routing, if the user doesn't have permissions, it returns a 404 HTTP code. But you can override the behavior like this:

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

App::new()
    .wrap(GrantsMiddleware::with_extractor(extract))
    .service(web::scope("/admin")
        .guard(PermissionGuard::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()
        }))

When Guard lets you in the Scope (meaning you have "ROLE_ADMIN_ACCESS"), the redirect will be unreachable for you. Even if you will request /admin/some_undefined_page.

Note: regex is a Path variable containing passed link.

Example of manual way protection

use actix_web_grants::permissions::{AuthDetails, PermissionsCheck};

async fn manual_secure(details: AuthDetails) -> HttpResponse {
    if details.has_permission(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.* supported version of actix-web is 4.*

Dependencies

~22MB
~514K SLoC