actix_web_grants/
lib.rs

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

actix_web_grants/
lib.rs
