actix_identity/lib.rs
1//! Identity management for Actix Web.
2//!
3//! `actix-identity` can be used to track identity of a user across multiple requests. It is built
4//! on top of HTTP sessions, via [`actix-session`](https://docs.rs/actix-session).
5//!
6//! # Getting started
7//! To start using identity management in your Actix Web application you must register
8//! [`IdentityMiddleware`] and `SessionMiddleware` as middleware on your `App`:
9//!
10//! ```no_run
11//! # use actix_web::web;
12//! use actix_web::{cookie::Key, App, HttpServer, HttpResponse};
13//! use actix_identity::IdentityMiddleware;
14//! use actix_session::{storage::RedisSessionStore, SessionMiddleware};
15//!
16//! #[actix_web::main]
17//! async fn main() {
18//! // When using `Key::generate()` it is important to initialize outside of the
19//! // `HttpServer::new` closure. When deployed the secret key should be read from a
20//! // configuration file or environment variables.
21//! let secret_key = Key::generate();
22//!
23//! let redis_store = RedisSessionStore::new("redis://127.0.0.1:6379")
24//! .await
25//! .unwrap();
26//!
27//! HttpServer::new(move || {
28//! App::new()
29//! // Install the identity framework first.
30//! .wrap(IdentityMiddleware::default())
31//! // The identity system is built on top of sessions. You must install the session
32//! // middleware to leverage `actix-identity`. The session middleware must be mounted
33//! // AFTER the identity middleware: `actix-web` invokes middleware in the OPPOSITE
34//! // order of registration when it receives an incoming request.
35//! .wrap(SessionMiddleware::new(
36//! redis_store.clone(),
37//! secret_key.clone(),
38//! ))
39//! // Your request handlers [...]
40//! # .default_service(web::to(|| HttpResponse::Ok()))
41//! })
42//! # ;
43//! }
44//! ```
45//!
46//! User identities can be created, accessed and destroyed using the [`Identity`] extractor in your
47//! request handlers:
48//!
49//! ```no_run
50//! use actix_web::{get, post, HttpResponse, Responder, HttpRequest, HttpMessage};
51//! use actix_identity::Identity;
52//! use actix_session::storage::RedisSessionStore;
53//!
54//! #[get("/")]
55//! async fn index(user: Option<Identity>) -> impl Responder {
56//! if let Some(user) = user {
57//! format!("Welcome! {}", user.id().unwrap())
58//! } else {
59//! "Welcome Anonymous!".to_owned()
60//! }
61//! }
62//!
63//! #[post("/login")]
64//! async fn login(request: HttpRequest) -> impl Responder {
65//! // Some kind of authentication should happen here
66//! // e.g. password-based, biometric, etc.
67//! // [...]
68//!
69//! // attach a verified user identity to the active session
70//! Identity::login(&request.extensions(), "User1".into()).unwrap();
71//!
72//! HttpResponse::Ok()
73//! }
74//!
75//! #[post("/logout")]
76//! async fn logout(user: Option<Identity>) -> impl Responder {
77//! if let Some(user) = user {
78//! user.logout();
79//! }
80//! HttpResponse::Ok()
81//! }
82//! ```
83//!
84//! # Advanced configuration
85//! By default, `actix-identity` does not automatically log out users. You can change this behavior
86//! by customizing the configuration for [`IdentityMiddleware`] via [`IdentityMiddleware::builder`].
87//!
88//! In particular, you can automatically log out users who:
89//! - have been inactive for a while (see [`IdentityMiddlewareBuilder::visit_deadline`]);
90//! - logged in too long ago (see [`IdentityMiddlewareBuilder::login_deadline`]).
91//!
92//! [`IdentityMiddlewareBuilder::visit_deadline`]: config::IdentityMiddlewareBuilder::visit_deadline
93//! [`IdentityMiddlewareBuilder::login_deadline`]: config::IdentityMiddlewareBuilder::login_deadline
94
95#![forbid(unsafe_code)]
96#![deny(missing_docs)]
97#![doc(html_logo_url = "https://actix.rs/img/logo.png")]
98#![doc(html_favicon_url = "https://actix.rs/favicon.ico")]
99#![cfg_attr(docsrs, feature(doc_auto_cfg))]
100
101pub mod config;
102pub mod error;
103mod identity;
104mod identity_ext;
105mod middleware;
106
107pub use self::{identity::Identity, identity_ext::IdentityExt, middleware::IdentityMiddleware};