Sharing

Plone comes with a sophisticated user management system that allows to assign users and groups with global roles and permissions. Sometimes this in not enough though and you might want to give users the permission to access or edit a specific part of your website or a specific content object. This is where local roles (located in the Plone sharing tab) come in handy.

Retrieve Local Roles

In plone.restapi, the representation of any content object will include a hypermedia link to the local role / sharing information in the ‘sharing’ attribute:

GET /plone/folder
Accept: application/json

HTTP 200 OK
content-type: application/json

{
  "@id": "http://localhost:55001/plone/folder",
  "@type": "Folder",
  ...
  "sharing": {
    "@id": "http://localhost:55001/plone/folder/@sharing",
    "title": "Sharing",
  }
}

The sharing information of a content object can also be directly accessed by appending '/@sharing‘ to the GET request to the URL of a content object. E.g. to access the sharing information for a top-level folder, do:

http

GET /plone/folder/@sharing HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/folder/@sharing -H "Accept: application/json" --user admin:secret

httpie

http -j http://nohost/plone/folder/@sharing -a admin:secret

python-requests

requests.get('http://nohost/plone/folder/@sharing', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "available_roles": [
    "Contributor", 
    "Editor", 
    "Reviewer", 
    "Reader"
  ], 
  "entries": [
    {
      "disabled": false, 
      "id": "AuthenticatedUsers", 
      "login": null, 
      "roles": {
        "Contributor": false, 
        "Editor": false, 
        "Reader": false, 
        "Reviewer": false
      }, 
      "title": "Logged-in users", 
      "type": "group"
    }
  ], 
  "inherit": true
}

Users and/or groups without a sharing entry can be found by appending the argument search to the query string. ie search=admin. Global roles are marked with the string “global”. Inherited roles are marked with the string “acquired”.

http

GET /plone/folder/doc/@sharing?search=admin HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/folder/doc/@sharing?search=admin' -H "Accept: application/json" --user admin:secret

httpie

http -j 'http://nohost/plone/folder/doc/@sharing?search=admin' -a admin:secret

python-requests

requests.get('http://nohost/plone/folder/doc/@sharing?search=admin', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "available_roles": [
    "Contributor", 
    "Editor", 
    "Reviewer", 
    "Reader"
  ], 
  "entries": [
    {
      "id": "Administrators", 
      "login": null, 
      "roles": {
        "Contributor": false, 
        "Editor": false, 
        "Reader": false, 
        "Reviewer": false
      }, 
      "title": "Administrators", 
      "type": "group"
    }, 
    {
      "disabled": false, 
      "id": "AuthenticatedUsers", 
      "login": null, 
      "roles": {
        "Contributor": false, 
        "Editor": false, 
        "Reader": false, 
        "Reviewer": false
      }, 
      "title": "Logged-in users", 
      "type": "group"
    }, 
    {
      "id": "Site Administrators", 
      "login": null, 
      "roles": {
        "Contributor": false, 
        "Editor": false, 
        "Reader": false, 
        "Reviewer": false
      }, 
      "title": "Site Administrators", 
      "type": "group"
    }, 
    {
      "disabled": true, 
      "id": "admin", 
      "roles": {
        "Contributor": "global", 
        "Editor": "acquired", 
        "Reader": false, 
        "Reviewer": false
      }, 
      "title": "admin", 
      "type": "user"
    }
  ], 
  "inherit": true
}

Update Local Roles

You can update the ‘sharing’ information by sending a POST request to the object URL and appending '/@sharing‘, e.g. '/plone/folder/@sharing‘. E.g. say you want to give the AuthenticatedUsers group the ‘reader’ local role for a folder:

http

POST /plone/folder/@sharing HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "entries": [
        {
            "id": "test_user_1_",
            "roles": {
                "Contributor": false,
                "Editor": false,
                "Reader": true,
                "Reviewer": true
            },
            "type": "user"
        }
    ],
    "inherit": true
}

curl

curl -i -X POST http://nohost/plone/folder/@sharing -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"entries": [{"type": "user", "id": "test_user_1_", "roles": {"Contributor": false, "Reviewer": true, "Editor": false, "Reader": true}}], "inherit": true}' --user admin:secret

httpie

http -j POST http://nohost/plone/folder/@sharing entries:='[{"type": "user", "id": "test_user_1_", "roles": {"Contributor": false, "Reviewer": true, "Editor": false, "Reader": true}}]' inherit:=true -a admin:secret

python-requests

requests.post('http://nohost/plone/folder/@sharing', headers={'Accept': 'application/json'}, json={'entries': [{u'type': u'user', u'id': u'test_user_1_', u'roles': {u'Contributor': False, u'Reviewer': True, u'Editor': False, u'Reader': True}}], 'inherit': True}, auth=('admin', 'secret'))

HTTP/1.1 204 No Content