Advanced permissions in Retool: The Fundamentals (Retool for Enterprises)

Managing permissions in complex systems is notoriously challenging, and Retool can be no different. If approached without a deeper understanding of how Retool permissions work, it's easy to get your apps, resource and user access in a tangle. We've worked with many organizations struggling to regain control over convoluted permissioning setups, particularly when their app infrastructure has scaled faster than they first expected.

For this reason, we always advocate for companies to - where possible - implement a Retool-friendly permissions structure from the very beginning that allows for scale. Careful planning and a better knowledge of the intricacies of the Retool Permissions settings is essential for Enterprise deployments.

In our next few Retool for Enterprise articles, we will be focusing specifically on permissions, covering the fundamentals here first, before discussing the different approaches you can take and how you can apply them in Retool.

Need more help than this article? Reach out to us!

Retool pricing plans and permissions features

Firstly, it's important to know that your permission features depends on your Retool pricing plan.

For small teams: The Free and Teams plans are suitable for smaller teams who don’t have a significant need for granular permissions. The Free plan does not offer permission features, so each user has full access, meaning all users can build and edit apps without role distinctions. The Team plan introduces basic role-based permissions for roles Viewer, Editor, or Admin. Any editor has access to edit all apps and resources.

This article is written for larger organizations on Retool who need more complex permissioning structures, so we’ll be assuming readers have the Business plan or Enterprise. Here are the key distinctions between those plans when it comes to permissions:

Business Plan: Suited for larger organizations, the business plan allows you to create new permission groups instead of relying on the Viewer, Editor and Admin groups. This is the minimum plan that we would recommend for teams with more granular permissions requirements.

Enterprise Plan: For those on Enterprise plans, you get access to enterprise-grade features like pushing groups from Okta and environment-level source control. The ability to differentiate environment permissions is particularly important for QA teams to have access only to staging resources.

Permissioning in Retool: The fundamentals

For you to make the right choice when choosing a permissioning pattern (which we'll talk more about in Permissions Part II), it's essential to understand Retool’s multiple layers of permissions. Though the Permissions UI in the environment settings can seem straightforward, it’s important to understand the nuances of each setting as you use them.

The apps, resources and workflow tabs allow you to define ‘Use’, ‘Edit’, and ‘Own’ access for users, but these settings mean different things for each tab, and these settings impact each other.

An example. If you give someone ‘use’ access to an app, but they don't have ‘use’ access to the resource inside of it, the queries that use that resource will not execute and will produce an error response. So, if a user has ‘use’ access to 2 out of 3 resources that are used in an app, the first two will work as expected, but the third (without ‘use’ access) will consistently fail.

To give you a better understanding of these granular settings, we’ll quickly run through what each of these permission types mean, as well as what settings to look out for in the ‘additional’ tab.

Resource permissions

In custom groups (outside of the editor, viewer and admin groups), you can specify exactly what type of access the group has to each resource in your environment. Although there are three boxes to toggle between, there are technically four states, as none selected means ‘no access’. You can only select one permission type, as each type builds on the permission access of the former.

Here’s what those permission types really mean when it comes to working with or using resources:

• Nothing toggled state - the user can’t run the resource even if they have access to an application that uses it. When performing an action like reading or writing data that is contingent on the resource, it will display an error message similar to: “you do not have access to  {{uuid}} resource”.
• Use - if the resource setting is toggled to Use, this means that the user, if they have access to an app, can run any queries connected to that resource within the application. Importantly - though they can run queries connected to the resource in ‘User’ mode, they cannot perform any edits on the query in ‘Edit’ mode, even if they have edit access to the app it uses.
• Edit - the Edit toggle includes the same access as Use but also allows the user to edit and create queries for the resource in the ‘Editor’ mode inside of Retool. Here, they can create, edit and delete any queries made against the resource within an application they have edit access to. Something to note here is that they can also see the resource’s configuration inside the resource page inside Retool (though cannot edit them).
• Own - Own includes all access in Use and Edit but also allows the user to edit the configuration of the resource (the connection settings), rename, and move the resource around into different folders. This means effectively giving this group managerial access over the resource.

When managing resource permissions, it’s essential to be wary of the ‘Query library’ setting in the Additional tab, as this can potentially overwrite resource access. We talk more about this in the ‘Additional tab’ section below.

App permissions

Similarly to the resource permissioning, the application section allows No access, Use, Edit and Own permissions, but note that the ability to use the applications  also depends on the access these users have to the resources included in apps.

• Nothing toggled state - if the user gets routed to this app or page, they will get an error message that says they don’t have access to the app. They will not see the app in the root directory.
• Use - The Use toggle means that the user group can only open the application in ‘User mode’. However, they will also need the correct permissioning (at least Use) to the app's respective resources to perform the queries within the app.
• Edit - This gives the same access as Use, but the edit toggle here means that this group can also access the application in ‘Editor mode’. This means that in ‘User mode’ they will see the black Retool header bar and the toggle to Edit the app in the right-hand corner. Once in ‘Editor mode’ they can run queries in the code tab for the resources for which they have Use access, and edit the ones for which they have Edit access. They can also delete these applications.
• Own -  similarly to the resources, Own is predominantly the administrative toggle for applications. ‘Owners’ have all access from Use and Edit, but this setting allows these users to rename these apps, reorganize them in the Retool directory folders and export them to JSON or Toolscript.
  

Workflow permissions

Workflow permissions work similarly to the App and Resource permissions, with a few small but crucial differences. Ultimately, Workflows are typically a chain of actions with a single trigger, and this trigger determines the access to run the workflow. If a user has some kind of access to trigger it, the workflow will execute regardless of the other permissions that user may have.

Keep in mind: users who have Use access to an application as well as Use access to a Workflow, but who might not have underlying resource access, can still trigger and run a workflow that includes those resources.

• Nothing toggled state - The Workflow is not visible in the Workflow section, they cannot run the Workflow from within the queries section of the Retool editor, nor can they trigger the workflow.
• Use - groups with Use access can press the play button to execute the Workflow or trigger it from an app, but cannot edit any part of the workflow in 'Editor mode'. As noted above, they do not also need resource access to trigger a workflow that uses a resource.
• Edit - groups with Edit access can trigger the workflow but they can also edit it. Importantly however, Editors can’t edit or create any steps including resources they don’t have access to edit. So, in order to properly create and edit Workflows, Editors need Edit access to all resources involved.
• Own - 'Owners' have all the permissions above, but can also rename or delete Workflows.
  

Additional tab: Essential errors to avoid

⚠️ Beware: Often overlooked, the ‘Additional’ tab section has a few potential security risks.

The first is the Query Library. If this Query Library checkbox is toggled on for a group, this means that they can perform shared queries and potentially run queries from within the query library page that they don’t necessarily have access to via the resource permissions we went through above.

‘Allow access to unpublished releases’ is the one of the riskiest settings in the Additional settings tab that often goes unnoticed. Allowing access to unpublished releases allows a user to go back in history and potentially run previously deleted queries from previous versions of the application. By default this is toggled on and often goes unchecked when launching an application. For large orgs it’s very easy for this to cause a large security issue, especially as users can accidentally gain access to older releases without realizing.

Finally, and probably most importantly is the ‘View audit logs’ toggle. If switched on, this allows a user to go to the audit log page and query the audit logs. The audit logs include the data that has been returned from the query, which means they can show PII and other sensitive data to users auditing, without recording what data was shown to them. It's essential that this toggle is toggled off for end users so that they can’t access secure data without this being logged.

We talk a little more about security tips like these in the Enterprise Security Checklist we recently released with the Retool Center of Excellence team.

Essential tips for permissioning in Retool

Now we've run through the fundamentals of Permissions in the Retool UI, here are six essential tips for working with the system best.

1. All Users: When you add a new user to your Retool environment, they will automatically be added to the All Users group. This is why it’s best practice to not set any permissions via this group, as it can be hard to maintain securely. The All Users group should only give access to the platform and should have all settings in ‘Additional’ (as mentioned previously) toggled off.
2. Editor and Viewer groups: These groups should also be avoided for large deployments as the permissions and security becomes difficult to manage as engineering teams and users grow.
   - If any user is in the Editor group, they have edit access to all apps and resources, which is generally unsuitable as your infrastructure grows. This actually also gives them Own settings for all resources, exposing the resource configuration and connection settings.
   - Likewise, anyone in the Viewer default group has full access to apps and resources, and can therefore perform any action across any app in that environment. These groups are often used at the beginning of Retool buildouts as they allow for simpler structures, but it’s best to move away from them as soon as you can.
3. Release versions toggled off: We already mentioned the ‘Release versions’ toggle in the ‘Additional’ section, but we’ll put it here again for good measure as this setting is toggled on by default. When making any new group, always ensure this has been switched off before continuing.
4. Retool Enterprise plan: For those on the Enterprise plan, you can also configure all of these permissions on the environment level. In the permissions settings you can therefore click the ‘show’ toggle for each resource or app and decide the specific environment resource (e.g. staging vs production). This is particularly useful for QA teams because they can be given access to staging resources without exposing production data.
5. User group admins: A group admin can add or remove users (members) in their groups, but they can’t change any of the actual granular access settings to apps, workflows or resources. Therefore, it makes most sense to use the User group admin role to assign non-technical managers the ability to manage their team, not to engineers who need to access the permissions settings themselves.
6. Folders: be wary with giving access on a folder-level, as any new app added to that folder will inherit those permissions, and this is where mistakes can easily be made. When applications, resources or workflows are placed within folders, you can define access to the parent folder or the nested objects specifically within them. We suggest sticking to a single pattern: either sticking to folder level access or single page access. If you do apply permissions via folders, you must have a rigid folder organization system to ensure no mistakes are made.  
   

That’s it for the fundamentals of Permissions in Retool - but we have plenty more to say! In Part II, we’ll offer some suggestions for approaches to permissions in Retool that Enterprise organizations can use to ensure watertight internal app infrastructures. We’ll specifically focus on the importance of formatting your permissions groups carefully. Stay tuned!