    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
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108

    /*!
    Identity management for Actix Web.

    `actix-identity` can be used to track identity of a user across multiple requests. It is built
    on top of HTTP sessions, via [`actix-session`](https://docs.rs/actix-session).

    # Getting started
    To start using identity management in your Actix Web application you must register
    [`IdentityMiddleware`] and `SessionMiddleware` as middleware on your `App`:

    ```no_run
    # use actix_web::web;
    use actix_web::{cookie::Key, App, HttpServer, HttpResponse};
    use actix_identity::IdentityMiddleware;
    use actix_session::{storage::RedisSessionStore, SessionMiddleware};

    #[actix_web::main]
    async fn main() {
        // When using `Key::generate()` it is important to initialize outside of the
        // `HttpServer::new` closure. When deployed the secret key should be read from a
        // configuration file or environment variables.
        let secret_key = Key::generate();

        let redis_store = RedisSessionStore::new("redis://127.0.0.1:6379")
            .await
            .unwrap();

        HttpServer::new(move || {
            App::new()
                // Install the identity framework first.
                .wrap(IdentityMiddleware::default())
                // The identity system is built on top of sessions. You must install the session
                // middleware to leverage `actix-identity`. The session middleware must be mounted
                // AFTER the identity middleware: `actix-web` invokes middleware in the OPPOSITE
                // order of registration when it receives an incoming request.
                .wrap(SessionMiddleware::new(
                     redis_store.clone(),
                     secret_key.clone(),
                ))
                // Your request handlers [...]
                # .default_service(web::to(|| HttpResponse::Ok()))
        })
    # ;
    }
    ```

    User identities can be created, accessed and destroyed using the [`Identity`] extractor in your
    request handlers:

    ```no_run
    use actix_web::{get, post, HttpResponse, Responder, HttpRequest, HttpMessage};
    use actix_identity::Identity;
    use actix_session::storage::RedisSessionStore;

    #[get("/")]
    async fn index(user: Option<Identity>) -> impl Responder {
        if let Some(user) = user {
            format!("Welcome! {}", user.id().unwrap())
        } else {
            "Welcome Anonymous!".to_owned()
        }
    }

    #[post("/login")]
    async fn login(request: HttpRequest) -> impl Responder {
        // Some kind of authentication should happen here
        // e.g. password-based, biometric, etc.
        // [...]

        // attach a verified user identity to the active session
        Identity::login(&request.extensions(), "User1".into()).unwrap();

        HttpResponse::Ok()
    }

    #[post("/logout")]
    async fn logout(user: Identity) -> impl Responder {
        user.logout();
        HttpResponse::Ok()
    }
    ```

    # Advanced configuration
    By default, `actix-identity` does not automatically log out users. You can change this behaviour
    by customising the configuration for [`IdentityMiddleware`] via [`IdentityMiddleware::builder`].

    In particular, you can automatically log out users who:
    - have been inactive for a while (see [`IdentityMiddlewareBuilder::visit_deadline`];
    - logged in too long ago (see [`IdentityMiddlewareBuilder::login_deadline`]).

    [`IdentityMiddlewareBuilder::visit_deadline`]: config::IdentityMiddlewareBuilder::visit_deadline
    [`IdentityMiddlewareBuilder::login_deadline`]: config::IdentityMiddlewareBuilder::login_deadline
    */

    #![forbid(unsafe_code)]
    #![deny(rust_2018_idioms, nonstandard_style, missing_docs)]
    #![warn(future_incompatible)]
    #![doc(html_logo_url = "https://actix.rs/img/logo.png")]
    #![doc(html_favicon_url = "https://actix.rs/favicon.ico")]
    #![cfg_attr(docsrs, feature(doc_auto_cfg))]

    pub mod config;
    pub mod error;
    mod identity;
    mod identity_ext;
    mod middleware;

    pub use self::{identity::Identity, identity_ext::IdentityExt, middleware::IdentityMiddleware};