Authentication

Authentication is the process by which a client's identity and capabilities are verified before granting access to server resources. Authentication is essential when you have content that you wish to protect and provide only to specific, approved clients.

The Ioto web server implements a powerful and flexible authentication framework that verifies username and password and controls client capabilities using a role based authorization mechanism.

Overview

Web authentication has historically used Basic or Digest authentication. However these two methods have security and usability flaws and should not be used.

A preferred method is to use a web form to capture the username and password and then transmit them securely using an encrypted TLS connection where the credentials are validated by the web server.

Access Roles

Once authenticated, users are authorized with a role that defines their capabilities.

In Ioto, access roles are an ordered list of user roles with increasing capabilities. Typical roles are: "user", "admin" or "support".

Authentication roles for the Ioto web server are defined in the web.json5 configuration file via the auth.roles property.

Here is a sample:

{
    auth: {
        roles: ["user", "admin"],
        login: '/api/public/login',
        logout: '/api/public/logout',
    }
}

The Ioto web server controls access to resources by assigning a specific "role" on a route that provides access to a document or resource. If the authenticated user has the required role or better, then the user is granted access.

For example:

web: {
    routes: [
        {match: '/api/admin/', role: 'admin'},
        {match: '/api/user/', role: 'user'},
        {match: '/api/'},
        {match: '/admin/', role: 'admin'},
        {match: '/user/', role: 'user'},
        {},
    ],
}

Each route specifies a matching URL prefix except for the last route which is a catchall. To restrict access, the route provides a "role" property that specifies the required user role to permit access.

Users and Passwords

Users are defined in the Ioto database together with their hashed and salted passwords and access role.

User entries are typically created by the device management or admin apps using the cryptMakePassword API.

However, during development, users may be created in the database via the dbcmd and pass programs.

To generate a hashed password for a user, use the pass program. For example:

pass --password demo-pass ralph

This will print the hashed password for "ralph".

You can modify the config/seed.json5 file with the required users and hashed passwords. Then apply this file to the database using the "reset" make target.

1	`$ make reset`

This will run the command:

$ dbcmd --reset --load config/seed.json5 --schema modes/$(MODE)/schema.json5 state/state.db

Verifying Passwords

Authentication schemes define how the user credentials are captured from the user and supplied to Ioto. There are two classes of authentication schemes.

Web Form Authentication
Custom Authentication

Form Authentication

The form authentication scheme uses a HTML web form for the user to enter their username and password credentials and a HTTP Post request to submit credentials to the server for verification. Ioto manages the login/logout process and if authentication succeeds, a login session is created and a cookie is returned to the client's browser. Subsequent requests that include the cookie will be automatically authenticated using the session.

Web Form

Here is a sample minimal example login page:

<html><head><title>login.html</title></head>
<body>
    <p>Please log in</p>
    <form name="details" method="post" action="/api/public/login">
        Username <input type="text" name="username"><br/>
        Password <input type="password" name="password"><br/>
        <input type="submit" name="submit" value="OK">
    </form>
</body>
</html>

After the user enters their username and password and clicks OK, the form is posted and the /api/public/login URL is requested. This URL should be bound to an Action via webAddAction that will verify the password and then call webLogin.

You can use the inbuilt webLoginUser routine to validate the password against the value stored in the database by setting the auth.login property in the web.json5 config file.

For example:

    auth: {
        login: '/api/public/login',
        logout: '/api/public/logout',
    },

If you require custom user authentication, you can define your own login action and leave the auth.login property unset. For example:

static int login(Web *web)
{
    cchar *password, *username;

    username = webGetVar(web, "username", 0);
    password = webGetVar(web, "password", 0);

    // Your own custom password checking routine
    if (CheckPassword(username, password)) {
        webLogin(web, username, password);
        webRedirect(web, 302, "/welcome.html");
    } else {
        webRedirect(web, 401, "/login-failed.html");
    }
    return 0;
}
webAddAction(host, "/auth/login", login);

The login function will retrieve the username and password entered by the user from the form post data and then validate these in the custom CheckPassword function.

SECURITY CAUTION: The login request should only be performed over a secure TLS encrypted connection and never over plain "HTTP".

Route Configuration

To implement the form based authentication, you should ensure the login and log out pages and all required graphics and stylesheets are accessible without authentication.

A typical set of routes for an authenticated web site is:

web: {
    routes: [
        {match: '/api/admin/', role: 'admin'},
        {match: '/api/user/', role: 'user'},
        {match: '/api/'},
        {match: '/admin/', role: 'admin'},
        {match: '/user/', role: 'user'},
        {},
    ],
}

Authenticated users can access documents under the /user section. Administrators have access to the /admin section. All other documents outside /user and /admin are public, such as the home page (/index.html), other HTML pages, stylesheets, javascript and images. These can be accessed without authentication.

The /api/admin section is accessible only to administrators and the /api/user is accessible to all authenticated users. All other actions under /api including the login and logout actions do not require authentication to access.

The {} route is used to match all other URLs and does not require authentication.

Route Table

URL	Description	Required Role
/index.html	Home page	none
/css/	Stylesheets	none
/js/	JavaScripts	none
/images/	Images	none
/api/admin	Actions requiring an administrator user	user
/api/user	Actions requiring an authenticated user	user
/api	Public actions including Login and logout	none
/admin	Documents visible only to administrative users	admin
/user	Documents visible to authenticated users	user

Custom Authentication

You can easily create a custom or hybrid authentication scheme. You can choose to pass the username and password to the login action via other means such as an "Authorization" HTTP header or JSON payload. You would then adjust your login() function accordingly.

Authentication APIs

See the the following API to manage authentication and authorization under program control.

Samples

Ioto provides a sample for user login:

Auth Sample