Sending login/logout requests to the server
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
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 should be either
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
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.
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
password sent with the request.
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">
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">
The login request may fail for several reasons. Appropriate status codes and information headers are returned as follows:
|Triggering event||Status code||Information header|
|Not using a ||405||rw-rbac-unsupported-method|
|Not using ||415||rw-rbac-unsupported-content-type|
|Action not "login" or "logout"||400||rw-rbac-unsupported-action|
|The "user" and "password" were not provided||400||rw-rbac-missing-credentials|
|shaDigest does not match roles file||403||rw-rbac-forbidden|
|Unable to access the roles file||500||rw-rbac-internal-error|
Successful login and logout requests return a status code of either
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.
`/login-logout` *methods=POST *plugin='rwserve-rbac-auth'
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
Key points to remember:
- RBAC login/logout uses
- Forms are designed by the webmaster.
- The handler's virtual resource location is configured in the