Sharing
Contents
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.
Retrieving 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 HTTP/1.1
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 -X GET http://nohost/plone/folder/@sharing -H "Accept: application/json" --user admin:secret
httpie
http http://nohost/plone/folder/@sharing Accept:application/json -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": [
{
"id": "Contributor",
"title": "Can add"
},
{
"id": "Editor",
"title": "Can edit"
},
{
"id": "Reader",
"title": "Can view"
},
{
"id": "Reviewer",
"title": "Can review"
}
],
"entries": [
{
"disabled": false,
"id": "AuthenticatedUsers",
"login": null,
"roles": {
"Contributor": false,
"Editor": false,
"Reader": false,
"Reviewer": false
},
"title": "Logged-in users",
"type": "group"
}
],
"inherit": true
}
The available_roles
property contains the list of roles that can be
managed via the sharing page. It contains dictionaries with the role ID and
its translated title
(as it appears on the sharing page).
Searching for principals#
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 -X GET 'http://nohost/plone/folder/doc/@sharing?search=admin' -H "Accept: application/json" --user admin:secret
httpie
http 'http://nohost/plone/folder/doc/@sharing?search=admin' Accept:application/json -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": [
{
"id": "Contributor",
"title": "Can add"
},
{
"id": "Editor",
"title": "Can edit"
},
{
"id": "Reader",
"title": "Can view"
},
{
"id": "Reviewer",
"title": "Can review"
}
],
"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
}
Updating 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": "AuthenticatedUsers",
"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": [{"id": "AuthenticatedUsers", "roles": {"Contributor": false, "Editor": false, "Reader": true, "Reviewer": true}, "type": "user"}], "inherit": true}' --user admin:secret
httpie
echo '{
"entries": [
{
"id": "AuthenticatedUsers",
"roles": {
"Contributor": false,
"Editor": false,
"Reader": true,
"Reviewer": true
},
"type": "user"
}
],
"inherit": true
}' | http POST http://nohost/plone/folder/@sharing Accept:application/json Content-Type:application/json -a admin:secret
python-requests
requests.post('http://nohost/plone/folder/@sharing', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'entries': [{'id': 'AuthenticatedUsers', 'roles': {'Contributor': False, 'Editor': False, 'Reader': True, 'Reviewer': True}, 'type': 'user'}], 'inherit': True}, auth=('admin', 'secret'))
HTTP/1.1 204 No Content