RealityServer Web Services API Programmer's Manual

Authorization System

The RealityServer Web Services Authorization system is the first step (or second if UAC is enabled) applied when processing an HTTP request or when an RTMP connection is made. The system calls a built in or user supplied authorization handler which has access to the HTTP or RTMP request information. From this the handler decides whether the connection should be allowed or not.

Handler selection

Multiple authorization handlers can be registered with RealityServer Web Services and which handler to use can be configured on a per URL basis. If a particular URL matches more than one Authorization handler then the handler associated with the URL with the longest match is used. By default RealityServer Web Services is configured to allow access to every URL.

Implementation

Authorization handlers are implemented in RealityServer Web Services plugins using the mi::rswservices::IAuthorizer interface. These are registered with RealityServer Web Services via mi::rswservices::IExtension_context.

Authorizers have access to the complete HTTP request or RTMP connect request in order to decide whether a connection should be allowed or not. In general authorization succeeds by having the handler return true. Authorization is refused by returning false. For RTMP authorization this is all that is required as there is no mechanism to provide detailed information on why a connection failed. For HTTP however, authorization failure is handled in different ways depending on Authorizer behavior:
  • Handler calls mi::rswservices::IAuthorization_context::set_failure_body. It is assumed that the handler has provided a complete HTTP failure response and this is sent directly.
  • Handler sets a response code and message on mi::http::IResponse. The server attempts protocol identification and if a protocol is found then the error code and message is encoded as a protocol error and returned. If no protocol is identified then an appropriate HTTP response body is generated and returned.
  • If neither of the above occurs then the response code 403 and message 'Forbidden' is returned as if they were set by the handler.
In all cases, any response headers set are honored for both authorization success and failure.

Built in Authorizers

RealityServer Web Services supplies two built in authorizers:
  • "Allow" permits access from all clients.
  • "Forbidden" denies access from all clients.