poem-grants

Authorization extension for poem to protect your endpoints.

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

The library can also be integrated with third-party solutions or your custom middlewares (like jwt-auth example).

NOTE: Even under beta flag it's ready-to-use library. However, I'm going to prepare large update of whole *-grants ecosystem with additional features soon.

How to use

1. Declare your own authorities extractor

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

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

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

Route::new()
    .at("/endpoint", your_endpoint)
    .with(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-auth example

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

Example of proc-macro way protection

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

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

Example of manual way protection

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

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

Supported poem versions

• For poem-grants: 3.* supported version of poem is 3.*
• For poem-grants: 2.* supported version of poem is 2.*
• For poem-grants: 1.* supported version of poem is 1.*