DEV Community: Harry Gill

Auth Web Microservice with rust using Actix-Web - Complete Tutorial Part 2

Harry Gill — Tue, 30 Oct 2018 09:21:27 +0000

Originally posted on gill.net.in

This post is outdated now please read the updated version Auth Web Microservice with rust using Actix-Web 1.0 - Complete Tutorial

Welcome back to part 2 of the tutorial

In part one we have successfully setup bulk base of our Auth microservice. Congratulations if you have your app running and no errors so far. Checkout Part One if you haven't already. Complete code for this tutorial is on Gitlab master branch.

Verify User Email or not?

Picking up from part one, we now have as server that takes an email address from a request and spits out a JSON response with an invitation object. In part one I said that we will send an email to the user, after some thought and feedback, we will be skipping this part now (look out for part 3). The service that I use is sparkpost and you as the reader of this tutorial may not have an account with them(which is free for small usage).

WARNING: Do not use this workaround in any real app without proper email verification.

Workaround

For now we will use the http response from the server to verify the email so to speak. The simplest way of creating an email verification is to have our server to use some sort of secret sent via the email to the user email and have them click an link with the secret to verify. We could use the UUID from the invitation object as a secret. Let's say the client gets an invitation after entering their email with uuid 67a68837-a059-43e6-a0b8-6e57e6260f0d.

We can send a request to register a new user with the above UUID in the url. Our server can take that id and find the Invitation object in the database and then compare the expiry date with current time. If all of these conditions are true we would let the user register, otherwise send an error response back. For now we will return the Invitation Object to the client as a workaround. Email support will get implemented next in Part 3.

Error handling and the `From` trait

Rust provides use with really powerful tools that we can use to convert one type of error to another. In this app we will be doing a few operations using different carets i.e. saving data with diesel, hashing password with bcrypt etc. These operations may return errors but we need to convert them to our custom error type. std::convert::From is a trait that allows us to convert that. Read more about the From trait here. By implementing the From trait we can use the ? operator to propagate errors of many different types that would get converted to our ServiceError type.

Our error is defined in the errors.rs, let's implement some From traits by adding impls for From uuid and diesel errors, we will also add a Unauthorized variant to our ServiceError enum. the file look like the following:

// errors.rs
use actix_web::{error::ResponseError, HttpResponse};
use std::convert::From;
use diesel::result::{DatabaseErrorKind, Error};
use uuid::ParseError;


#[derive(Fail, Debug)]
pub enum ServiceError {
    #[fail(display = "Internal Server Error")]
    InternalServerError,

    #[fail(display = "BadRequest: {}", _0)]
    BadRequest(String),

    #[fail(display = "Unauthorized")]
    Unauthorized,
}

// impl ResponseError trait allows to convert our errors into http responses with appropriate data
impl ResponseError for ServiceError {
    fn error_response(&self) -> HttpResponse {
        match *self {
            ServiceError::InternalServerError => HttpResponse::InternalServerError().json("Internal Server Error, Please try later"),
            ServiceError::BadRequest(ref message) => HttpResponse::BadRequest().json(message),
            ServiceError::Unauthorized => HttpResponse::Unauthorized().json("Unauthorized")
        }
    }
}

// we can return early in our handlers if UUID provided by the user is not valid
// and provide a custom message
impl From<ParseError> for ServiceError {
    fn from(_: ParseError) -> ServiceError {
        ServiceError::BadRequest("Invalid UUID".into())
    }
}

impl From<Error> for ServiceError {
    fn from(error: Error) -> ServiceError {
        // Right now we just care about UniqueViolation from diesel
        // But this would be helpful to easily map errors as our app grows
        match error {
            Error::DatabaseError(kind, info) => {
                if let DatabaseErrorKind::UniqueViolation = kind {
                    let message = info.details().unwrap_or_else(|| info.message()).to_string();
                    return ServiceError::BadRequest(message);
                }
                ServiceError::InternalServerError
            }
            _ => ServiceError::InternalServerError
        }
    }
}

Great! this will all become handy as we go.

Get some help

We all need some help at times. We will need to hash the password before we store it in the DB. There was a suggestion on Reddit rust community abut what algorithm to use. argon2 was suggested here. I agree with the suggestion but for the sake of simplicity I have decided to use bcrypt. BTW bcrypt algorithm is a widely used in production, and the bcrypt crate provides a really nice interface to hash and verify passwords.

To keep some concerns separate we create a new file src/utils.rs and define a helper hashing function as following.

//utils.rs
use bcrypt::{hash, DEFAULT_COST};
use errors::ServiceError;
use std::env;

pub fn hash_password(plain: &str) -> Result<String, ServiceError> {
    // get the hashing cost from the env variable or use default
    let hashing_cost: u32 = match env::var("HASH_ROUNDS") {
        Ok(cost) => cost.parse().unwrap_or(DEFAULT_COST),
        _ => DEFAULT_COST,
    };
    hash(plain, hashing_cost).map_err(|_| ServiceError::InternalServerError)
}

You may have noticed that we return a Result and use map_error() to return our custom error. This is to allow using the ? operator later when we call this function (Another way to convert error is to implement From trait for the error returned by bcrypt function, instead).

While we are at it, lets add a convenience method to our User struct defined in models.rs in the last tutorial. We also removing the remove_pwd() method, instead we will define another struct SlimUser that does not have the password field. We impl From trait to generate SlimUser from the user. It will all become clear as we get to use this in a while.

use chrono::{NaiveDateTime, Local};
use std::convert::From;
//... snip
impl User {
    pub fn with_details(email: String, password: String) -> Self {
        User {
            email,
            password,
            created_at: Local::now().naive_local(),
        }
    }
}
//--snip
#[derive(Debug, Serialize, Deserialize)]
pub struct SlimUser {
    pub email: String,
}

impl From<User> for SlimUser {
    fn from(user: User) -> Self {
        SlimUser {
           email: user.email
        }
    }
}

Don't forget to add extern crate bcrypt; and mod utils in your main.rs.
Another neat thing I forgot in the part one was logging to console. To enable it add the following to the main.rs

extern crate env_logger;
// --snip

fn main(){
    dotenv().ok();
    std::env::set_var("RUST_LOG", "simple-auth-server=debug,actix_web=info");
    env_logger::init();
    //--snip
}

Registering User

If you remember from the previous tutorial, we created a handler for Invitation now let's create a handler for registering a user. We are going to create a struct RegisterUser with some data that allows us to verify the Invitation and then create and return a user from the database.

Create a new file src/register_handler.rs and add mod register_handler; to you main.rs.

// register_handler.rs
use actix::{Handler, Message};
use chrono::Local;
use diesel::prelude::*;
use errors::ServiceError;
use models::{DbExecutor, Invitation, User, SlimUser};
use uuid::Uuid;
use utils::hash_password;

// UserData is used to extract data from a post request by the client
#[derive(Debug, Deserialize)]
pub struct UserData {
    pub password: String,
}

// to be used to send data via the Actix actor system
#[derive(Debug)]
pub struct RegisterUser {
    pub invitation_id: String,
    pub password: String,
}


impl Message for RegisterUser {
    type Result = Result<SlimUser, ServiceError>;
}


impl Handler<RegisterUser> for DbExecutor {
    type Result = Result<SlimUser, ServiceError>;
    fn handle(&mut self, msg: RegisterUser, _: &mut Self::Context) -> Self::Result {
        use schema::invitations::dsl::{invitations, id};
        use schema::users::dsl::users;
        let conn: &PgConnection = &self.0.get().unwrap();

        // try parsing the string provided by the user as url parameter
        // return early with error that will be converted to ServiceError
        let invitation_id = Uuid::parse_str(&msg.invitation_id)?;

        invitations.filter(id.eq(invitation_id))
            .load::<Invitation>(conn)
            .map_err(|_db_error| ServiceError::BadRequest("Invalid Invitation".into()))
            .and_then(|mut result| {
                if let Some(invitation) = result.pop() {
                    // if invitation is not expired
                    if invitation.expires_at > Local::now().naive_local() {
                        // try hashing the password, else return the error that will be converted to ServiceError
                        let password: String = hash_password(&msg.password)?;
                        let user = User::with_details(invitation.email, password);
                        let inserted_user: User = diesel::insert_into(users)
                            .values(&user)
                            .get_result(conn)?;

                        return Ok(inserted_user.into()); // convert User to SlimUser
                    }
                }
                Err(ServiceError::BadRequest("Invalid Invitation".into()))
            })
    }
}

Parsing url parameters

actix-web has many easy ways to extract data from a request.

One of the way is to use Path extractor.

Path provides information that can be extracted from the Request’s path. You can deserialize any variable segment from the path.

This will allow us to create a unique path for every invitation to be register as a user.

Let's modify our register route in the app.rs file, and add a handler function that we will implement later.

// app.rs
/// creates and returns the app after mounting all routes/resources
// add use statement at the top.
use register_routes::register_user;
//...snip
pub fn create_app(db: Addr<DbExecutor>) -> App<AppState> {
    App::with_state(AppState { db })
        //... snip
        // routes to register as a user
        .resource("/register/{invitation_id}", |r| {
           r.method(Method::POST).with(register_user);
        })

}

You may want to comment the changes out for now as things are not implemented and keep your app compiled and running. (I do that whenever possible, for continuous feedback).

All we need now is to implement that register_user() function that extracts the data from request sent by the client, invoke the handler by sending RegisterUser message to the Actor. Apart from the url parameter we also need to extract password from the client. We have already created a UserData struct in register_handler.rs for that purpose. We will ues the type Json to create UserData struct.

Json allows to deserialize a request body into a struct. To extract typed information from a request’s body, the type T must implement the Deserialize trait from serde.

Create a new file src/register_routes.rs and add mod register_routes; to you main.rs.

use actix_web::{AsyncResponder, FutureResponse, HttpResponse, ResponseError, State, Json, Path};
use futures::future::Future;

use app::AppState;
use register_handler::{RegisterUser, UserData};


pub fn register_user((invitation_id, user_data, state): (Path<String>, Json<UserData>, State<AppState>))
                     -> FutureResponse<HttpResponse> {
    let msg = RegisterUser {
        // into_inner() returns the inner string value from Path
        invitation_id: invitation_id.into_inner(),
        password: user_data.password.clone(),
    };

    state.db.send(msg)
        .from_err()
        .and_then(|db_response| match db_response {
            Ok(slim_user) => Ok(HttpResponse::Ok().json(slim_user)),
            Err(service_error) => Ok(service_error.error_response()),
        }).responder()
}

Test your implementation

After taking care of the errors if you had any, lets give it a spin.
invoking

curl --request POST \
  --url http://localhost:3000/invitation \
  --header 'content-type: application/json' \
  --data '{
    "email":"name@domain.com"
}'

Should return something like

{
    "id": "f87910d7-0e33-4ded-a8d8-2264800d1783",
    "email": "name@domain.com",
    "expires_at": "2018-10-27T13:02:00.909757"
}

Imagine that we sent an email to the user by creating a link that takes to a form for the user to fill. From there we would have our client post a request to http://localhost:3000/register/f87910d7-0e33-4ded-a8d8-2264800d1783. For the sake of this demo you can test your app with the following test command.

curl --request POST \
  --url http://localhost:3000/register/f87910d7-0e33-4ded-a8d8-2264800d1783 \
  --header 'content-type: application/json' \
  --data '{"password":"password"}'

Which should return something like

{
    "email": "name@domain.com"
}

Running the command again would result with an error

 "Key (email)=(name@domain.com) already exists."

Congratulations now you have a web service that can invite, verify and create a user and even send you a semi useful error message. 🎉🎉

Let's do Auth

According to w3.org:

The general concept behind a token-based authentication system is simple. Allow users to enter their username and password in order to obtain a token which allows them to fetch a specific resource - without using their username and password. Once their token has been obtained, the user can offer the token - which offers access to a specific resource for a time period - to the remote site.

Now how you choose to exchange that token can have security implications. You will find many discussions/debates around the internet and many ways that people use. I am very wary of storing things on client side that can be accessed by the client side JavaScript. Unfortunately this approach is suggested in thousands of tutorial everywhere. Here is a good read Stop using JWT for sessions.

I am not sure here, what to suggest you as the reader, apart from don't follow online tutorials blindly and do your own research. The purpose of this tutorial is to learn about Actix-web and rust not how to prevent your server from vulnerabilities. For the sake of this tutorial we will be using http only cookies to exchange tokens.

PLEASE DO NOT USE IN PRODUCTION.

Now that is out of the way 😰, let's see what we can do here. actix-web provides us with a neat way as middleware of handling a session cookie documented here actix_web::middleware::identity. To enable this functionality we modify our app.rs file as following.

use actix_web::middleware::identity::{CookieIdentityPolicy, IdentityService};
use chrono::Duration;
//--snip
pub fn create_app(db: Addr<DbExecutor>) -> App<AppState> {
    // secret is a random 32 character long base 64 string
    let secret: String = std::env::var("SECRET_KEY").unwrap_or_else(|_| "0".repeat(32));
    let domain: String = std::env::var("DOMAIN").unwrap_or_else(|_| "localhost".to_string());

    App::with_state(AppState { db })
        .middleware(Logger::default())
        .middleware(IdentityService::new(
            CookieIdentityPolicy::new(secret.as_bytes())
                .name("auth")
                .path("/")
                .domain(domain.as_str())
                .max_age(Duration::days(1)) // just for testing
                .secure(false),
        ))
        //--snip
}

This gives us very convenient methods like req.remember(data), req.identity() and req.forget() etc on HttpRequest prams in our route functions. That in turn will set and remove the auth cookie from client.

JWT?

While writing this tutorial I ran into a few discussions about What JWT lib to use. From a simple search I found a few, and decided to go with frank_jwt but then Vincent Prouillet Pointed out the incompleteness and suggested to go with jsonwebtoken. After having trouble with using the lib I got a great response from them. Now the repo has working examples and I was able to implement the following default solution. Please note this is not the most secure implementation of JWT you might want to look up resources for making it better suit your needs.

Before we create auth handler and route function, let's add some helper functions to our util.rs for jwt encoding and decoding. Don't forget to add extern crate jsonwebtoken as jwt; in your main.rs.

I Will gladly accept a PR if someone has a better implementation.

// utils.rs
use models::SlimUser;
use std::convert::From;
use jwt::{decode, encode, Header, Validation};
use chrono::{Local, Duration};
//--snip

#[derive(Debug, Serialize, Deserialize)]
struct Claims {
    // issuer
    iss: String,
    // subject
    sub: String,
    //issued at
    iat: i64,
    // expiry
    exp: i64,
    // user email
    email: String,
}

// struct to get converted to token and back
impl Claims {
    fn with_email(email: &str) -> Self {
        Claims {
            iss: "localhost".into(),
            sub: "auth".into(),
            email: email.to_owned(),
            iat: Local::now().timestamp(),
            exp: (Local::now() + Duration::hours(24)).timestamp(),
        }
    }
}

impl From<Claims> for SlimUser {
    fn from(claims: Claims) -> Self {
        SlimUser { email: claims.email }
    }
}

pub fn create_token(data: &SlimUser) -> Result<String, ServiceError> {
    let claims = Claims::with_email(data.email.as_str());
    encode(&Header::default(), &claims, get_secret().as_ref())
        .map_err(|_err| ServiceError::InternalServerError)
}

pub fn decode_token(token: &str) -> Result<SlimUser, ServiceError> {
    decode::<Claims>(token, get_secret().as_ref(), &Validation::default())
        .map(|data| Ok(data.claims.into()))
        .map_err(|_err| ServiceError::Unauthorized)?
}

// take a string from env variable
fn get_secret() -> String {
    env::var("JWT_SECRET").unwrap_or("my secret".into())
}

Auth Handling

You know the drill now 😉, lets create a new file src/auth_handler.rs and add mod auth_handler; to you main.rs.

//auth_handler.rs
use actix::{Handler, Message};
use diesel::prelude::*;
use errors::ServiceError;
use models::{DbExecutor, User, SlimUser};
use bcrypt::verify;
use actix_web::{FromRequest, HttpRequest, middleware::identity::RequestIdentity};

#[derive(Debug, Deserialize)]
pub struct AuthData {
    pub email: String,
    pub password: String,
}

impl Message for AuthData {
    type Result = Result<SlimUser, ServiceError>;
}


impl Handler<AuthData> for DbExecutor {
    type Result = Result<SlimUser, ServiceError>;
    fn handle(&mut self, msg: AuthData, _: &mut Self::Context) -> Self::Result {
        use schema::users::dsl::{users, email};
        let conn: &PgConnection = &self.0.get().unwrap();
        let mismatch_error = Err(ServiceError::BadRequest("Username and Password don't match".into()));

        let mut items = users
            .filter(email.eq(&msg.email))
            .load::<User>(conn)?;

        if let Some(user) = items.pop() {
            match verify(&msg.password, &user.password) {
                Ok(matching) => {
                    if matching { return Ok(user.into()); } else { return mismatch_error; }
                }
                Err(_) => { return mismatch_error; }
            }
        }
        mismatch_error
    }
}

Handler above takes the AuthData struct that contains email and password sent by the client. We use the email to extract user from the db and use bcrypt verify function to match the password. If all goes well we return the user or we return BadRequest error.

Now let's also create src/auth_routes.rs with the following content:

// auth_routes.rs
use actix_web::{AsyncResponder, FutureResponse, HttpResponse, HttpRequest, ResponseError, Json};
use actix_web::middleware::identity::RequestIdentity;
use futures::future::Future;
use utils::create_token;

use app::AppState;
use auth_handler::AuthData;

pub fn login((auth_data, req): (Json<AuthData>, HttpRequest<AppState>))
             -> FutureResponse<HttpResponse> {
    req.state()
        .db
        .send(auth_data.into_inner())
        .from_err()
        .and_then(move |res| match res {
            Ok(slim_user) => {
                let token = create_token(&slim_user)?;
                req.remember(token);
                Ok(HttpResponse::Ok().into())
            }
            Err(err) => Ok(err.error_response()),
        }).responder()
}

pub fn logout(req: HttpRequest<AppState>) -> HttpResponse {
    req.forget();
    HttpResponse::Ok().into()
}

Our login method extracts the AuthData from request and sends a message to DbEexcutor Actor handler which we implemented in auth_handler.rs. Here if all is good we get a user returned to us, We use our helper function that we defined earlier in utils.rs to create a token and call req.remember(token). This in turn sets a cookie header with token for the client to save.

Last thing we need to do now is use login/logout function in our app.rs. Change the .rsource("/auth") closure to following:

.resource("/auth", |r| {
            r.method(Method::POST).with(login);
            r.method(Method::DELETE).with(logout);
        })

Don't forget to add use auth_routes::{login, logout}; at the top of the file though.

Test run Auth

If you have been following the tutorial, you have already created a user with email and password. Use the following curl command to test our server.

curl -i --request POST \
  --url http://localhost:3000/auth \
  --header 'content-type: application/json' \
  --data '{
        "email": "name@domain.com",
        "password":"password"
}'

## response
HTTP/1.1 200 OK
set-cookie: auth=iqsB4KUUjXUjnNRl1dVx9lKiRfH24itiNdJjTAJsU4CcaetPpaSWfrNq6IIoVR5+qKPEVTrUeg==; HttpOnly; Path=/; Domain=localhost; Max-Age=86400
content-length: 0
date: Sun, 28 Oct 2018 12:36:43 GMT

If you received a 200 response like above with a set-cookie header, Congratulations you have successfully logged in.

To test the logout we send a DELETE request to the /auth, make sure you get set-cookie header with empty data and immediate expiry date.

curl -i --request DELETE \
  --url http://localhost:3000/auth

## response
HTTP/1.1 200 OK
set-cookie: auth=; HttpOnly; Path=/; Domain=localhost; Max-Age=0; Expires=Fri, 27 Oct 2017 13:01:52 GMT
content-length: 0
date: Sat, 27 Oct 2018 13:01:52 GMT

Implementing a protected route

The whole point of having Auth is to have way to verify a request is coming from a authenticated client. Actix-web has a trait FromRequest that we can implement on any type and then use that to extract data from the request. See documentation here. We will add the following at the bottom of auth_handler.rs.

//auth_handler.rs
//--snip
use actix_web::FromRequest;
use utils::decode_token;
//--snip

// we need the same data as SlimUser
// simple aliasing makes the intentions clear and its more readable
pub type LoggedUser = SlimUser;

impl<S> FromRequest<S> for LoggedUser {
    type Config = ();
    type Result = Result<LoggedUser, ServiceError>;
    fn from_request(req: &HttpRequest<S>, _: &Self::Config) -> Self::Result {
        if let Some(identity) = req.identity() {
            let user: SlimUser = decode_token(&identity)?;
            return Ok(user as LoggedUser);
        }
        Err(ServiceError::Unauthorized)
    }
}

We chose to use a type alias rather that creating a whole new type. When we extract LoggedUser from a request reader would know that its is the authenticated user. FromRequest trait simply tries to Deserialize the string from the cookie into our struct and if that fails it simply returns Unauthorized error back. To test this we need to add an actual route to or app. We simply add another function to auth_routes.rs

//auth_routes.rs
//--snip

pub fn get_me(logged_user: LoggedUser) -> HttpResponse {
    HttpResponse::Ok().json(logged_user)
}

To call this we register this method in app.rs resources. It would look like following.

//app.rs
use auth_routes::{login, logout, get_me};
//--snip

.resource("/auth", |r| {
    r.method(Method::POST).with(login);
    r.method(Method::DELETE).with(logout);
    r.method(Method::GET).with(get_me);
})
//--snip

Testing logged in user

Try the following Curl command in the terminal.

curl -i --request POST \
  --url http://localhost:3000/auth \
  --header 'content-type: application/json' \
  --data '{
        "email": "name@domain.com",
        "password":"password"
}'
# result would be something like
HTTP/1.1 200 OK
set-cookie: auth=HdS0iPKTBL/4MpTmoUKQ5H7wft5kP7OjP6vbyd05Ex5flLvAkKd+P2GchG1jpvV6p9GQtzPEcg==; HttpOnly; Path=/; Domain=localhost; Max-Age=86400
content-length: 0
date: Sun, 28 Oct 2018 19:16:12 GMT

## and then pass the cookie back for a get request
curl -i --request GET \
  --url http://localhost:3000/auth \
  --cookie auth=HdS0iPKTBL/4MpTmoUKQ5H7wft5kP7OjP6vbyd05Ex5flLvAkKd+P2GchG1jpvV6p9GQtzPEcg==
## result
HTTP/1.1 200 OK
content-length: 27
content-type: application/json
date: Sun, 28 Oct 2018 19:21:04 GMT

{"email":"name@domain.com"}

It should successfully return your email as json back. Only logged in users or requests with a valid auth cookie and token will pass through the routes you extract the LoggedUser.

What's next?

In Part 3 of this tutorial we will create the email verification and a frontend for this app. I wold like to use some sort of rust html templating system for that. At the same time I'm learning Angular so I might slap a small angular app at the front of it.
Get in touch with me on twitter if you have a question or suggestion about any of it.

Auth Web Microservice with rust using Actix-Web - Complete Tutorial Part 1

Harry Gill — Mon, 22 Oct 2018 15:36:10 +0000

This post is outdated now please read the updated version Auth Web Microservice with rust using Actix-Web 1.0 - Complete Tutorial

What?

We are going to create a web-server in rust that only deals with user registration and authentication. I will be explaining the steps in each file as we go. The complete project code is here repo. Please take all this with a pinch of salt as I'm a still a noob to rust 😉.

Flow of the event would look like this:

Registers with email address ➡ Receive an 📨 with a link to verify
Follow the link ➡ register with same email and a password
Login with email and password ➡ Get verified and receive jwt token

Crates we are going to use

actix // Actix is a Rust actors framework.
actix-web // Actix web is a simple, pragmatic and extremely fast web framework for Rust.
brcypt // Easily hash and verify passwords using bcrypt.
chrono // Date and time library for Rust.
diesel // A safe, extensible ORM and Query Builder for PostgreSQL, SQLite, and MySQL.
dotenv // A dotenv implementation for Rust.
env_logger // A logging implementation for log which is configured via an environment variable.
failure // Experimental error handling abstraction.
jsonwebtoken // Create and parse JWT in a strongly typed way.
futures // An implementation of futures and streams featuring zero allocations, composability, and iterator-like interfaces.
r2d2 // A generic connection pool.
serde // A generic serialization/deserialization framework.
serde_json // A JSON serialization file format.
serde_derive // Macros 1.1 implementation of #[derive(Serialize, Deserialize)].
sparkpost // Rust bindings for sparkpost email api v1.
uuid // A library to generate and parse UUIDs.

I have provided a brief info about the crates in use from their official description. If you want to know more about any of these crates please click on the name to go to crates.io. Shameless plug: sparkpost is my crate please leave feedback if you like/dislike it.

Prerequisite

I will assume here that you have some knowledge of programming, preferably some rust as well. A working setup of rust is required. Checkout https://rustup.rs for esasy rust setup. To know more about rust checkout
The Book.

We will be using diesel to create models and deal with database, queries and migrations. Pleas head over to http://diesel.rs/guides/getting-started/ to get started and setup diesel_cli. In this tutorial we will be using postgresql so follow the instructions to setup for postgres. You need to have a running postgres server and can create a database to follow this tutorial through. Another nice to have tool is Cargo Watch that lets you watch the file system and re-compile and re-run the app when you make any changes.

Install Curl if don't have it already on your system for testing the api locally.

Let's Begin

After checking your rust and cargo version and creating a new project with

# at the time of writing this tutorial my setup is 
rustc --version && cargo --version
# rustc 1.29.1 (b801ae664 2018-09-20)
# cargo 1.29.0 (524a578d7 2018-08-05)

cargo new simple-auth-server
# Created binary (application) `simple-auth-server` project

cd simple-auth-server # and then 

# watch for changes re-compile and run
cargo watch -x run

Fill in the cargo dependencies with the following, I will go through each of them as get used in the project. I am using explicit versions of the crates, as you know things get old and change.(in case you are reading this tutorial after a long time it was created). In part 1 of this tutorial we won't be using all of them but they will all become handy in the final app.

[dependencies]
actix = "0.7.4"
actix-web = "0.7.8"
bcrypt = "0.2.0"
chrono = { version = "0.4.6", features = ["serde"] }
diesel = { version = "1.3.3", features = ["postgres", "uuid", "r2d2", "chrono"] }
dotenv = "0.13.0"
env_logger = "0.5.13"
failure = "0.1.2"
frank_jwt = "3.0"
futures = "0.1"
r2d2 = "0.8.2"
serde_derive="1.0.79"
serde_json="1.0"
serde="1.0"
sparkpost = "0.4"
uuid = { version = "0.6.5", features = ["serde", "v4"] }

Setup The Base APP

Create new files src/models.rs src/app.rs.

// models.rs
use actix::{Actor, SyncContext};
use diesel::pg::PgConnection;
use diesel::r2d2::{ConnectionManager, Pool};

/// This is db executor actor. can be run in parallel
pub struct DbExecutor(pub Pool<ConnectionManager<PgConnection>>);


// Actors communicate exclusively by exchanging messages. 
// The sending actor can optionally wait for the response. 
// Actors are not referenced directly, but by means of addresses.
// Any rust type can be an actor, it only needs to implement the Actor trait.
impl Actor for DbExecutor {
    type Context = SyncContext<Self>;
}

To use this Actor we need to set up actix-web server. We have the following in src/app.rs. We are leaving the resource builders empty for now. This is where the meat of the routing is going to go.

// app.rs
use actix::prelude::*;
use actix_web::{http::Method, middleware, App};
use models::DbExecutor;

pub struct AppState {
    pub db: Addr<DbExecutor>,
}

// helper function to create and returns the app after mounting all routes/resources
pub fn create_app(db: Addr<DbExecutor>) -> App<AppState> {
    App::with_state(AppState { db })
        // setup builtin logger to get nice logging for each request
        .middleware(middleware::Logger::new("\"%r\" %s %b %Dms"))

         // routes for authentication
        .resource("/auth", |r| {
        })
        // routes to invitation
        .resource("/invitation/", |r| {
        })
        // routes to register as a user after the
        .resource("/register/", |r| {
        })
}

// main.rs
// to avoid the warning from diesel macros
#![allow(proc_macro_derive_resolution_fallback)]

extern crate actix;
extern crate actix_web;
extern crate serde;
extern crate chrono;
extern crate dotenv;
extern crate futures;
extern crate r2d2;
extern crate uuid;
#[macro_use] extern crate diesel;
#[macro_use] extern crate serde_derive;
#[macro_use] extern crate failure;

mod app;
mod models;
mod schema;
// mod errors;
// mod invitation_handler;
// mod invitation_routes;

use models::DbExecutor;
use actix::prelude::*;
use actix_web::server;
use diesel::{r2d2::ConnectionManager, PgConnection};
use dotenv::dotenv;
use std::env;


fn main() {
    dotenv().ok();
    let database_url = env::var("DATABASE_URL").expect("DATABASE_URL must be set");
    let sys = actix::System::new("Actix_Tutorial");

    // create db connection pool
    let manager = ConnectionManager::<PgConnection>::new(database_url);
    let pool = r2d2::Pool::builder()
        .build(manager)
        .expect("Failed to create pool.");

    let address :Addr<DbExecutor>  = SyncArbiter::start(4, move || DbExecutor(pool.clone()));

    server::new(move || app::create_app(address.clone()))
        .bind("127.0.0.1:3000")
        .expect("Can not bind to '127.0.0.1:3000'")
        .start();

    sys.run();
}

At this stage your server should compile and run on 127.0.0.1:3000. It doesn't do anything useful for now. Let's create some Models.

Setting up Diesel and creating our user Model

We start with creating a model for the user. Assuming from the previous steps you have postgres and diesel-cli installed and working. In your terminal echo DATABASE_URL=postgres://username:password@localhost/database_name > .env replace database_name, username and password as you have setup. Then we run diesel setup in the terminal. This will create our database if didn't exist and setup a migration directory etc.

Let's write some SQL, shall we. Create migrations by diesel migration generate users and invitation diesel migration generate invitations. Open the up.sql and down.sql files in migrations folder and add with following sql respectively.


--migrations/TIMESTAMP_users/up.sql
CREATE TABLE users (
  email VARCHAR(100) NOT NULL PRIMARY KEY,
  password VARCHAR(64) NOT NULL, --bcrypt hash
  created_at TIMESTAMP NOT NULL
);

--migrations/TIMESTAMP_users/down.sql
DROP TABLE users;

--migrations/TIMESTAMP_invitations/up.sql
CREATE TABLE invitations (
  id UUID NOT NULL PRIMARY KEY,
  email VARCHAR(100) NOT NULL,
  expires_at TIMESTAMP NOT NULL
);

--migrations/TIMESTAMP_invitations/down.sql
DROP TABLE invitations;

Command diesel migration run will create the table in the DB and a file src/schema.rs. This is the extent I will go about diesel-cli and migrations. Please read their documentation to learn more.

At this stage we have created the tables in the db, let's write some code to create a representation of user and invitation in rust. In models.rs we add the following.

// models.rs
...
// --- snip
use chrono::NaiveDateTime;
use uuid::Uuid;
use schema::{users,invitations};

#[derive(Debug, Serialize, Deserialize, Queryable, Insertable)]
#[table_name = "users"]
pub struct User {
    pub email: String,
    pub password: String,
    pub created_at: NaiveDateTime, // only NaiveDateTime works here due to diesel limitations
}

impl User {
    // this is just a helper function to remove password from user just before we return the value out later
    pub fn remove_pwd(mut self) -> Self {
        self.password = "".to_string();
        self
    }
}

#[derive(Debug, Serialize, Deserialize, Queryable, Insertable)]
#[table_name = "invitations"]
pub struct Invitation {
    pub id: Uuid,
    pub email: String,
    pub expires_at: NaiveDateTime,
}

Check your implementation is free from errors/warnings and keep an eye on cargo watch -x run command in the terminal.

Introducing 'sparkpost' a Rust Crate for email API

Harry Gill — Tue, 16 Oct 2018 09:33:56 +0000

Rust is an enjoyable language, and I have been experimenting with it for a some time. I started with creating a few web servers using different crates including rocket and actix. I needed to use an email api to send messages from the backend to either myself or the user.

I have used Sparkpost as an email service for such purpose in some of my nodejs apps. Having not found any rust API lib for it I decided to create one for myself. It is available on https://crates.io/crates/sparkpost.

Current implementation includes transmission api only. That allows you to send emails with metadata, templates and other features.

Here is a complete example of how to use the lib

[dependencies]
sparkpost="0.4"
serde_json="1.0"
serde_derive = "1.0"
serde = "1.0"
chrono = { version = "0.4", features = ["serde"] }
dotenv = "0.13"

// main.rs

#[macro_use]
extern crate serde_derive;
extern crate chrono; // for setting dateTime option to an email
extern crate dotenv; // optional- to read api key from .env file
extern crate serde;
extern crate sparkpost;

use chrono::prelude::*;
use sparkpost::transmission::{
  Attachment, EmailAddress, Message, Options, Recipient, Transmission, TransmissionResponse,
};


// this could be any Type to replace vlaues in sparkpost template
// only requirement is that it implements Serialize from serde
#[derive(Debug, Serialize)]
struct Data {
  name: String,
}

#[allow(unused)]
fn get_api_key() -> String {
  use dotenv::dotenv;
  use std::env;
  dotenv().ok();
  env::var("SPARKPOST_API_KEY").expect("SPARKPOST_API_KEY must be set")
}

fn main() {
  // for eu servers use 
  // let tm = Transmission::new_eu(get_api_key());
  let tm = Transmission::new(get_api_key());


  // new email message with sender name and email
  let mut email = Message::new(EmailAddress::new(
    "marketing@example.sink.sparkpostmail.com",
    "Example Company",
  ));

  let options = Options {
    open_tracking: true,
    click_tracking: true,
    transactional: false,
    sandbox: false,
    inline_css: false,
    start_time: Some(Utc.ymd(2019, 1, 1).and_hms(0, 0, 0)),
  };

  // recipient with substitute data for the template
  let recipient = Recipient::with_substitution(
    EmailAddress::new("bob@company.com", "Bob"),
    Data { name: "Bob".into() },
  );

  let attachment = Attachment {
       file_type: "image/png".into(),
       name: "AnImage.png".into(),
       // data is base64 encoded string
       data: "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAAXNSR0IArs4c6QAAAAlwSFlzAAAmCC".into(),
   };

  // complete the email message with details
  email
    .add_recipient(recipient)
    .add_attachment(attachment)
    .options(options)
    .campaign_id("marketing_blitz")
    .subject("My Awesome email 😎")
    .html("<h1>hello {name}</h1>")
    .text("hello {name}");

  let result = tm.send(&email);

  match result {
    Ok(res) => {
      match res {
        TransmissionResponse::ApiResponse(api_res) => {
          println!("API Response: \n {:#?}", api_res);
            assert_eq!(1, api_res.total_accepted_recipients);
            assert_eq!(0, api_res.total_rejected_recipients);
        }
        TransmissionResponse::ApiError(errors) => {
          println!("Response Errors: \n {:#?}", &errors);
        }
      }
    }
    Err(error) => {
      println!("error \n {:#?}", error);
    }
  }
}

As I mentioned above that there are many features that are lacking i.e. saving and retrieving templates and recipient list etc. Reason is that I don't use those features for now. If anyone is interested I will be more than happy to help.

Twitter

Originally published on hgill.io

Vue SPA, router guard with redirect after login

Harry Gill — Wed, 10 Oct 2018 12:59:05 +0000

Originally published on my blog

While making Let's Organise SPA(Single page Application) we bumped into the issue of properly checking Auth and redirecting when a user visited a route that required Authentication. If User is authenticated then go to the requested page or redirect to /login page. Once the user has successfully logged in redirect them back to the requested page.

Vue Router has something called Navigation Guards to the rescue, that you can use as hook before every route or selected routes. Navigation Guard is just a plain function and it works like the following.

function guard(to, from, next){
    if(store.state.auth.loggedIn) {
        // or however you store your logged in state
        next(); // allow to enter route
    } else{
        next('/login'); // go to '/login';
    }
}
...
// later in the guarded routes
export default [{
    path: '/membership',
    beforeEnter: guard, // Using guard before entering the route
    component: require('layouts/membershipLayout').default,
    children: [
      { path: '', component: require('pages/membership').default },
      ...
    ]
  }...
  ]

Code above invokes the guard function at before enter hook and does a basic check and redirection. But really what you need is for the router to remember where user started the route, and also check wether user is already authenticated (maybe in another tab).

Our application uses JWT(JSON Web Token) to authenticate Users. The JWT is not stored with client side JavaScript but in a secure https cookie. This means that the application JavaScript can't tell wether that token is valid or is even if it exists for that matter. This design requires at least one round trip to the server to validate the token.

In case of User being already authenticated in another tab, redirecting to login page is not a great user experience. So you can think of the flow lik following.

Router flow logic

We want to execute the logic flow above before every guarded route is visited. We have a place holder variable entryUrl to keep track of url user entered the site with initially set to null. Then we check if we are logged in our application keeps a variable in the Vuex state, If logged in then we check if the entryUrl variable is not set, then simply go to the next route as normal. Otherwise we redirect to that entryUrl and set the variable to null again.

If the Vuex logged in variable not set to true,(this could be if user just visited a url without going through login page) in then we invoke a call to the server to check if user is already authenticated.
then check for authentication, if yes go to the route. If every check fails then we store the initial url visited by the user in entryUrl variable and redirect user to 'login page'.

Corresponding code to the above model looks something like.

// routes.js

import store from '../store';

let entryUrl = null;

const guard = async (to, from, next) => {
  if (store.state.auth.loggedIn) {
    if (entryUrl) {
      const url = entryUrl;
      entryUrl = null;
      return next(url); // goto stored url
    } else {
      return next(); // all is fine
    }
  }

  await store.dispatch('checkAuth'); 
  // we use await as this async request has to finish 
  // before we can be sure

  if (store.state.auth.loggedIn) {
    next();
  } else {
    entryUrl = to.path; // store entry url before redirect
    next('/login');
  }
};

Say hello if you like on Twitter