1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
#![doc(
html_logo_url = "https://raw.githubusercontent.com/DDtKey/protect-endpoints/main/actix-web-grants/logo.png"
)]
//! A crate to protect your endpoints in `actix-web`.
//!
//! For built-in configure see: [`GrantsMiddleware`].
//!
//! To check user access to specific services, you can use: [`proc-macro`] and [`AuthorityGuard`] or manual.
//!
//! The library can also be integrated with third-party solutions (like [`httpauth`]), see [`authorities`] module.
//!
//! You can find more [`examples`] in the git repository.
//!
//! [`GrantsMiddleware`]: GrantsMiddleware
//! [`httpauth`]: https://docs.rs/actix-web-httpauth
//! [`examples`]: https://github.com/DDtKey/protect-endpoints/tree/main/actix-web-grants/examples
//! [`authorities`]: authorities
//! [`proc-macro`]: proc_macro
//! [`AuthorityGuard`]: AuthorityGuard
#![doc = include_str!("../README.md")]
pub mod authorities;
mod guards;
mod middleware;
pub use guards::AuthorityGuard;
pub use middleware::GrantsMiddleware;
/// Procedural macros for checking user authorities (permissions or roles).
///
/// # Examples
/// ```
/// use actix_web::{web, get, HttpResponse};
/// use actix_web_grants::protect;
/// use actix_web::http::StatusCode;
/// use actix_web::body::BoxBody;
///
/// // User should be ADMIN with OP_GET_SECRET permission
/// #[protect("ROLE_ADMIN", "OP_GET_SECRET")]
/// async fn macro_secured() -> HttpResponse {
/// HttpResponse::Ok().body("some secured info")
/// }
///
/// // User should be ADMIN and MANAGER
/// #[protect("ROLE_ADMIN", "ROLE_MANAGER")]
/// async fn role_macro_secured() -> HttpResponse {
/// HttpResponse::Ok().body("some secured info")
/// }
///
/// // Custom access denied message.
/// #[protect("ADMIN", error = "access_denied")]
/// async fn role_access() -> HttpResponse {
/// HttpResponse::Ok().body("some secured info")
/// }
/// // Non-admin role accessor will receive this response.
/// // The return type of the custom function must be `actix web::HttpResponse`.
/// fn access_denied() -> HttpResponse {
/// HttpResponse::with_body(
/// StatusCode::FORBIDDEN,
/// BoxBody::new("This resource allowed only for ADMIN"),
/// )
/// }
///
/// // Additional security condition to ensure the protection of the endpoint
/// #[protect("USER", expr = "user_id.into_inner() == user.id")]
/// #[get("/resource/{user_id}")]
/// async fn role_macro_secured_with_params(user_id: web::Path<i32>, user: web::Data<User>) -> HttpResponse {
/// HttpResponse::Ok().body("some secured info with parameters")
/// }
/// struct User { id: i32 }
///
/// // You own type is also supported (need to configure middleware for this type as well):
/// #[protect("Role::Admin", "Role::Manager", ty = "Role")]
/// async fn role_enum_macro_secured() -> HttpResponse {
/// HttpResponse::Ok().body("some secured info")
/// }
/// #[derive(Eq, PartialEq, Hash)] // required bounds
/// enum Role { Admin, Manager }
///
/// ```
#[cfg(feature = "macro-check")]
pub mod proc_macro {
pub use protect_endpoints_proc_macro::protect_actix_web as protect;
}
/// Just a shortcut for proc-macros
#[cfg(feature = "macro-check")]
pub use proc_macro::*;