User Access Control System

User Access Control is an optional feature which provides a level of resource management to an individual RealityServer instance. If enabled (it is off by default) it sets a maximum number of HTTP users that can access the system at one time. If more than the configured number of users try to access the system then an HTTP 503 (Service Unavailable) status code rather than processing the request.

Implementation

UAC is implemented via HTTP Session Cookies. If a request is received that does not contain a UAC session cookie, or if the cookies value is unknown, then the request is considered to be for a new user. RealityServer checks to see if the maximum number of sessions has been reached and if not it generates a session ID, sets an HTTP Response header to set the session cookie and then passes the request on to the next stage of RealityServer for processing. When the next request from the same user arrives, it will have a valid session cookie set and so the request will be passed on immediately.

If a new request arrives, but the maximum number of sessions has been reached, then RealityServer returns a 503 Session Unavailable error message to the user rather than processing the request.

Enabling

UAC is enabled simply by setting the maximum number of users in the RealityServer configuration file:

	# only 4 users may access at once
	uac_user_limit 4
    

Since many web based applications do not have an explicit logout system it is necessary to expire sessions if they are not used for a given period of time. Otherwise a user who simply closes their web browser would continue to take up a session slot even though they are not accessing RealityServer. The default expiry time for a session is 600 seconds (10 minutes) however this can also be configured:

	# idle session are expired after 2 minutes
	uac_session_timeout 120
    

Session Management

Timeouts are not the only way of expiring sessions, if your user interface does have explicit end session functionality, or if you are controlling RealityServer via an application server you can forcibly expire sessions.

Session management is done by making HTTP GET requests on the UAC management URL, which by default is /uac/. To immediately expire an existing session make the following GET request with the UAC session cookie set to the session to destroy:

    /uac/destroy/
    

It is also possible to require sessions to be explicity created rather than auto generated on first request. By setting uac_auto_session to off in the configuration file any requests without a session cookie are rejected. Session cookies must then be explicitly allocated by calling the following management URL:

    /uac/create/
    

This will create a new session, sets the cookie in the response header then returns. If the user limit has been reached then a 503 error code is returned.

Finally, it is possible to associate a RealityServer scope with a given session. When the session is destroyed (either by expiry or the management URL) all scopes associated with the session are also deleted. This provides an automated system to clean up the RealityServer database and memory. Scopes are associated with sessions by calling the following URL:

    /uac/associate_scope/scope_name
    

The associate call must be made with the session cookie set. Multiple scopes can be associated with a session by calling the URL multiple times. All associated scopes are removed on session deletion.

URL Exemption

It is possible to exclude URLs from requiring session cookies. This can be done, for example, if you want to allow access to an application's HTML interface to any number of users but restrict how many can actually use it at once. URL exemption is done using the apply_uac off directive within normal URL configuration directives :

    <url /viewer/.*>
    apply_uac off
    </url>
    

Such an application would typically have a 'Start' button that explicitly requests a session via the UAC session management URL. If the session request fails then it can display a message to try again later otherwise it begins sending requests and rendering images.

Events

The UAC system can be further customized by responding to UAC related events. Events are fired whenever a session is created or destroyed by any mechanism. Event handlers are passed the session ID, current number of sessions and the maximum number of sessions. They can then perform any required process to react to the event.

Implementation details can be found in the User Access Control section of the API docs.

A full implementation of a UAC event handler can found be in the UAC HAProxy Sample plugin.

Customization

The cookies used for UAC and the URL for session management can all be customized to match your implementation requirements. Details of this can be found in the UAC configuration documentation.