actix_web_grants/
lib.rs

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

actix_web_grants/
lib.rs
