Security

Search
Feedback

Access to a REST endpoints is protected by a corresponding node of type “ResourceAccess”. A ResourceAccess node has the following fields:

"signature": Normalized path of the REST endpoint
"flags": Integer bitmask

Examples for the “signature” field:

SignatureApplies to endpoint(s)Note
Foo/foo, /foos, /Foo, /Foos, /foo/, /Foo/captures permutations of 'Foo' endpoints
Foo/Bar/foo/bar, /foo/Bar, /foo/Bars
/Foo/Id/foo/45d94d5511ca477788e1de3e05abd4d6
/Foo/_Ui/foo/ui(here, 'ui' is a view)

The “flags” field has the following semantics:

    FORBIDDEN                   = 0;
    AUTH_USER_GET               = 1;
    AUTH_USER_PUT               = 2;
    AUTH_USER_POST              = 4;
    AUTH_USER_DELETE            = 8;
    NON_AUTH_USER_GET           = 16;
    NON_AUTH_USER_PUT           = 32;
    NON_AUTH_USER_POST          = 64;
    NON_AUTH_USER_DELETE        = 128;
    AUTH_USER_OPTIONS           = 256;
    NON_AUTH_USER_OPTIONS       = 512;
    AUTH_USER_HEAD              = 1024;
    NON_AUTH_USER_HEAD          = 2048;

To make the resource visible in Structr’s backend UI, you just have to make the ResourceAccess object ‘visibleToAuthenticatedUsers’ (setting the boolean field to true).

So for example, if you want to grant GET and PUT access to authenticated users on the REST endpoint “/foo/bar” and make it accessible in the Data UI, you have to create a ResourceAccess node as follows:

post resource_access '{"signature":"Foo/Bar", "flags":3, "visibleToAuthenticatedUsers":true}'

Another excample: To allow POST to non-authenticated users, but not GET, PUT, DELETE, OPTIONS and HEAD to “/registration”, but hide the endpoint for the Data UI:

post resource_access '{"signature":"Registration", "flags": 64}'

The object-based access is based on an ACL concept with three different access levels:

"visibleToPublicUsers" : true

Visible to public users:Everyone can [read/write/delete/set access rights for] the object

"visibleToAuthenticatedUsers" : true

Visible to authenticated users: Logged-in users can [read/write/delete/set access rights for] the object

Individual rights for a user/group: User/Group can [read/write/delete/set access rights for] the object

Private: Only the owner can [read/write/delete/set access rights for] the object

Default is ‘private’.
It is also possible to set permissions via the REST interface as you can also access relationships this way.

To change the permissions a user/group has for a particular node, you need to lookup the security relationships first:

curl -HX-User:admin -HX-Password:admin "http://0.0.0.0:8082/structr/rest/security?accessControllableId=941f54875b9446f7b7b929061f04fde5&principalId=f02e59a47dc9492da3e6cb7fb6b3ac25"
{
   "query_time": "0.001492947",
   "result_count": 1,
   "result": [
      {
         "id": "d3ec4083707e4e1ea037a1ec2727a560",
         "type": "Security",
         "relType": "SECURITY",
         "sourceId": "f02e59a47dc9492da3e6cb7fb6b3ac25",
         "targetId": "941f54875b9446f7b7b929061f04fde5",
         "principalId": "f02e59a47dc9492da3e6cb7fb6b3ac25",
         "accessControllableId": "941f54875b9446f7b7b929061f04fde5",
         "lastModifiedDate": "2014-07-30T10:43:47+0200",
         "createdDate": "2014-07-30T10:43:47+0200",
         "cascadeDelete": 0,
         "allowed": [
            "read",
            "write",
            "delete",
            "accessControl"
         ]
      }
   ],
   "serialization_time": "0.000228114"
}

Then change the allowed attribute to the desired value:

curl -i -HX-User:admin -HX-Password:admin "http://0.0.0.0:8082/structr/rest/d3ec4083707e4e1ea037a1ec2727a560" -XPUT -d '{"allowed":["read","write"]}'

Check the updated relationship object:

curl -HX-User:admin -HX-Password:admin "http://0.0.0.0:8082/structr/rest/d3ec4083707e4e1ea037a1ec2727a560"
{
   "query_time": "0.002009954",
   "result_count": 1,
   "result": {
      "id": "d3ec4083707e4e1ea037a1ec2727a560",
      "type": "Security",
      "relType": "SECURITY",
      "sourceId": "f02e59a47dc9492da3e6cb7fb6b3ac25",
      "targetId": "941f54875b9446f7b7b929061f04fde5",
      "principalId": "f02e59a47dc9492da3e6cb7fb6b3ac25",
      "accessControllableId": "941f54875b9446f7b7b929061f04fde5",
      "lastModifiedDate": "2014-08-03T15:06:04+0200",
      "createdDate": "2014-07-30T10:43:47+0200",
      "cascadeDelete": 0,
      "allowed": [
         "read",
         "write"
      ]
   },
   "serialization_time": "0.000384896"
}

You can also create new permissions by POSTing to the security resource:

curl -i -HX-User:admin -HX-Password:admin "http://0.0.0.0:8082/structr/rest/security" -d '{"principalId":"467f7c423c0e4b689468ebca163d7791","accessControllableId":"941f54875b9446f7b7b929061f04fde5","allowed":["read"]}' -XPOST
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Set-Cookie: JSESSIONID=e2ullk9o2592vf8jj10mtk6d;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Location: http://0.0.0.0:8082/structr/rest/security/d3ec4083707e4e1ea037a1ec2727a560
Vary: Accept-Encoding, User-Agent
Content-Length: 0
Server: Jetty(9.1.4.v20140401)

principalId is the UUID of the user or group and accessControllableId is the UUID of the node you want grant permissions on to the user/group.

A new security relationship has been created:

curl -HX-User:admin -HX-Password:admin http://0.0.0.0:8082/structr/rest/bfa7b7b3639b4525a441a1bec68be508
{
   "query_time": "0.008050873",
   "result_count": 1,
   "result": {
      "id": "bfa7b7b3639b4525a441a1bec68be508",
      "type": "Security",
      "relType": "SECURITY",
      "sourceId": "467f7c423c0e4b689468ebca163d7791",
      "targetId": "941f54875b9446f7b7b929061f04fde5",
      "principalId": "467f7c423c0e4b689468ebca163d7791",
      "accessControllableId": "941f54875b9446f7b7b929061f04fde5",
      "lastModifiedDate": "2014-08-03T15:36:52+0200",
      "createdDate": "2014-08-03T15:36:52+0200",
      "cascadeDelete": 0,
      "allowed": [
         "read"
      ]
   },
   "serialization_time": "0.001714507"
}

Structr’s security system provides two different types of access levels: Resource-and object-based access.

Graph-Browser

About this article
Last change 2016-03-04
Topics Structr 2.0