Session State Management

While HTTP is a stateless protocol, IOTO provides robust session state management to maintain context across multiple requests from the same client. This is essential for features like user authentication, device configuration, and multi-step operations.

Sessions work by creating a unique session ID for a client and sending it via a secure cookie. On subsequent requests, the browser returns the cookie, allowing the server to retrieve the session data. For memory-constrained embedded devices, sessions are managed efficiently and expire automatically after a configurable period of inactivity.

Session Lifecycle

Creation

A session is created automatically in one of two ways:

1. On-Demand: When you store data in the session state for the first time using the webSetSessionVar API call.
2. Authentication: When a user is successfully authenticated via webLogin. This creates a new, clean session for the authenticated user.

Upon creation, a session cookie containing the unique session ID is added to the Set-Cookie header of the HTTP response.

Persistence

Once created, a session persists as long as there is client activity. Each new request from the client resets the session's inactivity timer. If the timeouts.sessions limit is reached, the session is automatically destroyed to conserve resources.

Destruction

A session is destroyed in one of the following ways:

• Logout: Calling webLogout explicitly destroys the current session.
• Timeout: The session expires after the configured timeouts.sessions inactivity period.
• Limit: If the maximum number of sessions (limits.sessions) is reached, the oldest inactive session may be reclaimed.

When a session is destroyed, the session cookie is removed from the client.

Configuration

Session behavior is configured in the web.json5 file.

{
    "limits": {
        "sessions": 20
    },
    "timeouts": {
        "sessions": "30m"
    },
    "sessions": {
        "cookie": "ioto-session",
        "httpOnly": true,
        "sameSite": "Lax",
        "secure": true
    }
}

• limits.sessions: Maximum number of concurrent sessions.
• timeouts.sessions: Session inactivity timeout.
• sessions.cookie: The name of the session cookie.
• sessions.httpOnly: If true, the cookie cannot be accessed by client-side scripts.
• sessions.sameSite: Controls cross-site cookie sending. 'Lax' is a good default.
• sessions.secure: If true, the cookie is only sent over HTTPS.

Security

By default, session cookies are created with security best practices in mind:

• Secure: The cookie is only transmitted over HTTPS.
• HttpOnly: Prevents access from client-side JavaScript, mitigating XSS attacks.
• SameSite=Lax: Provides protection against Cross-Site Request Forgery (CSRF) attacks.

These defaults can be overridden in the sessions section of web.json5, but it is strongly recommended to keep them enabled.