Rust Lesson #637, Authentication of REST Services goes something like this. Set up a Rocket REST service to require login authentication.

There will be three sets of REST endpoints:

• login which will read the user’s credentials from the request header and write a session key to a private cookie,
• the endpoints you want to protect, which will just be your normal Rocket-style endpoint decorated with a new argument of type that implements rocket::request::FromRequest,
• logout which will scrub authentication information from your cookies.

Login

The first time a user accesses your service, the user should be directed to use a login post which will expect a rocket::serde::json::Json<> structure containing any information you use to setup a session, like username and password, and a reference to a rocket::http::CookieJar to place a session key into.

#[post("/users/login", format = "application/json", data = "<login_info>")]
pub fn login(login_info: Json<LoginInfo>, cookies: &CookieJar<'_>) -> Option<String> {
	....
}

Rocket uses reflection and annotation to perform magic on your route definition to ensure that in order to be well-formed, a request must provide values for the parameters. If a request doesn’t satisfy the parameters at face value, Rocket will respond with a 404.

Inside your route definition, you can check login_info provided in the request header and consult your database or oracle to see if user should be able to authenticate.

Upon success, you can write a session key to be used in subsequent requests. Typically, you’ll hash or encrypt a value readable only by the server to be used as a session key that would include fields like a user id, session id, and expiration time. Here all you have to do is write out a clear text string, for example JSON or whitespace separated values. Rocket’s cookie framework will encrypt the cookie value (but not the key) using the secret key in the Rocket.toml configuration.

let token = "user638 1642533881115".to_string();
let cookie = Cookie::build(AUTH_COOKIE, token).finish();
cookies.add_private(cookie);

Rocket also delivers the cookie back to the client.

Session authentication

This next part is the tricky one, since Rocket performs some sneaky dependency injection. When you register a route with a parameter implementing the FromRequest trait, Rocket will instantiate an implementation and invoke the from_request() method to determine if access to the route should be granted (Success), denied (Failure), or forwarded to another route (Forward).

The parameter to from_request() is a Request instance that can provide the cookie provided during login. Parse the cookie’s value and determine whether access to the REST request should proceed.

You might not need to touch the FromRequest instance in your route. It’s presence just signals the compiler to wire up authentication provided in your FromRequest::from_request() implementation to the route. You can attach other functionality to the FromRequest, such as information gleaned from authentication, like the username.

Logout

This is the easiest step. You’ll just set up a GET request whose only parameter is a rocket::http::CookieJar reference, from which you will remove your session-authentication cookie.

static AUTH_COOKIE: &str = "auth";

#[get("/users/logout")]
pub fn logout(cookies: &CookieJar<'_>) -> Option<String> {
    cookies.remove_private(Cookie::named(AUTH_COOKIE));
    Some("OK".to_string())
}

Debugging notes

Use curl to verify that the REST service authenticates before hacking away at your front end.

Before starting this lesson, I was less-familiar with attaching a JSON header to the request and using cookies. Headers are easy, just use the --data and --header CLI options.

curl --request POST --data '{"username":"some-user-name", "password": "clear-text-secret"}' --header "Content-Type: application/json" 192.168.1.9:7999/users/login -c -

Cookies are a little tricker, but only because there’ll likely be a lot of gobbledy gook– you’ll be passing back encrypted values to the client. In the above example, the -c flag to curl signals to write cookies to a file. The output file - signifies to write to standard out, but you can write to a file for ensuring that the login session is active and later read the cookie file with the -b flag in another request.

curl -v -b cookies.txt 192.168.1.9:7999/action/get/10/0

You can even use both -b and -c with the same value and curl will update the cookies file.

On versioning

As with any software project, it doesn’t take too long to travel to versioning-hell. The notes above refer to my experience with Rocket 0.5.0-rc.1 using the secrets, tls, and json features. The features required serde 1.0.130, serde_json 1.0.67, and rocket_contrib 0.4.10 dependencies. rocket_cors is also useful if you want to separate your front-end from REST requests.