protect-endpoints

The protect macro supports advanced logic using expr and ty attributes for Attribute-Based Access Control (ABAC) style checks.

• expr: Allows including logic checks based on function parameters. You can combine these with authorities using all or any.
• ty: Allows specifying a custom type for authorities (requires the middleware to be configured for that type).

Examples

Single authority with expression check:

#[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 { ... }

Logical OR with expression check:

#[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 { ... }

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

To use rocket-grants to authorize requests in your Rocket application, follow these three steps:

1. Define an authority extraction function: Create an async function that takes a &rocket::Request<'_> and returns an Option<HashSet<String>> (or a custom type). This function is responsible for determining which authorities/permissions are associated with the current request.

2. Attach the GrantsFairing: Register the fairing in your Rocket build process, passing your extraction function to GrantsFairing::with_extractor_fn. Since the extractor is async, you must wrap the call in Box::pin.

3. Protect endpoints: Use either the #[rocket_grants::protect] procedural macro or manual checks within your route handlers.

// 1. Define extractor
async fn extract(req: &rocket::Request<'_>) -> Option<HashSet<String>> {
    // logic to extract permissions
    None
}

// 2. Attach fairing
#[rocket::launch]
fn rocket() -> _ {
    rocket::build()
        .mount("/api", rocket::routes![endpoint])
        .attach(GrantsFairing::with_extractor_fn(|req| {
            Box::pin(extract(req))
        }))
}

You can protect endpoints declaratively using the #[poem_grants::protect(...)] macro. This is the most convenient way to enforce specific authorities on a handler.

Standard Poem Handlers

Apply the macro directly above your #[poem::handler]:

#[poem_grants::protect("OP_READ_SECURED_INFO")]
#[poem::handler]
async fn macro_secured() -> Response { ... }

Poem-OpenAPI Handlers

When using poem-openapi, you must use the #[poem_grants::open_api] macro, and it must be placed above the #[OpenApi] attribute:

#[poem_grants::open_api]
#[OpenApi]
impl Api {
    #[protect("OP_READ_ADMIN_INFO")]
    #[oai(path = "/admin", method = "get")]
    async fn macro_secured(&self) -> PlainText<String> { ... }
}

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

To use actix-web-grants for endpoint protection, follow these three steps:

1. Define an authority extractor: Create an asynchronous function that extracts user authorities from a ServiceRequest. The function should return a Result containing a collection of authorities (e.g., HashSet<String>) or an actix_web::Error.
2. Register the middleware: Add the GrantsMiddleware to your App using the extractor defined in step 1.
3. Protect endpoints: Use one of the three protection methods: proc-macro, Guard, or manual checks.

Note: You can integrate this with third-party libraries like actix-web-httpauth or use custom middleware instead of the standard extractor setup.

use actix_web::{dev::ServiceRequest, Error};
use std::collections::HashSet;

// 1. Define the extractor
async fn extract(req: &ServiceRequest) -> Result<HashSet<String>, Error> {
    // implementation logic to get authorities
    Ok(HashSet::new())
}

// 2. Add middleware to the App
App::new()
    .wrap(GrantsMiddleware::with_extractor(extract))
    // 3. Protect endpoints (see methods below)

To use protect-axum, you must first define an authority extractor and then apply it to your Axum Router using GrantsLayer.

1. Define an authority extractor: Create an async function that takes a mutable reference to an axum::extract::Request and returns a Result containing a collection of authorities (e.g., HashSet<String>) or an axum::response::Response on failure.
2. Apply the middleware: Use GrantsLayer::with_extractor(your_extractor_function) as a layer on your Router.

use axum::extract::Request;
use axum::response::Response;
use std::collections::HashSet;
use axum::routing::get;
use axum::Router;
use protect_axum::GrantsLayer;

// 1. Define the extractor
pub async fn extract(req: &mut Request) -> Result<HashSet<String>, Response> {
    // Implementation logic to extract authorities from request
    let mut authorities = HashSet::new();
    authorities.insert("USER_ROLE".to_string());
    Ok(authorities)
}

// 2. Add the layer to your Router
let app = Router::new()
    .route("/endpoint", get(your_handler))
    .layer(GrantsLayer::with_extractor(extract));

The procedural macro #[rocket_grants::protect] is the easiest way to secure routes. It checks if the authorities extracted by your fairing match the required permissions.

Basic Usage

Pass a string literal representing the required authority.

Advanced Logic with any, all, and expr

• any(...) / all(...): Combine multiple authority checks.
• expr: Add attribute-based access control (ABAC) by including logic based on function parameters. For example, you can ensure a user_id in the path matches the id of the user object in the request body.
• Custom Types: If your extractor returns a custom type instead of String, you can use the ty attribute (refer to the enum-role example in the repository for implementation details).

// Basic protection
#[rocket_grants::protect("OP_READ_SECURED_INFO")]
#[rocket::get("/")]
async fn macro_secured() -> &'static str {
   "ADMIN_RESPONSE"
}

// ABAC-like protection using `expr` and `any`
#[rocket_grants::protect(any("ADMIN", expr = "user.is_super_user()"))]
#[rocket::post("/secure/admin/<user_id>", data = "<user>")]
async fn admin_or_super_user(user_id: i32, user: Json<User>) -> &'static str {
   "some secured info with parameters"
}

When using the protection macros, you can specify authorization requirements using several types of conditions. The macro supports logical grouping and different ways to express authority requirements:

• String Literals: A simple string literal (e.g., "admin") checks if the user has that specific authority.
• any(...): A logical OR. The condition is met if the user has any of the specified authorities or if any of the nested expressions evaluate to true.
• all(...): A logical AND. The condition is met only if the user has all of the specified authorities or if all nested expressions evaluate to true.
• expr: Allows passing a custom Rust expression to evaluate the condition.

If multiple conditions are provided at the top level, they are treated as an all (AND) condition by default.

// Example conceptual usage of the macro logic:
#[protect(any("admin", "editor"))]
// OR
#[protect(all(any("user"), expr(is_active)))]
// OR
#[protect("super_user")]