Struct Auth 

pub struct Auth<'a> {
    pub users: &'a State<Users>,
    pub cookies: &'a CookieJar<'a>,
    pub session: Option<Session>,
}

The Auth guard allows to log in, log out, sign up, modify, and delete the currently (un)authenticated user. For more information see Auth. A working example:

use rocket::{*, form::Form};
use rocket_auth2::{Users, Error, Auth, Signup, Login};

#[post("/signup", data="<form>")]
async fn signup(form: Form<Signup>, auth: Auth<'_>) {
    auth.signup(&form).await;
    auth.login(&form.into());
}

#[post("/login", data="<form>")]
fn login(form: Form<Login>, auth: Auth) {
    auth.login(&form);
}

#[post("/logout")]
fn logout(auth: Auth) {
    auth.logout();
}
#[tokio::main]
async fn main() -> Result<(), Error>{
    let users = Users::open_sqlite("mydb.db").await?;

    rocket::build()
        .mount("/", routes![signup, login, logout])
        .manage(users)
        .launch()
        .await;
    Ok(())
}

Fields

users: &'a State<Users>

Auth includes in its fields a Users instance. Therefore, it is not necessary to retrieve Users when using this guard.

cookies: &'a CookieJar<'a>

session: Option<Session>

Implementations

impl<'a> Auth<'a>

pub async fn login(&self, form: &Login) -> Result<()>

Logs in the user through a parsed form or json. The session is set to expire in one year by default. For a custom expiration date use Auth::login_for.

#[post("/login", data="<form>")]
fn login(form: Form<Login>, auth: Auth) {
    auth.login(&form);
}

pub async fn login_for(&self, form: &Login, time: Duration) -> Result<()>

Logs a user in for the specified period of time.

#[post("/login", data="<form>")]
fn login(form: Form<Login>, auth: Auth) {
    let one_hour = Duration::from_secs(60 * 60);
    auth.login_for(&form, one_hour);
}

pub async fn signup(&self, form: &Signup) -> Result<()>

Creates a new user from a form or a json. The user will not be authenticated by default. In order to authenticate the user, cast the signup form to a login form or use signup_for.

#[post("/signup", data="<form>")]
async fn signup(form: Form<Signup>, auth: Auth<'_>) -> Result<&'static str, Error>{
    auth.signup(&form).await?;
    auth.login(&form.into()).await?;
    Ok("Logged in")
}

pub async fn signup_for(&self, form: &Signup, time: Duration) -> Result<()>

Creates a new user from a form or a json. The session will last the specified period of time.

#[post("/signup", data="<form>")]
async fn signup_for(form: Form<Signup>, auth: Auth<'_>) {
    let one_hour = Duration::from_secs(60 * 60);
    auth.signup_for(&form, one_hour).await.expect("");
}

pub fn is_auth(&self) -> bool

It allows to know if the current client is authenticated or not.

#[get("/am-I-authenticated")]
fn is_auth(auth: Auth<'_>) -> &'static str {
    if auth.is_auth() {
        "Yes you are."
    } else {
        "nope."
    }
}

pub async fn get_user(&self) -> Option<User>

It retrieves the current logged user.

#[get("/display-me")]
async fn display_me(auth: Auth<'_>) -> String {
    format!("{:?}", auth.get_user().await)
}

pub fn logout(&self) -> Result<()>

Logs the currently authenticated user out.

#[post("/logout")]
fn logout(auth: Auth)  {
    auth.logout();
}

pub async fn delete(&self) -> Result<()>

Deletes the account of the currently authenticated user.

#[post("/delete-my-account")]
fn delete(auth: Auth)  {
    auth.delete();
}

pub async fn change_password( &self, password: &str, ) -> Result<(), Box<dyn Error>>

Changes the password of the currently authenticated user

    auth.change_password("new password");

pub async fn change_email(&self, email: String) -> Result<(), Error>

Changes the email of the currently authenticated user

auth.change_email("new@email.com".into());

pub fn get_session(&self) -> Result<&Session>

This method is useful when the function returns a Result type. It is intended to be used primarily with the ? operator.

auth.get_session()?;

pub async fn compare_password(&self, password: &str) -> Result<bool>

Compares the password of the currently authenticated user with another password. Useful for checking password before resetting email/password. To avoid bruteforcing this function should not be directly accessible from a route. Additionally, it is good to implement rate limiting on routes using this function.

Trait Implementations

impl<'r> FromRequest<'r> for Auth<'r>

type Error = Error

The associated error to be returned if derivation fails.

fn from_request<'life0, 'async_trait>( req: &'r Request<'life0>, ) -> Pin<Box<dyn Future<Output = Outcome<Auth<'r>, Error>> + Send + 'async_trait>>

where 'r: 'async_trait, 'life0: 'async_trait,

Derives an instance of Self from the incoming request metadata.