Skip to main content

Run workflows against enforced resources

Give workflows a run identity so triggered runs work on resources with data access enforcement turned on.

Queries for enforced resources need an identity to evaluate access policies against. Identity evaluation depends on the type of run:

  • Runs that a person starts use that person's policies.
  • Runs triggered by a schedule, a webhook, a query, an email sent directly to the workflow, or another agent through an A2A call, use the service user set as the workflow's run identity. Retool blocks these runs when the workflow has no run identity.

This guide explains how to give a workflow a run identity and grant its service user access to an enforced resource.

Requirements​

  • An Enterprise plan.
  • A PostgreSQL resource. Access policies are supported only for PostgreSQL.
  • Edge 4.78 or later for self-hosted instances. On earlier Edge versions, use a separate resource instead.
  • Edit access to the workflow and membership in the group you want it to run as.
  • Own access to the resource, to create or change access policies.

Assign a run identity to the workflow​

Choose the group whose access the workflow needs. The group's service user is the identity that triggered workflows use. For more information, refer to Run a workflow as a service user.

  1. Open the workflow in the workflow IDE.
  2. Open the Triggers panel.
  3. In the Run Identity section, click the Service user dropdown and select a group. The list contains the groups you belong to.
  4. Review the resources listed for the group. A service user run fails on queries against a resource the group can't access.
  5. Publish the workflow. The run identity applies to runs of the published version.

Grant the group access to the resource​

The group needs Use access to the resource. Refer to Manage permissions for resources for more information on setting environment-specific permissions on the resource. Access policies can narrow what a group reaches but can't grant access that the group's resource permissions deny.

Grant the group access in a policy​

Create an access policy that applies to the group selected in the Service user dropdown, or add the group to an existing policy. Grant only the tables and columns that the workflow queries. Refer to Configure access policies for the steps.

A service user's current_user.email is null, so a row filter that uses {{ current_user.email }} can't be resolved for its runs. Retool blocks those queries. Refer to Restrict rows with filters.

Verify the workflow​

Run the workflow from a trigger and confirm that every block succeeds. If a query is blocked, check audit logs for the policy that applied. Refer to Troubleshooting access policies for common causes.

Use a separate resource instead​

If a workflow can't have a run identity, you can point it at a second resource that doesn't use enforcement. This keeps the workflow running, but the workflow resource isn't governed by access policies.

To govern apps and users with access policies while these workflows keep running, you can create two resources for the same database. One resource has enforcement turned on and serves everything users run. A second resource has enforcement turned off and is used only by the affected workflows.

Caution

The workflow resource is not governed by access policies. Anyone who can query it, or edit a workflow that queries it, can access whatever its database credentials allow. A best practice is to narrow access to the resource on both sides. Limit what its credentials can access in the database, and limit who can use it in Retool.

How the two resources differ​

Both resources connect to the same database. They differ only in whether enforcement is on and who uses them.

ResourceData access enforcementQueried by
Enforced resourceOn.Apps, the query library, raw SQL, agents, workflow runs Retool can attribute to a user, and workflow runs that have a run identity.
Workflow resourceOff.Workflow runs Retool cannot attribute to a user and that have no run identity.

Access policies on the enforced resource have no effect on the workflow resource.

Create a database role for the workflow resource​

Because access policies do not apply to the workflow resource, its database credentials are what limits the data it can access. Create a dedicated role granting only what your workflows need, instead of reusing the credentials of the enforced resource.

CREATE ROLE retool_workflows LOGIN PASSWORD 'a-strong-password';
GRANT CONNECT ON DATABASE orders TO retool_workflows;
GRANT USAGE ON SCHEMA public TO retool_workflows;
GRANT SELECT ON public.orders TO retool_workflows;
GRANT INSERT, UPDATE ON public.order_events TO retool_workflows;

A role with broad access undoes the policies on the enforced resource because the data will be accessible through the workflow resource.

Create the workflow resource​

Refer to Create a PostgreSQL resource for how to create a resource with data access enforcement turned on.

  1. Create an additional PostgreSQL resource.
  2. Give it a name that states what it is for, such as Orders database (workflows), so builders do not select it by mistake.
  3. Enter the same host, port, and database name as the enforced resource.
  4. Authenticate with the role you created in the previous section.
  5. Configure every environment your workflows run in.
  6. Leave Data access enforcement turned off.

Restrict who can use the workflow resource​

Access levels are the only Retool control on this resource. Grant Use access to the group that maintains these workflows, and grant nothing to everyone else. Use access allows a group to create and edit queries against a resource from within workflows, so anyone who has it can query whatever the role you created can allow.

Refer to Manage permissions for resources for more information on setting environment-specific permissions on the resource.

Move workflow queries to the workflow resource​

note

Move the workflow queries before you turn on data access enforcement for the other PostgreSQL resource, so workflow runs don't fail.

For each workflow that queries the database and has runs Retool cannot attribute to a user:

  1. Open the workflow.
  2. Select each block that reads from or writes to the database.
  3. Change its resource to the workflow resource.
  4. Run the workflow and confirm every block succeeds.

Once workflow queries run against the workflow resource, turn on data access enforcement for the original resource and create access policies for your apps and users. Refer to Configure access policies for more information.