OSF Web Services Datasets & Access Permissions

From OSF Wiki
Jump to navigation Jump to search

Introduction

OSF is managed by a powerful dataset access permissions layer. This permissions layer authorize or refuse web service access of datasets to group of users. If a user is refused access to a data, it means that it won't have access to any records within that dataset.

You should refer yourself to the OSF Application IDs and API Keys Management page to see how the Applications IDs and API Keys should be managed.

Access Permissions

Access permission records are used to define fine grained access permissions to datasets contents. There are 4 variables that define an access permission:

  • Dataset URI
    • This is the Dataset URI for which you want to create an access record. Access to this dataset will be restricted by this (and possibly others) access permissions records
  • Group URI
    • This is the URI of the group of users for which these access permissions will be defined
  • Web Services URIs
    • These are all the web service endpoints that will be queriable using this access permissions record.
  • CRUD Permissions
    • These are the four CRUD operations that will be permitted, or refused, to that group of users, to access that dataset using one of these web service endpoint

A dataset can only be accessed via one of the OSF Web Services. That web service will only grant access to that dataset content if there exists an access permissions record that meet the following criterias:

  • There is an access record for that dataset URI
  • The requesting user belong to the group of that access record
  • The web service that is being used is part of the list of the web service endpoints of that access record
  • The CRUD permissions defined in the access record gives access to the required CRUD permissions by the web service endpoin

If all these criterias as met, then the query of the user will be successful, otherwise a HTTP 403 error will be returned.

Example of an access permissions record

Here is an example of an access permissions record:

  • Dataset URI: http://localhost/datasets/test
  • Group URI: http://localhost/groups/test
  • Web Services URI: http://localhost/ws/crud/read/, http://localhost/ws/search/
  • CRUD Permissions: Create: TRUE, Read: TRUE, Update: TRUE, Delete: TRUE

Now let's consider these few scenarios:

Scenario #1

Assume that we have a user (http://localhost/users/test) that belong to the group (http://localhost/groups/test) that send a request to the search web service endpoint (http://localhost/ws/search/) for the test dataset (http://localhost/datasets/test).

If we check the Search endpoint's documentation, we will notice that it only requires Read permissions on the data. Given the access record defined above, the query is valid, and the request will be successful. Since the user belong to that group of user, since there exist an access record for that dataset, and since the Search web service endpoint is part of this access record and that the user as Read permissions, the query is successful.

Scenario #2

Assume that we have a user (http://localhost/users/test) that belong to the group (http://localhost/groups/test) that send a request to the search web service endpoint (http://localhost/ws/revision/read/) for the test dataset (http://localhost/datasets/test).

Given the access record defined above, the query is not valid, and the request will be rejected. The problem with this query is that the Revision: Read web service endpoint is not defined in any access record for that dataset. It means that this web service endpoint cannot be used to access the content of that dataset.

Querying a Web Service Endpoint

All and every web service endpoint call are validate by OSF. If the user doesn't have access to an endpoint, a HTTP 403 error will be returned. In this section, we will see how a OSF Web Service endpoint should be queried, and what the HTTP query should look like. Also note that if you want one of your application to communicate with a OSF Web Service endpoint, then you have to comply with the rules outlined in this section.

To generate a valid query to a web service endpoint, the application that send the query need to know the following information:

Variable Description
request timestamp The unix timestamp is the current type when the query is sent
ws url path The ws url path is the path portion of the web service endpoint URL. For example, if the endpoint's URL is http://localhost/ws/search/ then the value of ws url path should be /ws/search/
application ID The application ID is the application ID as registered in OSF Web Services' keys.ini file
user URI The user URI is the URI of the requesting user. This user should be member of a group that as access to the requesting dataset
parameters The parameters are the GET or POST parameters of the query.
Note: They have to be unencoded parameters


API Key The API Key is the API Key as registered in OSF Web Services' keys.ini file. This is the shared secret between the user and OSF
HTTP method The HTTP method can be GET or POST depending on the HTTP method used to query the web service endpoint
Note: they have to be uppercase


security hash The security hash is calculated using the following function (in PHP, but can be implemented in any programming language):
  function securityHash($parameters, $http_method, $ws_url_path, $api_key, $request_timestamp)
  {
    $md5_payload = base64_encode(md5($parameters, true));  

    $data = $http_method . $md5_payload . $ws_url_path . $request_timestamp;

    $hash = hash_hmac("sha1", $data, $api_key, true);

    $hash = base64_encode($hash);
    
    return($hash);
  }

Now that we know what is required to properly generate the HTTP query, here are the HTTP Headers that need to be added to any web service endpoint query:

HTTP Header Value
OSF-TS request timestamp
OSF-APP-ID application ID
OSF-USER-URI user URI
Authorization security hash

If the HTTP headers are properly defined, then when the web service endpoint will receive the query, it will try to re-created the security hash using the shared secret (the API Key) between the user and the web service endpoint. Then if the security keys matches, then it will continue to valide the query based on the dataset access permissions records.

It is only once these two things are validated that the query is fully validated by the endpoint, and that the endpoint starts to process the request and return the resultset.

Groups Management

Groups management is fairly important in OSF. Because of the granularity of the access records, it is quite important to manage dataset accesses by properly managing the groups.

A group is really just a set of users that shares the same access permissions in OSF. If you want to have special permissions for a single user, then you should create a new group that has only a single user registered to it.

As soon as a user URI is registered to a group, that user will have all the permissions defined for that group.

Tools For Access Permissions, Users and Groups

The most flexible way to manage access permissions, users and groups is by using the following OSF web service endpoints:

However, managing these things by directly user these endpoints can be a daunting task. Normally these endpoints are used by user interfaces that communicate directly with these endpoints to help a user to manage these things. If the currently available interfaces are not suitable for your needs, you should be using these endpoints to create your own.

Permissions Management Tool

The Permissions Management Tool (PMT) is a commandline tool that can be used by any system administrator to manage the access permissions, groups and users of a OSF instance. This command line tool can be used by hands, or it can be used by automatic procedures (such as cron jobs).

You can find more information about the PMT here.

OSF for Drupal: Permissions

The access records, users and groups can also be managed using the OSF for Drupal user interface. However, the only things that you can manage are the Drupal users and roles related to that Drupal instance. Depending on how you are using OSF for Drupal, it may be the easiest and best way to manage the users and permissions.

You can find more information about OSF for Drupal's permissions mechanism here.