You have been redirected from an outdated version of the article. Below is the content available on this topic. To view the old article click here.

Resource Access Grants

Any resource in Structr can be accessed via REST in the common JSON format. Each type automatically defines a REST endpoint.

In order to protect these endpoint URLs, Structr has a built-in access control engine which lets administrators control the specific access rights for each type endpoint.

Example

In the following screenshot the resource access grants table has been filtered to only show grants whose signature contains “Sample”.

Resource Access Grants Table

We can see the following settings:

  • Non-authenticated (public) users are allowed to perform GET-operations on /structr/rest/SampleApplication which will load the public view
  • Non-authenticated (public) users are allowed to perform GET-operations on /structr/rest/SampleApplication/CustomView which will load the CustomView view
  • Authenticated users are allowed to perform both GET-operations as well
  • Authenticated users are allowed to perform POST operations on /structr/rest/SampleApplication which allows them to create instances of SampleApplication
  • Authenticated users are allowed to perform POSToperations on /structr/rest/SampleApplication/SampleMethod which allows them to call the custom method SampleMethod on instances of type SampleApplication.

Search results for "Resource Access Grants"

Resource Access Grants Migration Guide

Resource Access Grants have been made more flexible in Structr 4.0 Release. Rights management now also applies to grant nodes. That means that users have to have read access to the grant object to be able to “use” it. Assigning visibility flags (visibleToPublicUsers, visibleToAuthenticatedUsers) or ACL read rights via users/groups is necessary for this. The other configuration of access flags for HTTP Verbs remain unchanged.

When upgrading to a version of Structr >= 4.0 (with an existing application), there are two (similar) approaches we can take to configuring the resource access grants: Manual migration and semi-automatic migration using the deployment.

Resource Access Grants

This part of Structr’s backend UI is the place where the entry points of Structr’s HTTP REST Service can be configured.

While the security system of Structr is focused on users and their security context (i.e. does the user has access to a given database entity?), the checking of resource access grants is focused on the URL path (the resource) of an HTTP request.

More precisely, if a user requests all entities of a given schema type via Structr’s REST interface with a call to the URL /structr/rest/SchemaType, Structr will check if the user is logged into the system and if a GET request on the resource /SchemaType is permitted for authenticated users. If the user is not logged into the system the GET permission for non-authenticated users has to be set for that resource.

Only when the permission for the resource is set, Structr will then check if user has grants for the actual database content and the entities of the type SchemaType.

Relationship Details Dialog

The Cascading Delete settings allow configuration of what happens when either end of the relationship is deleted. The possible values are explained in-depth in the help popup in the dialog.
Automatic Creation of Related Nodes configures if it is allowed to include nested nodes in a REST POST request for this relationship. A node with the given property set is automatically created and linked to the node. If the nested node contains an id attribute (or another property marked as unique) a node is searched for that property and linked if found.

Permission Resolution allows configuration of rights propagation in the graph. If NONE is selected, no rights propagation is applied for this relationship. If SOURCE_TO_TARGET is selected the rights are propagated along the relationship direction to the next node. For TARGET_TO_SOURCE the rights propagation is works against the relationship direction. For ALWAYS the direction of the relationship does not matter and rights propagation is always applied.
Specific rights (Read, Write, Delete, AccessControl) can be added, kept or removed according to the propagation configuration. If a user has read rights to the previous node and Read is configured to Keep, the user also has read rights for the next node. (Specific User/Group rights are applied before using permission propagation - i.e. if a user has specific rights configured for a node, permission resolution is not evaluated as user rights are more specific).
Along the way of permission propagation, properties can be hidden in order to hide sensitive information from users who get rights from permission propagation. The property names can be separated by comma , or space character.

There are 3 tabs where the functionality of the type can be configured:

  • Local Attributes
    A Custom Type can be extended with dynamic properties to provide the data model for the intended use-case. This list contains all local properties (meaning they are defined on this type directly).
  • Views
    The properties of a type can be combined into named Views, which are accessible under an individual REST URL. Access to these URLs can be configured independently for each HTTP method using Resource Access Grants, which makes them an ideal tool to create specialised endpoints for different client applications (e.g. mobile clients etc.).
  • Methods
    There are different kinds of methods - callback methods and entity methods. Callback methods are automatically executed by the framework upon certain lifecycle events and have a strict naming convention. Entity methods are called by the user/programmer.
    Entity methods are not automatically run by the framework and must be called manually. This either means making a POST request to /structr/rest/(Type)/(<a data-id="7c9c8218bced42bab66868373e64d885" class="mention">UUID</a>)/(methodName) or in serverside JavaScript as node.methodName();

Resource Access Grants

The first message comes in case that the resource access grant with the signature SchemaType exists, but the method GET is not configured to be allowed for public users.
The second message comes in case a resource is requested for which no resource access grant exists at all (in this case a GET request for the view “public” on the type “SchemaType”).

For the first two lines in the above case (< v.4.0) two separate Resource Access Grants would need to be created. One with the signature SchemaType and the GET permission for public users. The other one with the signature SchemaType/_Public.

While the security system of Structr is focused on users and their security context (i.e. does the user have access to a given database entity?), the checking of resource access grants is focused on the URL path (the resource) of an HTTP request.

REST

The REST mode provides a very simple REST client that runs as if you were to access Structr externally. This means that your requests are made without authentication, as long as you don’t authenticate them. You can use the REST client to simulate access from the outside and test Resource Access Grants etc.

Endpoints

With the default configuration, non-admin users are not allowed to access any endpoints. If you want to allow non-admin users access to an endpoint, you must grant permission explicitly, and separately for each HTTP method. This is what the “Authenticated Users” flags in Resource Access Grants are for.

Authentication

Access to the REST endpoints is prohibited by default and can be obtained through different authentication methods. Please refer to the Security chapter below to learn more about Structr’s Security System, Authentication Headers, Resource Access Grants and HTTP Basic Authentication.

Resource Access Grants

In all the examples until now, we used the admin user to authenticate the request. The admin user is a special user that has access to all endpoints, database objects and functions. If you want a non-admin user to be able to fetch data from a REST endpoint, you need to allow access to each resource separately. This is what the so-called Resource Access Grants are for.

Authentication

Additionally, REST endpoints are protected by a security layer called Resource Access Grants that depend on the type of user making the request.

Authenticated Users

A request that includes authentication headers is an authenticated request, and we call the corresponding user authenticated user. Authenticated users are at a higher level in the access control hierarchy, and have their own permission set in Resource Access Grants.

Signature

Resource Access Grants consist of a signature and a set of flags that control access to individual REST endpoints. The signature of an endpoint is based on its URL, omitting any UUID, plus a special representation for the view, which is the view’s name, capitalized and with a leading underscore. The signature part of a schema method is equal to its name, but capitalized. The following table contains examples for different URLs and the resulting signatures.

Endpoints

With the default configuration, anonymous users are not allowed to access any endpoints. If you want to allow anonymous access to an endpoint, you must grant permission explicitly, and separately for each HTTP method. This is what the “Non-authenticated Users” flags in Resource Access Grants are for.

Deployment Format

folder / filedescription
componentsContains the shared components of the pages editor of Structr.
filesContains all files out of Sturctr’s virtual filesystem. Folders and files in the virtual filesystem are not being exported by default. If you want to include a folder or file into the export you have to set the flag includeInFrontendExport on each file or folder. Each file or folder will inherit this flag from its parent folder.
mail-templatesContains the mail-templates.
modulesContains the application configuration and definition of additional modules of Structr e.g. the flow engine.
pagesContains the created pages in the pages editor of Structr.
schemaContains the schema definition and code entered in the schema and code section of the Structr UI.
securityContains the resource access grants defined in the security section of the Structr UI.
templatesContains all template elements of the pages editor of Structr.
application-configuration-data.jsonContains the configured schema layouts of Structr’s schema editor.
components.jsonContains the settings e.g. visiblity flags, contentType or uuid for each file in the components folder of the export.
deploy.confContains information about the Structr system that created the export of the application.
files.jsonContains the settings e.g. visiblity flags, contentType or uuid for each file in the files folder of the export.
localizations.jsonContains the localizations that where created in the localizations section of the Structr UI and that can be used in server side scripting with the localize() function of Structr.
mail-templates.jsonContains the settings e.g. visiblity flags, locale or uuid for each file in the mail-templates folder of the export.
pages.jsonContains the settings e.g. visiblity flags, contentType or uuid for each file in the pages folder of the export.
pre-deploy.confScript that is run before deployment import. Use this to create users who are granted access to nodes in the export files.
post-deploy.confScript that is run after deployment import. Can be used to start any tasks which are necessary after import.
sites.jsonContains sites that are configured in the pages section of the Structr UI.
templates.jsonContains the settings e.g. visiblity flags, contentType or uuid for each file in the templates folder of the export.
widget.jsonContains the widgets that were created in the pages section of the Structr UI.

REST Query

The REST repeater configuration allows entering a REST URI and supports all query features a regular REST query supports. This includes sort, order, page, pageSize, range queries etc.

It is not necessary to include the REST base path /structr/rest/.
Further, it is not necessary to create resource access grants for these REST queries as they are run internally.

Type Details Dialog

There are 5 tabs where the functionality of the type can be configured:

  • Local Attributes
    A Custom Type can be extended with dynamic properties to provide the data model for the intended use-case. This list contains all local properties (meaning they are defined on this type directly).

  • Views
    The properties of a type can be combined into named Views, which are accessible under an individual REST URL. Access to these URLs can be configured independently for each HTTP method using Resource Access Grants, which makes them an ideal tool to create specialised endpoints for different client applications (e.g. mobile clients etc.).

  • Methods
    There are different kinds of methods - callback methods and entity methods. Callback methods are automatically executed by the framework upon certain lifecycle events and have a strict naming convention. Entity methods are called by the user/programmer.
    Entity methods are not automatically run by the framework and must be called manually. This either means making a POST request to /structr/rest/<Type>/<UUID>/<methodName> or in serverside JavaScript as <node>.<methodName>();

  • Remote Attributes
    Custom types can be linked to other types, including base types. Structr will automatically create Remote Attributes on either side of the link, which can then be used to create, update or remove the relationships between instances of the two types. In this tab the configuration of the remote attributes can be viewed and edited. The names configured here are used throughout the application to refer to the other side of the relationship(s).

  • Inherited Attributes
    The content of this tab is of informative character. All inherited attributes are shown with an information from where it was inherited.

Manual configuration

If there are a lot of grants to configure it is advisable to active the switch “Show visibility flags in Resource Access Grants table” on the “UI Settings” tab on the dashboard.

  1. Log in as admin in the administration backend
  2. Navigate to the “Security” area
  3. Activate the “Resource Access Grants” tab
  4. Activate the checkbox “Show only used grants”
  5. Migrate the grants according to these rules:
    • If the grant has active flags set for “Public Users” then the visibleToPublicUsers flag will be set to true
    • If the grant has active flags set for “Authenticated Users” then the visibleToAuthenticatedUsers flag will be set to true.
    • If the grant now has both visibility flags set, split it into two grants with identical signature