VAL
Virtuoso Authentication Layer
VAL Overview

Virtuoso provides numerous options for access control - some specific to a particular realm. For instance:

  • Protected SPARQL endpoints associated with specific authentication methods, e.g. /sparql-auth, /sparql-oauth, /sparql-webid
  • SPARQL roles restrict the types of SPARQL commands a database user may perform.
  • Graph level security allows the setting of permissions bit masks to set the read/write (and sponge) permissions on specific RDF graphs to control public or specific user access.

However, OpenLink’s preferred generic access control mechanism for Virtuoso is VAL, the Virtuoso Authentication Layer. VAL provides a generic ACL layer which can be used to protect many Virtuoso resources including SPARQL endpoints or graphs, WebDAV resources and access to the Sponger or individual Sponger cartridges.

VAL provides both authentication and access control services to Virtuoso through an internal Virtuoso API or by two public HTTP APIs, a ‘standard’ HTTP API and a RESTful variant, which manage rules and groups via their URLs. Both are Turtle-based. VAL supports systems like OpenID, BrowserID, and a variety of OAuth services such as Facebook, Google, or Twitter.

Typically, users attempting to access a VAL-protected resource must first login and authenticate themselves through a VAL-supplied authentication dialog. After establishing a VAL session, their access permissions on the resource are checked. Virtuoso LDP resources and containers could be protected in this way, once the required VAL hooks are in place.

The supported authentication methods are:

VAL’s generic ACL layer is fully RDF-based, storing rules and groups in the triple store in private graphs, and describing rules using the W3C acl ontology and the OpenLink ACL ontology. The system also supports restrictions which restrict arbitrary values based on the authenticated user. These can be used to limit the number of query results, enforce quotas etc.

In addition to the API VAL will install a new 401_page and 403_page for the /DAV vhost. SSL-enabled sites need to be manually configured via VAL.DBA.create_val_vhosts() to do the same on the https counterpart. The path of the new authentication page is /val/authenticate.vsp. This page can of course also be customized. It is recommended to look at its code to tweak the look.

VAL Low-Level Authentication API

VAL provides the procedures required for any component in Virtuoso to use these authentication methods (see also VAL Authentication API). There are basically two workflows:

VAL OAuth-like Workflow

The OAuth-like workflow applies to OpenID as well as all supported OAuth-based services.

The workflow for a client is always the same irrespective of the service type:

  1. The client requests an authentication URL via VAL.DBA.thirdparty_authentication_url()
  2. The client navigates to the returned URL allowing the user to authenticate with the 3rd party service.
  3. The 3rd party service redirects to the generic callback procedure VAL.DBA.thirdparty_callback() which will complete the authentication procedure by for example requesting an OAuth access token. It will then call a previously configured procedure for custom processing and finally write an HTML 303 redirection result.

For more details of the possible parameters see the procedure documentation.

VAL BrowserID-like Workflow

The BrowserID-like workflow differs from the above in that it does not require any redirects and callbacks. The client needs to initiate the BrowserID authentication as normally done via the navigator.id Javascript object:

navigator.id.watch({
loggedInUser: null,
onlogin: function(assertion) {
// We need to logout directly after logging in to avoid an endless loop. If we do not logout
// a redirect to this page will result in the Personal JS to call this function again which
// will then trigger the loop
navigator.id.logout();
window.location.href = "authenticate.vsp?service=browserid&assertion=" + assertion;
},
onlogout: function() {
}
});

In this example the BrowserID authentication wil be triggered through a VSP page. We could just as easily perform an AJAX call instead.

If in this example the authenticate.vsp page is called with the service=browserid parameter it will do something like the following to verify the BrowserID assertion which has been created by the client based on the email address and the password the user provided:

if ({?'service'} = 'browserid') {
declare browserid varchar;
if (VAL.DBA.browserid_verify_assertion({?'assertion'}, http_host(), browserid)) {
-- here the user is authenticated via their BrowserID
}
}

VAL provides the procedure VAL.DBA.browserid_verify_assertion() to verify the assertion.

VAL's Session Support

VAL supports the creation and usage of standard Virtuoso sessions as stored in VSPX_SESSIONS. Sessions are created via VAL.DBA.new_user_session() or VAL.DBA.add_sid_to_url().

This is the default mechanism for VAL.DBA.thirdparty_authentication_url(). VAL.DBA.add_sid_to_url() will create a new session id and add it to the given URL.

VAL High-Level API

In addition to the low-level authentication API VAL also provides an authentication.vsp page and two procedures VAL.DBA.get_authentication_details_for_connection() and VAL.DBA.logout() which allow to easily integrate VAL authentication into any Virtuoso application. Create a login link via VAL.DBA.create_login_page_url(), let authenticate.vsp do most of the work and check the result via VAL.DBA.get_authentication_details_for_connection().

See Adding VAL Support to a VSP-based Application for details.

Configuration

Certain aspects of VAL require properly configured SSL endpoints for /val/api and /DAV. The former provides an https callback URL for OpenID and OAuth (always recommended but also mandatory for Box.com and Salesforce), the latter requires a custom 40x_page to enable all the VAL authentication methods.

VAL provides VAL.DBA.setup_val_host() which allows to create the necessary vhosts for a given host.

Also registry setting val_always_use_https_callbacks can be set to 1 for VAL to always use https callback URLs, not only for the services which require it.

See VAL Configuration for more configuration options.