Datasets and Access Rights (OSF Web Service)

OSF Web Service is guided by a flexible system that defines access rights to individual datasets. Different datasets can have different users and permissions. Different datasets can be accessed by different Web services endpoints.

When combined with an external CMS system, these access rights can also be governed by profiles (patterns of users and access rights) and assignments to one or more user groups.

Anatomy of OSF Web Service Access Records
An access record is an internal OSF Web Service entity that is used to determine if a Web service requester has access to the content of a dataset given the kind of action that he tries to perform on them. These access records are at the core of OSF Web Service: it is what determines if a request is authenticated or refused by any of the Web service endpoints.

An access record is composed of four different characteristics:


 * 1) A requester (the user) identifier (IP address)
 * 2) A target dataset URI
 * 3) A set of Web service(s) endpoint(s) URIs that can be used with this access record
 * 4) A set of CRUD (create - read - update - delete) actions that can be performed by the user, utilizing these Web service endpoints, to access/manipulate data in that dataset

These four characteristics make the access records really flexible, and enable them to define all kind of access usage patterns.

Web Services Permissions
In OSF Web Service, every Web service is characterized as to whether it supports one or more of the CRUD (create - read - update - delete) actions. This means that a given Web service may require Read permissions on a given dataset in order to be able do its work. Other Web service endpoint may require Create permissions. Others may require Delete and Update. Each Web service has a purpose, and this purpose is translated into a series of actions (CRUD actions) that need to be performed.

Here is the basic matrix of the CRUD permissions required for each Web service endpoint:

Web Service Permissions and Access Rights
Each Web service endpoint needs to perform different kinds of CRUD actions in order to fulfill its goal. However, the access to the dataset, by a user, using one of these Web service endpoint will only be granted if there is an access record defined in such a way that the user (IP) has the proper CRUD rights defined for that dataset for this given Web service endpoint. The CRUD access defined for that user has to match the ones needed by the Web service endpoint.

Let's take as an example:

Bob has an access record defined that way:

->     ->      ->      ->      ->      ->      ->      ->      ->      ->

This access record means that Bob, identified by his IP address  has all the CRUD permissions on the dataset. It also states that Bob can only use the CRUD: Create, CRUD: Read, CRUD: Update and CRUD: Delete Web service endpoints on that dataset.

Now, let's say that Bob sends this query:

When this request is analyzed by the Auth: Validator Web service endpoint, then the access will be granted, the CRUD: Read Web service endpoint will be executed and results will be returned to the user.

This query will be granted because there exists an access record in the system that states that the user Bob has Read access to the content of the dataset , and that he also can use the CRUD: Read endpoint  on that dataset.

Now, let's take this second access record:

Kelly has an access record defined that way:

->     ->      ->      ->      ->      ->      ->      ->

Now Kelly wants to send this query to the Search endpoint:

This query is granted because there exists an access record in the system that states that the user Kelly has Read access to the content of the dataset , and that she also can use the Search endpoint  on that dataset.

Then she tries to send this SPARQL query:

However, now she gets a  HTTP status for that query. This query has been refused to Kelly for the following reason: even if there exists an access record in the system that states that the user Kelly has Read access to the content of the dataset , the access record doesn't state that the SPARQL endpoint (http://localhost/wsf/ws/sparql/) can be used by Kelly, for accessing the content of this dataset.

These few examples show how these access records work. These examples show how the four basic characteristics of an access record can create really flexible access control patterns based on a requester, a dataset, a list of Web service endpoints, and a set of actions.

Access Authentication Workflow
Let's examine the access authentication workflow with this example of a user that sends a request to the Search endpoint for searching the content of a particular dataset.



The Setup
The user (let's call him Bob) works from a computer with the IP address. Bob has multiple different access record defined for this IP address, but one of them is the following one:

->     ->      ->      ->      ->      ->      ->      ->      ->      ->      ->      ->      ->      ->

Step #1
The user sends this request to the Search Web service endpoint:

Bob sends a HTTP POST query to a Search Web service endpoint. He requests a OSF Web Service_Internal_Resultset_Structure serialized in RDF+XML. Bob wants to send a full-text search query for the word  to get all the records that match this search query that belong to the dataset

Step #2
When the Search Web service endpoint gets the request from Bob, the first thing it will do is to authenticate the incoming request. For authenticating the request, the Search Web service endpoint will send a validation request to the Auth: Validator Web service.

The internal query that is exchanged between the two services can be represented by:

Step #3, #4, #5
When the Auth: Validator Web service endpoint does receive a validation query, it makes sure that there exists an access record that would authorize the query to be authenticated.

What the endpoint does is to create a query that is sent against an internal access authentication record dataset hosted in a triple store. It gets back all the records that have been defined for the input IP, dataset and Web service URI. Then, if the access records are defined, the Auth: Validator Web service makes sure that the CRUD rights needed by the Web service (the Search endpoint in this example) have the rights defined in the access record for that query.

Step #7
The result of the validation (if it gets validated, or refused) is returned to the Search endpoint.

Step #8, #9, #10, #11
If the query is valid, the Search endpoint will continue its processing. It will send a search query to the full-text search engine to get back a list of records that match the search query  from the   dataset. Then the underlying full-text search engine will return the list of all records that match this search query to the Search endpoint.

Note: if the request is refused, then the search endpoint will skip all the other steps and continue with the  with a HTTP Status code  .

Step #12
Once the Search endpoint retrieves the results from the search engine, it then converts the data into a resultset serialized in the format requested by the user. In this case, a RDF+XML version of the resultset will be returned to the user.

Global User
There exists a special user in OSF Web Service that is called the. This user is referred to as having the IP address. This is the IP address that is used by the Auth: Validator Web service endpoint if no access records are defined for a given incoming IP address. It loosely refers to the public access records of a dataset.

This means that if there is an access permission record for the IP address, with the CRUD permissions " ", on the dataset URI   for  , this mean that anybody that send a query, to any Web service endpoint, for that dataset, will be granted Read permissions. This means that this dataset becomes.