Auth Handler

Preliminaries

This note describes how the server handles POST requests to login and logout of the Role Based Access Control mechanism.

Users can login to the website using the services of the built-in "rwserve-rbac-auth" plugin. This handler expects requests to be sent with a POST method.

Webmasters should either create their own form-based page to act as a front-end user interface for this handler, or use AJAX to manage the request/response cycle.

Requests sent to the handler must have a content-type of application/x-www-form-urlencoded. The form's payload includes four possible URL-encoded values: action, user, password and location.

Action should be either "login" or "logout".

Login Request

When processing the login action, the handler applies the server's standard SHA256 hashing algorithm, as outlined in the note regarding user accounts. The handler accepts or rejects the login request based on successful comparison of the caclulated shaDigest against the user's previously stored shaDigest.

Requests that are accepted return a set-cookie response header, which instructs the browser to create and store a session cookie under the identifier rw-rbac. All subsequent requests from the browser will send that cookie back to the server for use by the RBAC handler.

The contents of the rw-rbac cookie are the roles assigned to the user, in an encrypted form. Refer to the separate note regarding Stateful Roles for a detailed description of how this cookie is secured against bad actors.

Logout Request

When processing the logout action, the handler simply sends a new set-cookie response header with an rw-rbac identifier and an empty string. This instructs the browser to remove the cookie which effectively prevents further access to protected resources.

The logout action does not use, and will ignore, any user and password sent with the request.

HTML Forms

In these two examples, the POST form's "action" attribute points to the path /login-logout, which is not a real location; rather, this path is configured by the webmaster to point to a virtual resource path. See the examples below, and refer to the note pertaining to the Router, for detailed instructions on how it works.

Here is what a properly crafted HTML login form should look like:

<form method="POST" action="/login-logout">
    <input type="hidden" name="action" value="login">
    <input type="text" name="user">
    <input type="password" name="password">
    <input type="hidden" name="location" value="https://example.com/welcome">
    <input type="submit" value="Login">
</form>
						

Here is what a properly crafted HTML logout form should look like:

<form method="POST" action="/login-logout">
    <input type="hidden" name="action" value="logout">
    <input type="hidden" name="location" value="https://example.com/bye-bye">
    <input type="submit" value="Logout">
</form>
						

Information Headers

The login request may fail for several reasons. Appropriate status codes and information headers are returned as follows:

Status codes

Successful login and logout requests return a status code of either 204 or 303. For both the login and logout actions, the optional location form value may be supplied. It should contain a path (including the https:// scheme) pointing to the web page to be displayed after a successful action. If provided, the server will respond with status code 303 and a location header, instructing the browser to issue a new request to that other web page. If not provided, the server will respond with status code 204, and the webmaster will be responsible for providing some type of browser-side script to determine how to proceed.

Here is a partial configuration showing just the entries used by the RBAC-Auth handler. A more complete example is provided in the note that covers the RBAC handler itself.

host {
    modules {
        rbac   on
    }
    plugins {
        router {
            `/login-logout`  *methods=POST  *plugin='rwserve-rbac-auth'
        }
    }
    rbac {
        roles `/etc/rwserve/roles`      // the file created by the 'addrole' CLI utility
        cipher-secret C#9fB$2gD@5zR*7e  // secret used to encrypt the 'rw-roles' cookie
        max-idle 1800                   // number of seconds of inactivity before credentials expire
    }
}
						

Review

Key points to remember:

• RBAC login/logout uses POST with content-type application/x-www-form-urlencoded.
• Forms are designed by the webmaster.
• The handler's virtual resource location is configured in the router section.