Trait User

pub trait User {
    // Provided methods
    fn id(&self) -> Option<UserId> { ... }
    fn username<'a>(&'a self) -> Option<Cow<'a, str>> { ... }
    fn is_active(&self) -> bool { ... }
    fn is_authenticated(&self) -> bool { ... }
    fn last_login(&self) -> Option<DateTime<FixedOffset>> { ... }
    fn joined(&self) -> Option<DateTime<FixedOffset>> { ... }
    fn session_auth_hash(
        &self,
        secret_key: &SecretKey,
    ) -> Option<SessionAuthHash> { ... }
}

A user object that can be authenticated.

This trait is used to represent a user object that can be authenticated and is a core of the authentication system. A User object is returned by [AuthRequestExt::user()] and is used to check if a user is authenticated and to access user data. If there is no active user session, the User object returned by [AuthRequestExt::user()] is an AnonymousUser object.

A concrete instance of a User object is returned by a backend that implements the AuthBackend trait. The default backend is the DatabaseUserBackend, which stores user data in the database using Cot ORM.

Provided Methods

fn id(&self) -> Option<UserId>

Returns the user’s ID.

The ID is used to identify the user in the database or other storage. Can also be None if the user is not authenticated.

AnonymousUser always returns None.

fn username<'a>(&'a self) -> Option<Cow<'a, str>>

Returns the user’s username.

The username can be None if the user is not authenticated.

AnonymousUser always returns None.

fn is_active(&self) -> bool

Returns whether the user is active.

An active user is one that has been authenticated and is not banned or otherwise disabled. In other words, a user can be authenticated but unable to access the system.

AnonymousUser always returns false.

fn is_authenticated(&self) -> bool

Returns whether the user is authenticated.

An authenticated user is one that has been logged in and has an active session.

AnonymousUser always returns false.

fn last_login(&self) -> Option<DateTime<FixedOffset>>

Returns the user’s last login time.

This is the time when the user last logged in to the system. Can be None if the user has never logged in.

AnonymousUser always returns None.

fn joined(&self) -> Option<DateTime<FixedOffset>>

Returns the user’s join time.

This is the time when the user joined the system. Can be None if the user hasn’t been authenticated.

AnonymousUser always returns None.

fn session_auth_hash(&self, secret_key: &SecretKey) -> Option<SessionAuthHash>

Returns the user’s session authentication hash.

This used to verify that the session hash stored in the session object is valid. If the session hash is not valid, the user is logged out. For instance, DatabaseUser implements this method to generate a session hash using the user’s password hash. Therefore, when a user changes their password, the session hash is also changed, and all their sessions are invalidated.

The session auth hash should always be the same for the same secret key, unless something has changed in the user’s data that should invalidate the session (e.g. password change). Moreover, if a user implementation returns Some session hash for some secret key A, it should also return Some session hash for any other secret key B.

If this method returns None, the session hash is not checked.

AnonymousUser always returns None.

Examples

use std::borrow::Cow;

use cot::auth::{Password, SessionAuthHash, User, UserId};
use cot::config::SecretKey;
use hmac::{Hmac, Mac};
use sha2::Sha512;

struct MyUser {
    id: i64,
    password: Password,
}

type SessionAuthHmac = Hmac<Sha512>;

impl User for MyUser {
    fn id(&self) -> Option<UserId> {
        Some(UserId::Int(self.id))
    }

    fn username(&self) -> Option<Cow<'_, str>> {
        Some(Cow::from(format!("user{}", self.id)))
    }

    fn is_active(&self) -> bool {
        true
    }

    fn is_authenticated(&self) -> bool {
        true
    }

    fn session_auth_hash(&self, secret_key: &SecretKey) -> Option<SessionAuthHash> {
        // thanks to this, the session hash is invalidated when the user changes their password
        // and the user is automatically logged out

        let mut mac = SessionAuthHmac::new_from_slice(secret_key.as_bytes())
            .expect("HMAC can take key of any size");
        mac.update(self.password.as_str().as_bytes());
        let hmac_data = mac.finalize().into_bytes();

        Some(SessionAuthHash::new(&hmac_data))
    }
}

Implementors

impl User for DatabaseUser

Available on crate feature db only.

impl User for AnonymousUser