OSDB  OSDB Access Control

See also:

Introduction

OSDB uses ACLs to protect access to its REST API and UI. When ACL protection is enabled, after authenticating through HTTPS, clients must provide a OSDB session cookie with each call. This is handled automatically by browsers. Non-browser clients must use a login API to capture the session cookie. The OSDB login API is described in OSDB REST API Documentation which includes sample Node.js clients for interacting with the OSDB login and REST APIs.

root.acl

The resources to be protected are identified by URIs in a file root.acl. An example root.acl is listed below. Authenticated users, identified by their WebIDs, are granted access to specific resources via the acl:agent property.

@prefix acl: <http://www.w3.org/ns/auth/acl#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

<#authorization1>
    a acl:Authorization ;
    acl:agent 
      <http://ods-qa.openlinksw.com:8896/DAV/home/nobody/cmsb_ex_webid_170223.html#i> ,
      <http://ods-qa.openlinksw.com:8896/DAV/home/nobody/cmsb_ex_webid_170223.ttl#identity> ;
    acl:accessTo 
      <https://osdb.openlinksw.com/osdb/ui/services.*> ,
      <https://osdb.openlinksw.com/osdb/ui/actions.*> ,
      <https://osdb.openlinksw.com/osdb/api/v1/services.*> ,
      <https://osdb.openlinksw.com/osdb/api/v1/actions.*> ;
    acl:mode
        acl:Read .

The rules contained in root.acl are read and evaluated each time an OSDB endpoint is accessed. Any changes to the file take effect immediately, without needing to restart the server.

Public access to a resource is granted using agentClass foaf:Agent, rather than acl:agent <{webID}>.

The initial implementation of OSDB supports two permissions: acl:Read and acl:Write. The permissions required to access an OSDB path depends on a combination of the path and the request HTTP method. The following REST API endpoints require acl:Write:

All other REST or UI endpoints require only acl:Read, including:

As can be seen by comparing the above paths for 'Load service' and 'List services', then 'Unload service' and 'Describe service', OSDB is able to apply different access restrictions on the same path differentiated by the HTTP request method.

The ACL rule below restricts access to the UI for loading and unload services (/osdb/ui/manage_services). Only acl:Read is needed to access this UI. In addition, the rule limits access to the equivalent REST APIs (POST /osdb/api/v1/services and DELETE /osdb/api/v1/services/{serviceId}), by only granting acl:Write to the identified users.

<#authorization2>
    a acl:Authorization ;
    acl:agent
      <http://ods-qa.openlinksw.com:8896/DAV/home/nobody/cmsb_ex_webid_170223.html#i> ,
      <http://ods-qa.openlinksw.com:8896/DAV/home/nobody/cmsb_ex_webid_170223.ttl#identity> ;
    acl:accessTo 
      <https://osdb.openlinksw.com/osdb/api/v1/services.*> ,
      <https://osdb.openlinksw.com/osdb/ui/manage_services> ;
    acl:mode
      acl:Read, acl:Write .

ACL Regular Expressions

OSDB allows the use of regular expressions in place of resource URIs. This allows a regexp to identify a set of resources as the value of acl:accessTo as opposed to having to identify each protected resource explicitly by its own URI. The regexp https://osdb.openlinksw.com/osdb/ui/actions.* protects all paths which are descendents of https://osdb.openlinksw.com/osdb/ui/actions/, for instance:

The effect of this regexp is to automatically protect all imported actions accessed through the UI. There is no need to update the acl:accessTo list after importing a set of new actions by loading a service description. Likewise, the OSDB REST API is fully protected by two regexps.

Disabling ACLs

Ordinarily, OSDB will enforce ACLs in accordance with the rules defined in root.acl. ACL protection can be disabled entirely by starting the OSDB server with the command line option --disable-acls.

Debugging Authentication and ACL Rules

The OSDB server, osdb_server, supports logging to the console and to a file osdb.log. The logging level is controlled by a -l startup option:

-l, --loglevel [info, verbose, debug] Log level (default: info)

-l debug emits the most detailed debug output and dumps some data structures. -l verbose logs function calls but not data structures. Either log level traces OSDB's WebID authentication process.

info: OSDB server
info: Server URL:  https://localhost:8000
info: Service registry:  http://localhost:8896/sparql
verbose: ServiceRegistry#get_service_descriptors
verbose: ACLChecker: Is an agent allowed Read access on https://localhost:8000/osdb/ui/services ?
verbose: ACLChecker: Checking if ACL file root.acl exists
verbose: ACLChecker: Read access NOT permitted to anonymous user
verbose: ACLChecker: ACL file found but no matching policy found
verbose: ACLChecker: Authentication required
verbose: GET /osdb/ui/login
verbose: GET /osdb/login
verbose: #authenticate_using_web_id:
verbose: CN: Carl Blakeley , 
         SAN: URI:http://ods-qa.openlinksw.com:8896/DAV/home/nobody/cmsb_ex_webid_170223.html#i
verbose: #authenticate_using_web_id: delegator:
verbose: #ui_authentication_cb: Identified user:  
         http://ods-qa.openlinksw.com:8896/DAV/home/nobody/cmsb_ex_webid_170223.html#i
verbose: ACLChecker: Is http://ods-qa.openlinksw.com:8896/DAV/home/nobody/cmsb_ex_webid_170223.html#i 
                     allowed Read access on https://localhost:8000/osdb/ui/services ?
verbose: ACLChecker: Checking if ACL file root.acl exists
verbose: ACLChecker: Read access permitted to user:
                     http://ods-qa.openlinksw.com:8896/DAV/home/nobody/cmsb_ex_webid_170223.html#i
verbose: GET /osdb/ui/services
verbose: GET /osdb/logout

WebID with Delegation

In additional to standard WebID, OSDB supports WebID+TLS+Delegation (WTD). WebID authentication with delegation allows a user accessing an OSDB resource to delegate identity authentication to an intermediary software agent identified by its own WebID. The benefit of authentication using delegation is that it requires only one certificate, for the software agent. The delegates/users being authenticated require only their own profile document, not a personal public/private key pair. Without delegation, WebID authentication requires each user to have their own key pair. For a large user base, this presents a signficant security and administrative overhead.

The semantics of this kind of delegated identity authentication are expressed through reciprocal relationship types oplcert:hasIdentityDelegate and oplcert:onBehalfOf represented by RDF statements stored in WebID profile documents of users and software agents. WTD configuration for OSDB, as regards profile documents and certificates, is similar to that for Virtuoso. For a detailed explanation of WTD, albeit in the context of Virtuoso, please refer to: