9 releases (stable)
3.0.1 | May 29, 2024 |
---|---|
3.0.0 | Mar 31, 2024 |
2.0.1 | Mar 4, 2024 |
2.0.0 | Jan 9, 2024 |
1.0.0-beta.1 | Feb 19, 2022 |
#165 in Authentication
667 downloads per month
41KB
256 lines
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
- 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>>
- 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
- 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())
}
}
Example of ABAC-like protection and custom authority type
Here is an example using the ty
and expr
attributes. But these are independent features.
expr
allows you to include some checks in the macro based on function params, it can be combined with authorities by using all
/any
.
ty
allows you to use a custom type for th authorities (then the middleware needs to be configured).
Take a look at an enum-role example
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 ofpoem
is3.*
- For
poem-grants: 2.*
supported version ofpoem
is2.*
- For
poem-grants: 1.*
supported version ofpoem
is1.*
Dependencies
~13–24MB
~362K SLoC