WebBroker Sessions Management
Go Up to Using Web Broker Index
Since RAD Studio 13.0, the new TWebSessionManager class manages a list of TWebSession objects. It is a non-visual component that offers a set of properties at design time. By default, it uses a SessionId cookie, but other options are possible. Developers can associate data with the session object.
The TWebRequest.Session property returns the session associated with the request. You can store custom objects in TWebSession.DataVars, making them directly available in WebStencils scripts.
Session authentication can be integrated with session management and based on different logic. Ready to use are TWebBasicAuthenticator (implementing "Basic" HTTP authentication) or TWebFormsAuthenticator (for custom HTML form-based authentication). Both TWebSessionManager and TWebFormsAuthenticator can be put on a web module, but only a single instance of each.
A “sentinel” algorithm is built into TCustomWebDispatcher.DispatchAction, and delegates processing to IWebSessionManager or IWebAuthenticator.
Contents
Session Management
The new TWebSessionManager component provides advanced session management capabilities. Session data, whether stored in cookies (default), headers, or query parameters, is accessible in WebStencils templates using the @session.xxx syntax.
The component supports flexible session scoping: sessions can be unlimited, assigned per authenticated user, or bound to a user–IP combination for added security. Sessions expire after a configurable timeout, and applications store custom objects in DataVars for direct access.
TWebRequest.Session returns the current session, enabling immediate storage and retrieval of custom data without additional setup.
WebStencils accesses session data through @session.customObject, with @customObject as a shortcut for objects stored in DataVars.
Configuration
IdLocation: Where session ID is stored -ilCookie(default),ilHeader, orilQuery.IdName: Session ID parameter name (default: "sessionId").Scope: Session uniqueness level:ssUnlimited: New session for any request without a session ID (default).ssUser: One session per authenticated user (requires authenticator).ssUserAndIP: One session per user+IP combination (requires authenticator).
Timeout: Session expiration in seconds (default: 3600).SharedSecret: Secures session IDs for user-scoped sessions.
TWebSession represents individual sessions with:
DataVars: Custom key-value storage (objects owned by session).User: Associated authenticated user (IWebUser interface).- Base information such as: CreatedTime, LastURL, LastIP, etc.
- Access via
TWebRequest.Sessionproperty.
Authentication
Since RAD Studio 13.0, there are two ready-to-use authenticators:
- TWebBasicAuthenticator for standard HTTP Basic Authentication:
- Uses standard Authorization header.
- Configurable
Realmproperty. - Automatic credential extraction and challenge generation.
- TWebFormsAuthenticator for custom HTML form-based login flows:
LoginURL: Authentication form page.FailedURL: Redirect for failed authentication.HomeURL: Default redirect after successful login.ReturnURLParam: Query parameter for preserving original URL (default: "returnUrl").
TWebFormsAuthenticator manages the complete login flow. It redirects unauthenticated requests to the login page, processes POST credentials, and returns users to the original URL through the ReturnURL parameter. Configuration uses the LoginURL, FailedURL, and HomeURL properties, while the OnAuthenticate event validates credentials against the user store.
Both authenticators support logout via POST to LogoutURL and use OnAuthenticate event for credential validation.
Authorization
TWebAuthorizer provides role-based access control through authorization zones. URL patterns, such as /admin, define protected areas, and access is restricted by user roles specified in a comma-separated list. Authorization levels include zkFree, zkProtected, and zkIgnore.
Authorization checks user roles against zone requirements. Use the OnAuthorize event for custom authorization logic. Failed authorization redirects to UnauthorizedURL or returns a 403 status.
In addition, the session object includes a UserHasRole method.
Configuration
- PathInfo: URL pattern mask for matching requests. IE: /admin*
- Kind: Protection level:
zkIgnore: Skip all processing.zkFree: Allow anonymous access.zkProtected: Require authentication.
- Roles: Comma-separated list of required user roles.
WebStencils Integration
WebStencils templates support role-based content control through @session.UserHasRole(‘admin’), enabling conditional display of sections based on user permissions.
Sessions integrate with WebStencils templating:
- @session.xxx: Access session object properties.
- @session.DataVars: Access session custom variables.
- @session.UserHasRole(<string>): Check if a user has a specific role.
- @<n>: Direct access to objects stored in DataVars with key
<n>.
Request Properties
RAD Studio allows one TWebSessionManager and one authenticator per web module. The dispatcher sentinel automatically detects these components, while event handlers implement custom authentication and authorization logic.
- TWebRequest.AuthUserName: Authenticated user name.
- TWebRequest.AuthMethod: Authentication method used.
- TWebRequest.Session: Current request session object.
TWebSessionManager automatically creates sessions. When an authenticator is present, authentication becomes mandatory and can be controlled with TWebAuthorizer . Components interact through the IWebSessionManager, IWebAuthenticator, and IWebAuthorizer interfaces.
Log output
TWebApplication.Log records messages with severity, text, and parameters. It runs on all platforms and integrates with the hosting web server’s log system.
- Apache: Apache server log file, by default logs\error.log
- ISAPI: Windows Event Log (eventvwr.msc) -> Windows Logs
- CGI: file with TCGIApplication.LogFileName name
- FastCGI: HTTP (Apache, nginx) server log file, by default logs\error.log
This feature is not supported by Indy IdHTTPServer.