EmbedThis

Appearance

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 ​

The Ioto web server supports multiple authentication methods to suit different application requirements:

Choosing an Authentication Method ​

Web Form Authentication is the recommended method for most web applications. It provides:

  • User-friendly login interface
  • Session-based authentication with cookies
  • Support for secure logout
  • Flexibility for custom authentication logic

Basic and Digest Authentication are standardized HTTP authentication methods that:

  • Work well for APIs and programmatic access
  • Require no custom login pages
  • Are supported by all HTTP clients
  • Digest provides better security than Basic by hashing credentials

SECURITY RECOMMENDATION: All authentication methods should be used over TLS/HTTPS connections to protect credentials in transit.

Authentication Components ​

Users and Roles ​

The Ioto authentication framework uses a role-based authorization system. Users are assigned roles that define their access capabilities, and routes require specific roles for access.

Learn more: Users and Roles

Route Protection ​

Routes can be configured to require authentication and specific user roles. The web server automatically enforces these requirements before granting access to protected resources.

Example route configuration:

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

Authentication Methods ​

Web Form Authentication ​

Web form authentication uses HTML forms to collect user credentials and HTTP POST requests to submit them to the server. This method provides the best user experience for web applications.

Learn more about Web Form Authentication

Basic and Digest Authentication ​

Basic and Digest authentication are HTTP-standard authentication methods. Basic authentication transmits credentials in base64 encoding (unencrypted), while Digest authentication uses MD5 hashing for improved security.

Learn more about Basic and Digest Authentication

Configuration ​

Authentication is configured in the web.json5 configuration file. The auth section defines:

  • Available user roles and their abilities
  • Login and logout endpoints (for form authentication)
  • Authentication method settings

Example configuration:

js
{
    auth: {
        // Define roles with their abilities (2-level structure)
        roles: {
            public: [],
            user: ['view', 'read'],
            admin: ['user', 'edit', 'delete'],
        },
        login: '/api/public/login',
        logout: '/api/public/logout',
    }
}

The roles property defines a two-level authorization system:

  • Level 1: Role names (e.g., public, user, admin)
  • Level 2: Abilities for each role as an array

Roles can include other roles and specific abilities. For example, the admin role includes the user role plus additional edit and delete abilities.

Authentication APIs ​

The Ioto web server provides APIs for managing authentication programmatically:

Samples ​

Ioto provides authentication samples:

See Also ​