OSF Web Services Datasets & Access Permissions

= 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: 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: If all these criterias as met, then the query of the user will be successful, otherwise a HTTP 403 error will be returned.
 * 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
 * This is the URI of the group of users for which these access permissions will be defined
 * These are all the web service endpoints that will be queriable using this access permissions record.
 * 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
 * These are all the web service endpoints that will be queriable using this access permissions record.
 * 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
 * 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
 * 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
 * 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

Example of an access permissions record
Here is an example of an access permissions record: Now let's consider these few scenarios:
 * Dataset URI:
 * Group URI:
 * Web Services URI:
 * CRUD Permissions:

Scenario #1
Assume that we have a user that belong to the group  that send a request to the search web service endpoint  for the test dataset.

If we check the Search endpoint's documentation, we will notice that it only requires  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  permissions, the query is successful.

Scenario #2
Assume that we have a user that belong to the group  that send a request to the search web service endpoint  for the test dataset.

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:

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:

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 ) 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.
 * Auth Registrar: Group
 * Auth Registrar: User
 * Auth Registrar: Access
 * Auth: Lister
 * Auth Registrar: WS

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.