HTTP Authentication, Authorization, and Sessions

This document provides an overview of how authentication, authorization, and sessions can be handled in Cro for an HTTP application. Since applications have a wide range of needs in this area, Cro makes it easy for applications to plug in their own session and auth handling. At the same time, it provides a range of components to handle the most common cases.

The auth property of Cro::HTTP::Request §

The auth property of a Cro::HTTP::Request is used to hold an object that may represent any, or all, of:

A current user
A set of rights, or a means to check those rights
Session data

For example:

With basic authentication, there may not be any ongoing session, and the user is authenticated for each request. In this case, the object in auth would typically carry the username, potentially having methods on it to do lookups of further data about that user or fetch rights.
With a JSON Web Token, there is no ongoing session, and the object in auth would be populated from the data in the web token, provided that the token can be verified.
With a web-based login (login form on a page), typically there will be a session object with fields indicating if there is currently a logged in user. The login process would update the session object with that information at the time of login, and clear it at the time of logout.
For a system without any kind of login, but that simply wishes to hold some information about a particular session, then the object would just represent that session information.

Cro does not place any constraints on the type of the object in auth; the contents of this session and/or user object is left for the application to define as it needs. However, it will be most convenient for use with the HTTP router if the object does the Cro::HTTP::Auth role (which is a simple marker role).

The auth property will typically be set by a piece of request middleware. Cro provides a number of options, some built-in and others as modules that can be installed independently.

Router Support §

The signature of a route may start with a positional parameter that:

Is constrained by a type that does the Cro::HTTP::Auth role
Is marked with the is auth trait (this is less convenient, but allows for the case where an existing object should be used, but it is not desirable to couple it to Cro)

Such a parameter will not be treated as the first route segment, but instead will be populated with the contents of the auth property of the Cro::HTTP::Request being processed. The type constraint will also be checked; should it fail, then a HTTP 401 Unauthorized responses will automatically be produced (which middleware may later rewrite into a redirect to a login page, if applicable).

For systems where there are different kinds of user, it can be convenient to create subset types to describe them:

subset Admin of My::App::Session where .is-admin;
subset LoggedIn of My::App::Session where .is-logged-in;

And then use them in routes like this:

my $app = route {
    get -> LoggedIn $user, 'my', 'profile' {
        # Use $user in some way
    }

    get -> Admin, 'system', 'log' {
        # Just use the type and don't name a variable, if the session/user
        # object is not needed
    }
}

Note that middleware that populates auth must be installed either at the server level or in a route block with before (not before-matched, which will be too late).

In-memory session management §

The Cro::HTTP::Session::InMemory[::T] role implements simple in-memory session management, using a cookie to store the session ID. This is useful in web applications. The type used to represent the session data is to be provided by the application. For example:

class My::App::Session {
    has $.is-logged-in;
    has $.admin;
    has @.recently-viewed-items;
}

Could be used as session state by applying this middleware, either in a route block:

my $app = route {
    before Cro::HTTP::Session::InMemory[My::App::Session].new(
        expiration => Duration.new(60 * 15),
        cookie-name => 'MY_SESSION_COOKIE_NAME'
    );

    # Protected routes here...
}

Or at server level (pass it to the before parameter of Cro::HTTP::Server).

The default expiration time is 30 minutes, and this impacts both the max-age set on the cookie as well as the time before session state is deleted from memory. If no cookie name is provided, a random name will be generated (to help avoid being able to fingerprint the application platform by its session cookie name).

Since the session state is stored in memory, it will be lost when the service is restarted. Architecturally, it also prevents scaling out beyond a single process. In short, this is convenient for development purposes, and may be enough for some simple, low-traffic, applications. Consider switching to, or even starting with, Cro::HTTP::Session::Persistent instead in order to provide better scalability and user experience.

Important: The security of this session mechanism depends on the secrecy of the session cookie, which will be sent with every request (this applies not just to Cro, but to HTTP sessions in general). Therefore, HTTPS should be used in production deployments that use this mechanism.

Persistent session management §

The Cro::HTTP::Session::Persistent[::T] role implements session state, with the state being persisted (for example, in a database or key/value store). To use it, one must implement the methods for saving a session state, loading a session state (updating the last seen timestamp), and clearing outdated session state.

class MySession does Cro::HTTP::Auth {
    has $.is-logged-in;
    has $.admin;
    has @.recently-viewed-items;
}
class MySessionStore does Cro::HTTP::Session::Persistent[MySession] {
    # This will be called whenever we need to load session state, and the
    # session ID will be passed. Return `fail` if it is not possible
    # (e.g. no such session is found).
    method load(Str $session-id --> MySession) {
        !!! 'Load session $session-id, place data into a new MySession instance'
    }

    # This method is optional, and will be called when a new session starts.
    # It by default does nothing, but may be convenient for databases with a
    # INSERT/UPDATE distinction (in which case this would be the initial
    # INSERT, and the save method would be an UPDATE). In other databases,
    # this distinction may not exist. This method may return an instance of
    # the session object; if it does not, one will be created automatically
    # (by calling `.new`).
    method create(Str $session-id) {
    }

    # This will be called whenever we need to save session state.
    method save(Str $session-id, MySession $session --> Nil) {
        !!! 'Save session $session under $session-id, probably with a timestamp'
    }

    method clear(--> Nil) {
        !!! 'Clear sessions older than the maximum age to retain them'
    }
}

There are no concrete implementations of this role in the Cro core. However, Cro::HTTP::Session::Redis exists in the module ecosystem; other options will likely be added with time.

Basic Authentication §

The Cro::HTTP::Auth::Basic[::TSession, Str $username-prop] role is a basis for implementing basic authentication. The TSession parameter is the type of the session object to go in auth, and $username-prop is the name of the property to set to the username if authentication succeeds (Nil will be assigned otherwise).

In the case the request's auth property is empty, then an instance of the TSession object will be created, passing username-prop as a parameter (so if $username-prop was set to username, then it would call MySession.new(username => $the-username)). If auth already contains an object, it assumes the property name is actually an attribute name, and uses the metamodel to set it (thus meaning it need not be is rw). This makes it possible to apply a session middleware before this middleware, and have the current user added to the data.

The role requires the authenticate method to be implemented. It is passed the username and password to authenticate, and should return True if it is a valid combination and False otherwise.

class MyUser does Cro::HTTP::Auth {
    has $.username;
}
class MyBasicAuth does Cro::HTTP::Auth::Basic[MyUser, "username"] {
    method authenticate(Str $user, Str $pass --> Bool) {
        # No, don't actually do this!
        return $user eq 'c-monster' && $pass eq 'cookiecookiecookie';
    }
}

JSON Web Tokens §

The Cro::HTTP::Auth::WebToken is a base role for verifying JSON Web Tokens. It has secret and public-key attributes for password or OpenSSL's public key accordingly. Either password or public key must be set. When a request is and decode it using either password or public key. When both secret and public-key attributes are set, public-key will be used to decode token.

In case when key pair is used, RS256 algorithm is used, otherwise HS256 is used.

auth attribute will be populated with Nil if method get-token($request) returned Nil or died with an exception. In case of success, it must return Str.

This role has method set-auth($request, $result), that is called to set auth attribute of a given request. As result of JSON decoding may not do Cro::HTTP::Auth and so made request unable to be sent to a correct route, Cro::HTTP::Auth::WebToken::Token wrapper class that does Cro::HTTP::Auth role is used. It has a single token property that is populated with the result of decoding JSON Web Token by default on calling a set-auth method.

The Cro::HTTP::Auth::WebToken::Bearer is a role that does Cro::HTTP::Auth::WebToken. Its get-token method is overridden to take the token from Auth header of the request object. set-auth method may be overridden by the user to set a custom object that does Cro::HTTP::Auth role to auth attribute. It is installed as middleware, either at route block or server level.

The Cro::HTTP::Auth::WebToken::FromCookie[Str $cookie-name] is a role that does Cro::HTTP::Auth::WebToken. Its get-token method is overridden to take the token from the request's cookie with given name $cookie-name. set-auth method may be overridden by the user to set a custom object that does Cro::HTTP::Auth role to auth attribute. It is installed as middleware, either at route block or server level. Additionally, this role checks exp claim of parsed token. In case it is invalid, the cookie will be removed from the request.

Web form based login §

This can be implemented by picking a session storage mechanism, and having a field in the user/session object that indicates the user is logged in, with some information about rights perhaps included. Since the details of login forms and user databases vary greatly, Cro does not provide a built-in way to achieve this. It is possible some drop-in solutions for more quickly getting started with new applications will be published as a module in the future, however.

The basic recipe is as follows:

class UserSession does Cro::HTTP::Auth {
    has $.username is rw;

    method logged-in() {
        defined $!username;
    }
}

my $app = route {
    before Cro::HTTP::Session::InMemory[UserSession].new;

    subset LoggedIn of UserSession where *.logged-in;

    get -> UserSession $s {
        content 'text/html', "Current user: {$s.logged-in ?? $s.username !! '-'}";
    }

    get -> LoggedIn $user, 'users-only' {
        content 'text/html', "Secret page just for *YOU*, $user.username()";
    }

    get -> 'login' {
        content 'text/html', q:to/HTML/;
            <form method="POST" action="/login">
              <div>
                Username: <input type="text" name="username" />
              </div>
              <div>
                Password: <input type="password" name="password" />
              </div>
              <input type="submit" value="Log In" />
            </form>
            HTML
    }

    post -> UserSession $user, 'login' {
        request-body -> (:$username, :$password, *%) {
            if valid-user-pass($username, $password) {
                $user.username = $username;
                redirect '/', :see-other;
            }
            else {
                content 'text/html', "Bad username/password";
            }
        }
    }

    sub valid-user-pass($username, $password) {
        # Call a database or similar here
        return $username eq 'c-monster' && $password eq 'cookiecookiecookie';
    }
}

Contents

The auth property of Cro::HTTP::Request
Router Support
In-memory session management
Persistent session management
Basic Authentication
JSON Web Tokens
Web form based login

HTTP Authentication, Authorization, and Sessions

The auth property of Cro::HTTP::Request§

Router Support§

In-memory session management§

Persistent session management§

Basic Authentication§

JSON Web Tokens§