diff --git a/docs/4DQodlyPro/force-login.md b/docs/4DQodlyPro/force-login.md index 9df5d8c6a..e706330f9 100644 --- a/docs/4DQodlyPro/force-login.md +++ b/docs/4DQodlyPro/force-login.md @@ -15,7 +15,6 @@ Make sure the ["force login" mode](https://developer.4d.com/docs/REST/authUsers# You can also set this option directly in the [**roles.json** file](https://developer.4d.com/docs/ORDA/privileges#rolesjson-file). -You just need then to implemented the [`authentify()`](https://developer.4d.com/docs/REST/authUsers#function-authentify) function in the datastore class and call it from the Qodly page. A licence will be consumed only when the user is actually logged. :::note Compatibility @@ -28,8 +27,6 @@ When the legacy login mode ([deprecated as of 4D 20 R6](https://blog.4d.com/forc In a simple Qodly page with login/password inputs, a "Submit" button calls the following `authentify()` function we have implemented in the DataStore class: - - ```4d exposed Function authentify($credentials : Object) : Text var $salesPersons : cs.SalesPersonsSelection @@ -51,31 +48,6 @@ In a simple Qodly page with login/password inputs, a "Submit" button calls the f return "Wrong user" End if ``` - - - ```qs - exposed function authentify(credentials : Object) : string - var salesPersons : cs.SalesPersonsSelection - var sp : cs.SalesPersonsEntity - - salesPersons=ds.SalesPersons.query("identifier = :1", credentials.identifier) - sp = salesPersons.first() - - if (sp!=Null) - if (verifyPasswordHash(credentials.password, sp.password)) - session.clearPrivileges() - session.setPrivileges("") //guest session - - return "Authentication successful" - else - return "Wrong password" - end - else - return "Wrong user" - end - ``` - - This call is accepted and as long as the authentication is not successful, `Session.setPrivileges()` is not called, thus no license is consumed. Once `Session.setPrivileges()` is called, a 4D client licence is used and any REST request is then accepted. diff --git a/docs/4DQodlyPro/img/add-privilege.png b/docs/4DQodlyPro/img/add-privilege.png new file mode 100644 index 000000000..88b3ec382 Binary files /dev/null and b/docs/4DQodlyPro/img/add-privilege.png differ diff --git a/docs/4DQodlyPro/roles/attributesPermissions.md b/docs/4DQodlyPro/roles/attributesPermissions.md index 3a8a68b66..a7a8050f6 100644 --- a/docs/4DQodlyPro/roles/attributesPermissions.md +++ b/docs/4DQodlyPro/roles/attributesPermissions.md @@ -40,6 +40,3 @@ To address this issue, refine the attribute permissions to restrict access to se By setting attribute permissions in the `ManageFinancials` privilege, you allow users with the `ManageReports` privilege to access the Reporting dataclass while restricting access to confidential attributes like `netProfitMargin` and `totalExpenses`. - - -In the response, the presence of `__INVALID: 1` indicates that the attribute is marked as invalid, signaling that the user lacks the necessary permissions to access or modify it. \ No newline at end of file diff --git a/docs/4DQodlyPro/roles/dataClassPermissions.md b/docs/4DQodlyPro/roles/dataClassPermissions.md index ce5e6168b..8e7aa1282 100644 --- a/docs/4DQodlyPro/roles/dataClassPermissions.md +++ b/docs/4DQodlyPro/roles/dataClassPermissions.md @@ -6,13 +6,12 @@ title: DataClass Permissions import Column from '@site/src/components/Column' -## Purpose and Scope - -**DataClass** Permissions empower you to shape and control access to specific DataClasses within your datastore. These permissions dictate what actions users are allowed to perform on individual DataClasses, enabling fine-grained access control over your data. ## Configuring DataClass Permissions -DataClass-level permissions can override or supplement those set at the datastore level. To set DataClass permissions for a specific privilege: +[Refer to the 4D documentation](https://developer.4d.com/docs/ORDA/privileges#inherited-permissions) to see how DataClass permissions interact with other permissions. + +To set DataClass permissions for a specific privilege: - Select the resource name, like the `Employee` dataclass, from the dropdown list. - Or, type the resource name directly into the search bar. @@ -23,7 +22,7 @@ The
-By setting specific permissions in the `Restricted` privilege for the `Employee` DataClass, you prevent users with the `Guest` privilege from accessing sensitive employee data. +1. Create a `Restricted` privilege for the `Employee` DataClass +2. Set all permissions to the `Restricted` privilege. -:::info -In this context, the permissions set at the datastore level for the Guest privilege are overridden by the Restricted privilege at the DataClass level. As a result, users with the Guest role no longer have access to the Employee DataClass. -::: \ No newline at end of file +In this context, the permissions set at the datastore level for the guest privilege are overridden by the Restricted privilege at the DataClass level. As a result, users with the guest role no longer have access to the Employee DataClass. \ No newline at end of file diff --git a/docs/4DQodlyPro/roles/datastorePermissions.md b/docs/4DQodlyPro/roles/datastorePermissions.md index 94c12faed..1db6526df 100644 --- a/docs/4DQodlyPro/roles/datastorePermissions.md +++ b/docs/4DQodlyPro/roles/datastorePermissions.md @@ -5,17 +5,9 @@ title: Datastore Permissions import Column from '@site/src/components/Column' -## Purpose and Scope +## Overview -Datastore permissions are essential for controlling access to your entire **Datastore**. By configuring these permissions, you establish a primary defense mechanism against unauthorized access and alterations to critical mission data. - -## Risk of Unrestricted Access - -Without proper setup, your application is vulnerable to unregulated access. In such scenarios, every user gains unrestricted access to all **datastore resources**, posing significant risks. - -To illustrate, imagine an unauthorized user attempting an HTTP request to the **Package dataclass** REST API endpoint. This unchecked data access allows unauthorized actions, including accessing confidential user information, and poses a uniform risk across all dataclasses. - - +Datastore permissions are essential for controlling access to your entire **Datastore**. 4D offers several strategies to [ensure the security of the data in your datastore](https://developer.4d.com/docs/ORDA/privileges#restriction-modes). ## Configuring Datastore Permissions @@ -32,15 +24,16 @@ The
-:::info -By applying all permissions to the `ds` resource within the Restricted privilege and not assigning it to any role, you prevent malicious access attempts. This safeguard transforms the application into a secure vault. -::: - -Attempting to access the REST API endpoints will result in a `No permission to read for the Package dataclass` response, a rule that extends across all dataclasses. - - ## Full Access to Gradual Restriction -Alternatively, the `Guest` privilege provides another strategy for managing unauthorized users. This privilege allows full access to the entire datastore by default, with specific resources being restricted through other privileges achieved by applying [Dataclasses Permissions](dataClassPermissions.md). +Alternatively, the `guest` privilege provides another strategy for managing unauthorized users. This privilege allows full access to the entire datastore by default, with specific resources being restricted through other privileges achieved by applying [Dataclasses Permissions](dataClassPermissions.md). ### Introducing the Guest Privilege -When a role lacks specific privileges, the `Guest` privilege is assigned to that `Session`. This allows users without defined privileges to access non-restricted resources while preventing potentially harmful activities with other resources, ensuring that users interact within well-defined boundaries. +When a role lacks specific privileges, the `guest` privilege is assigned to that `Session`. This allows users without defined privileges to access non-restricted resources while preventing potentially harmful activities with other resources, ensuring that users interact within well-defined boundaries. :::info -The `Guest` privilege grants access to all resources if no explicit permissions are in place. +The `guest` privilege grants access to all resources if no explicit permissions are in place. ::: ### Configuring the Guest Privilege -The `Guest` privilege is established in the `Privileges` tab by default, ready to welcome users who have not yet established a formal identity. +The `guest` privilege is established in the `Privileges` tab by default, ready to welcome users who have not yet established a formal identity. ### Configuring Read Access -To grant read access to the `Guest` privilege, follow these steps: +To grant read access to the `guest` privilege, follow these steps: 1. Remove complete permissions control over the Datastore from the `Restricted` privilege. -2. Assign the Read permission specifically to the datastore within the `Guest` privilege, thereby endowing it with the capability of read-only access. +2. Assign the Read permission specifically to the datastore within the `guest` privilege, thereby endowing it with the capability of read-only access. -By making this change, the `Guest` privilege now allows users to access a wealth of data, including details about flights, hotels, and activities, while ensuring that critical information remains safeguarded against unauthorized modifications. +By making this change, the `guest` privilege now allows users to access a wealth of data, including details about flights, hotels, and activities, while ensuring that critical information remains safeguarded against unauthorized modifications. @@ -100,7 +86,7 @@ To balance data accessibility and security, the next crucial step is to utilize ## Guest Inherited Permission -Permissions of the `Guest` privilege are automatically inherited across various privileges. This parallels the behavior observed in the `Restricted` privilege, where the capability of reading from the **Datastore** is evident. +`guest` permissions are [granted to every session](https://developer.4d.com/docs/ORDA/privileges#guest-privilege). diff --git a/docs/4DQodlyPro/roles/example-of-configuration.md b/docs/4DQodlyPro/roles/example-of-configuration.md index 0e1b5a813..c95968974 100644 --- a/docs/4DQodlyPro/roles/example-of-configuration.md +++ b/docs/4DQodlyPro/roles/example-of-configuration.md @@ -4,9 +4,9 @@ title: Example of configuration --- import Column from '@site/src/components/Column' -This section is a tutorial that will show you how to configure roles and privileges for a HealthCare application handling patients and appointments, including confidential data. - -It includes the support of both **public** and **authenticated** [application accesses](../../QodlyinCloud/console/resourceMonitoring.md#application-access). +This example shows how to configure roles and privileges for a healthcare application that handles patients, appointments, and confidential data. +The application authenticates identities in its own `authentify()` function and calls [`Session.setPrivileges()`](https://developer.4d.com/docs/API/SessionClass#setprivileges) to assign roles to each session. +The rules below explain why each permission grants or denies access; see 4D's [privilege configuration rules](https://developer.4d.com/docs/ORDA/privileges#inherited-permissions) for details. ## Application overview @@ -25,27 +25,12 @@ The `AppSettings` dataclass is used only by the administrator to set up applicat ::: -### Users +### Identities and roles -The following personaes are identified, along with their access: +The application defines its own identities and validates them in its `authentify()` function. After authentication, this function calls `Session.setPrivileges()` to assign the appropriate role to the session. See the 4D documentation for [`authentify()`](https://developer.4d.com/docs/REST/authUsers#function-authentify) and [`Session.setPrivileges()`](https://developer.4d.com/docs/API/SessionClass#setprivileges). -**Mary** and **Arthur** are registered as [Qodly users](../../QodlyinCloud/console/userAccountManagement.md#users-page) and use the authenticated endpoint. The administrator [assigns them a role in the console](../../QodlyinCloud/console/userAccountManagement.md#edit-user-details).​ - - - -Once a Qodly app user is authentified, they can only run the actions allowed for the assigned role (because the privileges assigned to this role have the permissions to run specific actions on some resources). - -**X** will use the public access without any role and will be only able to run actions allowed for the public access.​ - -:::note - -The developer is free to implement an authentication for public users and to assign them a role. This case is not covered here.​ - -::: - - ### Actions In this example, only the **read** action is considered, to simplify the story. However, the exposed principles are the same for other actions (create, update...) ​ @@ -58,25 +43,25 @@ We want to configure the following accesses: -## Configuring registered users +## Configuring access ### Protecting all data -By default in new Qodly applications, **no permissions** are set up, which means that all data are available for any Qodly app registered user (Reminder: public endpoint is disabled by default).​ Thus, the initial configuration is: +In this example, **Restrict Access By Default** is off, so resources without an explicit permission are accessible. The initial configuration is: The first step in activating safety is to **protect all data** by default. Accesses will then be opened for each resource. -1. Create a **None** privilege with a granted **Read** action on the Datastore​. +1. Create a **None** privilege and grant it **Read** access on the datastore. -By the inheritance principles, the **whole datastore** is then protected. +The datastore permission is inherited by every dataclass. Since no role receives **None**, read access to the dataclasses is denied by default. -2. Do **never** assign this privilege to any role, so that the whole datastore will always remain protected by default​. +2. Never assign **None** to a role. As an alternative, turn on **Restrict Access By Default** in `roles.json`; resources without an explicit permission are then denied, so the **None** lock privilege is unnecessary. See 4D's [restriction modes](https://developer.4d.com/docs/ORDA/privileges#restriction-modes). ### Creating the viewPatient privilege @@ -91,17 +76,17 @@ By the inheritance principles, the **whole datastore** is then protected. -However, this privilege will give access to all patient data to the *Secretary* role, including by default any confidential. You still need to restrict access to this level of information. +The **Patients** dataclass permission replaces the datastore permission, so a session with **viewPatient** can read patient data without **None**. This also includes the `confidentialInfo` attribute unless a separate attribute permission is defined. ### Creating the viewConfidentialInfo privilege Only the *Doctor* role can view the patient's confidential data (gathered in a *confidentialInfo* attribute). -1. Create the *viewConfidentialInfo* privilege with a granted **Read** action on the `Patients.confidentialInfo` attribute.​ +1. Create the *viewConfidentialInfo* privilege with **Read** access on the `Patients.confidentialInfo` attribute. -2. Assign it to the *Doctor* role (see [roles](#roles) below). This will exclude all other roles). ​ +2. Assign it to the *Doctor* role (see [roles](#roles) below). Attribute permissions are added to the parent dataclass permission, so reading `confidentialInfo` requires **both** **viewPatient** and **viewConfidentialInfo**. The *Secretary* role has only **viewPatient**, so it cannot read that attribute. @@ -119,21 +104,16 @@ Here are the corresponding role definitions. -## Configuring public access - -By default in new Qodly applications, the public access is **disabled**. The public access is the access granted for public users (like **X**) without any role. - -1. [Activate the Public access explicitely](../../QodlyinCloud/console/resourceMonitoring.md#3-public-url-development-environment-only) in the console. - +### Allowing appointment reads -2. Allow the *guest* privilege to read the appointments. +Grant the built-in **guest** privilege **Read** access to the `Appointments` dataclass. -By default, **all users, including public users** have the [*guest* privilege](./datastorePermissions.md#introducing-the-guest-privilege). By simply allowing the *guest* privilege to read appointments, we allow all users, registered and not registered, to read the appointments. +The `Appointments` dataclass permission replaces the datastore-level **None** permission. Because every session has the built-in [**guest** privilege](./datastorePermissions.md#introducing-the-guest-privilege), all sessions can read appointments. ## The final picture @@ -141,4 +121,12 @@ Here is a complete overview of the roles and privileges for our HealthCare appli +### A common pattern + +A common configuration grants broad access through a **manager** privilege, then restricts one dataclass: for example, the `Salaries` dataclass requires the **payroll** privilege. A session must have **payroll** to access `Salaries`, because a dataclass permission replaces the datastore permission; **manager** continues to grant access to other dataclasses. + +### Recommended practice + +Grant access through roles. Create an administration role that includes every privilege except **None**, and add each new privilege to that role when it is created. With **Restrict Access By Default** off, review the **Detailed Permission Review** for every role after each permission change to confirm its effective access. See the 4D documentation on [roles, privileges, and permission rules](https://developer.4d.com/docs/ORDA/privileges#privileges-and-roles). + diff --git a/docs/4DQodlyPro/roles/includingPrivileges.md b/docs/4DQodlyPro/roles/includingPrivileges.md index 789953cf8..82aa4f95b 100644 --- a/docs/4DQodlyPro/roles/includingPrivileges.md +++ b/docs/4DQodlyPro/roles/includingPrivileges.md @@ -5,43 +5,21 @@ title: Including Privileges import Column from '@site/src/components/Column' -## Understanding Privilege Inclusion +## Overview -Privilege inclusion stands as a foundational concept in access control, involving the nesting of one or more privileges within another to create a hierarchical structure. This approach enables the inheritance of permissions, simplifying the management of access rights. +Privilege inclusion lets you combine existing privileges to build a reusable access-control structure. +An included privilege contributes its permissions to the privilege that includes it, helping avoid duplicate configurations. +This makes it easier to manage access consistently as application needs evolve. +Privileges can be assigned to roles to define what each group of users can do. -## Benefits of Privilege Inclusion -Privilege inclusion provides substantial advantages, enhancing the efficiency and flexibility of access control: +For example, `ManageFinancials` can include `ManageReports` to bring reporting permissions together with financial-specific access. +The resulting privilege can then be assigned to the `Financial Manager` role. -|Benefits | Purpose | Practical Application| -|---------|------------|----------------------| -| **Granular Control** |Empowers administrators for precise user access control.|In a healthcare system, it's used to manage access to patient records with healthcare providers granted access to only relevant medical information, ensuring fine-tuned control over sensitive data.| -| **Efficient Management**|Hierarchical privileges reduce redundancy in permission assignments.|In large enterprises, it's used to set overarching permissions for departments or roles. For example, a marketing team might inherit common access rights without individual configurations.| -| **Flexibility and Adaptability**|Enables a flexible and adaptable access control model.|In a rapidly evolving technology company, it's used to integrate access rights for new tools without disrupting existing configurations.| -| **Nuanced Access Restrictions**|Allows for nuanced access restrictions.|In a financial institution, it's used to enforce specific access restrictions for different departments. For instance, the finance team might have additional access rights to sensitive financial data, while other departments have restricted access.| +This approach keeps shared permissions in one place while allowing specialized privileges to add their own access rules. Use privilege inclusion to simplify administration while keeping access scoped to the needs of each role. +For details, see the 4D documentation on [privileges and roles](https://developer.4d.com/docs/ORDA/privileges#privileges-and-roles). - -## Including Privilege Use Case - -### Background - -The `ManageReports` privilege grants the `Sales Manager` role access to the `Reporting` dataclass, with the exception of the delete permission: - - - -However, the addition of the `ManageFinancials` privilege introduces specialized restrictions for anyone outside the financial department, including access to `netProfitMargin` and `totalExpenses` attributes and deletion permissions within the `Reporting` dataclass: - - - -### Intra-Privilege Relationships - -In a `Financial Manager` role, two privileges exist: `ManageReports` for reviewing and creating reports, and `ManageFinancials` for deleting reports or accessing sensitive data. - -In this case, the `ManageFinancials` privilege operates within the constraints set by the `ManageReports` privilege, adding supplementary permissions, ensuring nuanced control over data access. - -Given the structured inheritance of permissions, an efficient approach consolidates these into a singular privilege. By including `ManageReports` within `ManageFinancials`, a unified privilege is formed, providing the `Financial Manager` with streamlined permissions. - -### Including Privilege Configuration +## Including Privilege Configuration To include the `ManageReports` privilege within the scope of `ManageFinancials`: diff --git a/docs/4DQodlyPro/roles/modelEditorApproach.md b/docs/4DQodlyPro/roles/modelEditorApproach.md deleted file mode 100644 index a442520c1..000000000 --- a/docs/4DQodlyPro/roles/modelEditorApproach.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -id: modelEditorApproach -title: Model Editor Approach -draft: True ---- - -import Column from '@site/src/components/Column' - -In the **Model Editor**, link privileges to permissions for Datastore, DataClass, Attribute, and Function ressources. Adding permissions is done by clicking on the button in the dropdown list. Conversely, to remove an affected privilege, click on the button next to the privilege. - -:::info - - - - - - - - - - - - - - - - - - - - - - - - - -

- - - - -::: - - -## Datastore Permissions - - - - To configure Datastore permissions (e.g., Create, Read, Update, Delete and Execute), click on the Model for a streamlined dropdown selection to allocate desired privileges. - - - - - - - -## DataClass Permissions - - - - To configure Dataclass permissions (e.g., Create, Read, Update, Delete and Execute), click on a Dataclass for a streamlined dropdown selection to allocate desired privileges. - - - - - - - -## Attribute Permissions - - - - To configure Attribute permissions (e.g., Create, Read, Update and Delete), click on an Attribute within a Dataclass for a streamlined dropdown selection to allocate desired privileges. - - - - - - - -## Function Permissions - - - - To configure Function permissions (e.g., Execute and Promote), click on a Function within a Dataclass for a streamlined dropdown selection to allocate desired privileges. - - - - - \ No newline at end of file diff --git a/docs/4DQodlyPro/roles/permissionsFunctionLevel.md b/docs/4DQodlyPro/roles/permissionsFunctionLevel.md index 097f2cab7..88d501d9d 100644 --- a/docs/4DQodlyPro/roles/permissionsFunctionLevel.md +++ b/docs/4DQodlyPro/roles/permissionsFunctionLevel.md @@ -5,7 +5,6 @@ title: Function Permissions import Column from '@site/src/components/Column' -## Purpose and Scope Function-level permissions control access to custom functions defined within the Model. These functions can perform actions such as managing bookings, generating invoices, and handling reservations. @@ -79,78 +78,6 @@ After the function concludes, the temporary elevation from the `Promote` permiss
-:::tip -Refer to the use case of the [`Promote`](#promote-permission-use-case) permission for detailed configuration information. -::: - - -## Strategies - -### Max Restriction to Gradual Expansion - -To control function execution, the **DataStore** level is configured exclusively for the `Restricted` privilege, ensuring that only roles with this privilege can execute functions, thus preventing any unauthorized access. - - - -

- -:::info - - - - Hovering over the icon reveals that all functions throughout the model — encompassing DataStore, Dataclasses, Entity selections, and Entities — have the execute permission for the Restricted privilege. - - - - - - -::: - -However, to accommodate scenarios where the `Agent` role needs to execute functions, such as the `book` function within the `roomOptions` Entity class, a gradual expansion involves adding the `book` function resource and checking the execute permission. - - - -

- -:::info -In this context, the `bookRoom` privilege overrides function permissions set at the **DataStore** level (`Restricted`). -::: - -### Full Access to Gradual Restriction - -If no `Execute` permission is set at any level, it grants full access to all functions defined throughout the Model. Gradual restriction involves using other privileges to restrict specific function execution, as seen in the `Employee` DataClass, where the `register()` function execution is restricted to specific privileges. - - - -## Promote Permission Use Case - -### Scenario Overview - -In a travel agency's system, dynamic pricing analysis recalculates travel package prices based on demand, seasonal trends, and competitor pricing. Key roles include: - -- The `Sales Manager` role fully controls Read access to the `Pricing` Dataclass, including the execution of its functions (Dataclass functions, entity functions, and entity selection functions), such as the `analyzePricing` function, to ensure confidentiality. - -- Although the `Agent` role is restricted from accessing the `Pricing` Dataclass, there are specific scenarios where the `Agent` may need to utilize the `analyzePricing` function to conduct a pricing analysis in response to special requests. - -### Promote Permission Configuration - -If an `Agent` receives a special request, they need `Execute` permission for the `analyzePricing` function to generate a customized pricing quote. This allows users with the `Agent` role to directly execute the function. - - - -However, due to restricted access to the `Pricing` Dataclass limited to the `Sales Manager` role: - - - -Executing the function code attempting to `Read` data from it would result in a `No permission to read for the Pricing dataclass` error. - -Therefore, It becomes essential to include `Promote` permission for the `analyzePricing` function within the `ManageFinancials` privilege: - - - -

- :::info @@ -162,8 +89,5 @@ Therefore, It becomes essential to include `Promote` permission for the `analyze ::: -This configuration explicitly specifies that when the `analyzePricing` function is executed within a session holding the `Agent` role, which lacks permission for the `Pricing` resource, it temporarily integrates the `ManageFinancials` privilege into that session during function execution. This temporary elevation allows the function to be executed without granting permanent access. -:::tip -Add the `Execute` permission in the privilege associated with the role that needs to directly perform the function. Meanwhile, the `Promote` permission is configured in the privilege that grants broader control over the resources involved in the function, providing a temporary elevation of privileges during the function's execution. -::: + diff --git a/docs/4DQodlyPro/roles/permissionsOverview.md b/docs/4DQodlyPro/roles/permissionsOverview.md index e4cdc830a..973c7ef26 100644 --- a/docs/4DQodlyPro/roles/permissionsOverview.md +++ b/docs/4DQodlyPro/roles/permissionsOverview.md @@ -14,26 +14,27 @@ When no specific permission has been defined for a resource, access to the resou Permissions define essential actions on resources, covering tasks such as creation, reading, updating, deletion, description, execution (for functions), and promotion (also for functions). -| Permission | Datastore | Dataclass | Attribute | Function | -|------------|-----------|-----------|-----------|----------| -| Create | Create an Entity in any Dataclass. | Create a new Entity in the chosen Dataclass. | Create a new Entity with a value different from the default allowed for the chosen Attribute. | n/a | -| Read | Read Attributes in any Dataclass. | Read attributes in the chosen Dataclass. | Read the content of the chosen Attribute. | n/a | -| Update | Update Attributes in any Dataclass. | Update attributes in the chosen Dataclass. | Update the content of the chosen Attribute. | n/a | -| Delete | Delete data throughout the Model. | Delete data in the chosen Dataclass. | Delete a non-null value for the chosen Attribute. | n/a | -| Execute | Execute all functions throughout the Model, including DataStore, Dataclasses, Entity selections, Entities, as well as Singleton functions| Execute any function on the chosen dataclass (Dataclass functions, entity functions, and entity selection functions). | n/a | Execute the selected function. | -| Promote | n/a | n/a | n/a | Temporarily adds a specific privilege to the session during function execution, primarily for secure privilege escalation. | +See the [permission action description in the 4D documentation](https://developer.4d.com/docs/ORDA/privileges#permission-actions). +Note that the **Delete** column is the `drop` action in the `roles.json` file. -## Default restriction modes -The **Restrict Access by default** selector allows you to configure how resources (i.e. datastore, attributes, functions, etc.) are accessed when no specific permission is defined for them: +## Options -- **Unrestricted mode** (selector off): Resources without defined permissions are accessible to all requests. This mode is suitable for development environments where access can be gradually restricted. -- **Restricted mode** (selector on): Resources without defined permissions are blocked by default. This mode is recommended for production environments where access must be explicitly granted. +### Restrict Access by default -For more information on the restriction modes, please refer to the [4D documentation](https://developer.4d.com/docs/ORDA/privileges#restriction-modes/). +This selector allows you to configure how resources are accessed when no specific permission is defined for them. It is set by default. + +For information on the restriction modes, please refer to the [4D documentation](https://developer.4d.com/docs/ORDA/privileges#restriction-modes/). + + +### Force login + +This selector helps you to control the number of opened web sessions that require 4D Client licenses. It is set by default. + +See the [**Force Login** page](../force-login.md) for more information. ## Managing permissions @@ -71,13 +72,14 @@ Users can check the desired filter options to display only the relevant permissi To create a new permission in the current privilege: -- Click on the `+ Create a permission` bar . +- Click on the `Create a permission` dropdown menu . -- A dropdown menu will display a list of available assets (e.g., Datastore, Functions, Singletons, Attributes). +- The menu displays a list of available assets (e.g., Datastore, Functions, Singletons, Attributes, datastore functions (`ds.myFunction`)). - Select the desired asset to create and configure its permissions. +Resources already displayed in the grid (including rows coming from included privileges) are not offered in the dropdown: click their row instead. ### Assign Permissions @@ -97,7 +99,7 @@ The reset functionality allows users to clear all permissions for the current pr ### Clean Non-Existing Resources -If a resource is unavailable (e.g., an attribute name from the Tag DataClass was deleted), it appears in red in the permissions table. A shadow effect is applied to indicate that the resource no longer exists. The resource icon also turns red, providing a clear visual indication of its unavailability. +If a resource is unavailable (e.g., an attribute name from the Tag DataClass was deleted), it appears in red in the permissions table. A shadow effect is applied to indicate that the resource no longer exists. The resource icon also turns red, providing a clear visual indication of its unavailability. The privilege card also shows "This privilege uses non-existing resources". Also, the clean button to remove permissions, related to resources that no longer exist, becomes enabled. @@ -116,43 +118,16 @@ Also, the clean button to remove permissions, related to resources that no longe When all resources are available, the Clean button is disabled. ::: -## Inheritance - -In managing access control within your application, understanding the hierarchy and how permissions can override one another is crucial. Permissions can be set at various levels—**Datastore**, **DataClass**, and **Attribute**—each with the ability to override or supplement permissions set at higher levels. This hierarchical structure allows for granular control over user access to resources. - - -### General Principle - -The permissions hierarchy is structured as follows: - -1. **Datastore Level**: This is the broadest level of permissions. Permissions set at the datastore level apply to all resources within the datastore unless specifically overridden at a lower level. The *execute* permission action defined at the datastore level applies to all functions of the project, including all exposed singleton functions. - -2. **DataClass Level**: Permissions set at the DataClass level apply to all attributes and functions within that DataClass. These permissions can override or supplement those set at the datastore level for that specific DataClass. - -3. **Attribute Level**: This is the most granular level. Permissions set at the attribute level apply to individual attributes within a DataClass. These permissions can override or supplement those set at both the datastore and DataClass levels for that specific attribute. - - -### Inheritance Flow +## Inheritance -Permissions set at a higher level are automatically inherited by lower levels unless explicitly modified. This means: +The engine resolves permissions per resource and per action: a dataclass or function permission replaces the datastore one, an attribute permission adds a condition. For a detailed description of inheritance principes, see the [**Inherited permissions** section in the 4D documentation](https://developer.4d.com/docs/ORDA/privileges#inherited-permissions). -- **DataClass-level permissions inherit from datastore permissions** for that DataClass and its attributes. -- **Attribute-level permissions inherit from both datastore and DataClass permissions** for that attribute. - -:::info Example: Inheritance from Datastore to DataClass** - -- **Scenario**: The datastore grants `Read` permission to all users. - -- **Result**: All DataClasses and their attributes inherit the `Read` permission, allowing users to read data from any DataClass unless overridden. -::: - -If you don't set specific permissions at a lower level, the resource will inherit the permissions from the higher level. ### Show/Hide Inherited Permissions - When managing permissions, you can toggle between showing and hiding inherited permissions. By default, inherited permissions are visible, allowing you to see which permissions a privilege has inherited from other privileges for a resource. You can toggle off this option to hide any inherited permissions and focus only on permissions explicitly defined within the current privilege. + When managing permissions, you can toggle between showing and hiding permissions coming from **included privileges**. By default, inherited permissions are visible, allowing you to see which permissions a privilege has inherited from other privileges for a resource. You can toggle off this option to hide any inherited permissions and focus only on permissions explicitly defined within the current privilege. @@ -163,28 +138,7 @@ If you don't set specific permissions at a lower level, the resource will inheri - **Disabled**: Hides inherited permissions defined for resources. If a resource's permissions are entirely inherited and no explicit permissions are defined in the current privilege, the entire resource row will be hidden. If an explicit permission exists (e.g., Execute) for a resource, only the inherited permissions (e.g., Create) are unchecked while the resource row remains visible. -## Overrides - -### General Principle - -While permissions inherit from higher levels, you can override them at more specific levels. This means: - -- **Attribute-level permissions can override DataClass and datastore permissions for that attribute.** -- **DataClass-level permissions can override datastore permissions for that DataClass and its attributes.** - -Overrides allow you to refine access control by setting exceptions to the inherited permissions. - -### Overrides Flow - -- **Override at DataClass Level**: If you need a DataClass to have different permissions from the datastore defaults, you can set permissions specifically for that DataClass. - -- **Override at Attribute Level**: For individual attributes that require different permissions from their DataClass, you can set permissions specifically for those attributes. - -:::info Example: Overriding Datastore Permissions at the DataClass Level -- **Scenario**: You want to restrict access to the `Employee` DataClass, despite the datastore granting `Read` permission. - -- **Action**: At the DataClass level for `Employee`, remove the `Read` permission. -- **Result**: Users cannot read data from the `Employee` DataClass, even though the datastore allows reading from other DataClasses. +The privilege grid shows the permissions defined in the privilege and, with the toggle, those of its included privileges; it does not show what a dataclass, attribute or function inherits from the datastore, nor what a dataclass permission replaces. -::: \ No newline at end of file +The effective permissions are shown in the **Detailed Permission Review** of a **role**. \ No newline at end of file diff --git a/docs/4DQodlyPro/roles/rolesPrivilegesOverview.md b/docs/4DQodlyPro/roles/rolesPrivilegesOverview.md index 3d3a70eec..4d325cb81 100644 --- a/docs/4DQodlyPro/roles/rolesPrivilegesOverview.md +++ b/docs/4DQodlyPro/roles/rolesPrivilegesOverview.md @@ -11,14 +11,12 @@ import Column from '@site/src/components/Column' Roles are essential in defining distinct user profiles within Qodly. Each role corresponds to a specific set of privileges, and access levels (Permissions). -### Role Hierarchy - -Roles can be structured hierarchically, allowing for an organized and layered access control system. In Qodly, higher-level roles can inherit the **privileges** of lower-level roles, creating an efficient method of managing user access. This hierarchy enhances the granularity of access management and facilitates a streamlined approach. - ### Detailed Permission Review for Roles When a role is selected in the `Roles & Privileges` editor, a detailed permission review is displayed to provide insight into the final permissions resolution for that specific role. This feature helps developers fine-tune privileges more effectively by showing the impact of privilege configurations. +This review is available on **roles only, by design**: roles are the recommended way to give access, so the effective permissions are shown where they apply. The review is computed from the [role's privileges plus `guest`](https://developer.4d.com/docs/ORDA/privileges#privileges-and-roles). + @@ -36,7 +34,7 @@ When a role is selected in the `Roles & Privileges` editor, a detailed permissio - Singletons - Singleton Functions -- Permission Columns: For each asset, the following columns display resolved permissions: Read, Create, Update, Delete and Execute. +- Permission Columns: For each asset, the following columns display resolved permissions: Read, Create, Update, Delete and Execute. The **ds** row shows the permissions defined on the datastore, not a summary of the dataclasses below (expand the row to see them). :::tip Permission Indicators A grey tick indicates that the permission is granted. @@ -46,13 +44,10 @@ If the access is granted through promoted privileges, an info indicator indicates that the permission is not granted. ::: +:::tip -:::info Impact of Privilege Changes -Displaying permissions explicitly helps identify the consequences of modifications in privileges, such as: +To see what a session without role can do (before login, i.e. guest only), create a role with no privilege and look at its review. -- Adding permissions to a privilege included in a role. -- Removing permissions from a privilege that is not included in any role. -- Promoting a function execution in a privilege will apply the promotion universally, regardless of roles. ::: @@ -64,8 +59,14 @@ To add a role: 2. Navigate to the `Roles and Privileges` section. 3. Click on the `Roles` tab to access role management. 4. To create a new role, click on the `+` button next to Roles. +5. Enter the name of the role in the creation dialog box and click **Create** or **Cancel**. +To edit or delete a role: +1. Select a role in the list. +2. Click on the `pencil` icon to rename it, or on the `trash` icon to remove it. + +Renaming updates every reference; deleting asks for confirmation and removes the privilege from roles, inclusions and permissions. :::note Example In a back-office travel agency solution, you might create roles such as: @@ -92,11 +93,19 @@ To add a privilege: 2. Navigate to the `Roles and Privileges` section. 3. Click on the `Privileges` tab to access privileges management. 4. Click on the `+` button to create a new privilege. +5. Enter the name of the privilege in the creation dialog box and click **Create** or **Cancel**. +

+ +### Guest + +The `guest` privilege is always present. It cannot be renamed, deleted or included. [See the 4D documentation](https://developer.4d.com/docs/ORDA/privileges.md#guest-privilege) for more information on the `guest` privilege. + + :::note Example In a back-office travel agency solution, you might create privileges such as: @@ -137,28 +146,35 @@ To assign one or multiple privileges to a role: 1. Navigate to the `Roles` tab within the `Roles and Privileges` section. 2. Select the desired role (e.g., `Sales Manager`). -3. Locate the privileges section on the top. -4. In this section, you'll find a comprehensive list of available privileges. -5. To assign a privilege, click the `+` icon. -6. To remove a privilege, simply click the `-` icon. +3. Locate the privileges section on the top. + + - In this section, you'll find a comprehensive list of available privileges. + - `guest` is shown selected (italic) on every role and cannot be removed; it is not written in the role + +4. To assign a privilege, click the `+` icon. +5. To remove a privilege, simply click the `-` icon.

+ :::note Example For instance, a `Sales Manager` role might possess privileges like `ManageBookings` and `ViewReports`, granting them the ability to analyze booking trends and monitor revenue for informed decision-making. Similarly, a `Content Manager` role could receive the privilege `ManageContent`. ::: ## Assigning Roles and Privileges -Roles and privileges are assigned to **user sessions** using the [`Session.setPrivileges()`](https://developer.4d.com/docs/API/SessionClass#setprivileges) function of the `4D.Session` class. +Roles are assigned to **user sessions** using the [`Session.setPrivileges()`](https://developer.4d.com/docs/API/SessionClass#setprivileges) function of the `4D.Session` class. + +It is recommended to assign **roles** rather than **privileges**: you define one role per user profile, assigned to the session. Although 4D allows you to assign privileges directly, this should be the exception. A privilege is merely a building block; it is the role that describes what a user can do. + ## Roles and privileges JSON Representation -In Qodly Studio, roles and privileges have a JSON representation that can be useful for troubleshooting or copying selected parts. +Roles and privileges are stored in dedicated file named `roles.json`. [See the 4D documentation](https://developer.4d.com/docs/ORDA/privileges#rolesjson-file) for more information about this file.