Dag-level access control
Dag-level access control
Dag-level access control
If you use Dag-level access control, forward authentication must use the Deployment-based endpoints, not the older org-based endpoints.
When you click Navigate to Airflow in the Astro UI, the correct Deployment-based URL appears in your browser address bar.
Deployment-based URLs follow this format:
<deployment-id>.<last-two-characters-of-deployment-id>...
You only need to reference or configure these endpoints if you are setting up custom ingress, reverse proxies, or other advanced integrations.
Dag-level access control permissions are enforced at the Deployment level, and using the older org-based URLs can result in incorrect permission enforcement or authentication failures. Note that you may still be feature-flagged to use the older URI format. Contact your account team to enable the new Deployment-based forward auth URLs to use Dag-level access control.
Astro supports Dag-level role-based access control (RBAC), which adds a fourth tier to the Astro access control hierarchy: Organization > Workspace > Deployment > Dag. Dag roles grant per-Dag permissions to users, Teams, and API tokens within a specific Deployment, so you can enforce least-privilege security and enable multiple teams to collaborate in a single Deployment without exposing Dags across team boundaries.
When you assign a Dag role, you bind it to Dags using either Dag tags or Dag IDs:
Use Dag tags for your role bindings whenever possible. Tag-based bindings scale automatically as you add new Dags, so you won’t need to update role assignments every time a new Dag is deployed. For example, tagging all Dags owned by a team with team:analytics lets you assign a single Dag role that covers all current and future Dags for that team.
Astro provides two default Dag roles that you can assign to users, Teams, and API tokens:
To create roles with more granular permissions, see Create a custom Dag role.
You can assign Dag roles to Teams so that all Team members share the same Dag-level permissions.
You can assign Dag roles to Organization, Workspace, and Deployment API tokens to give them fine-grained access to specific Dags within a Deployment. Direct Access tokens can’t be assigned Dag roles.
To assign a Dag role to an Organization API token:
Organization Owners can view and manage all of a user’s Dag role assignments from a centralized page.
In the Astro UI, click Organization Settings > Access Management.
Click Users, then click the user whose Dag access you want to view.
Click the Dags tab.
The Dags tab lists explicit Dag role assignments across all Deployments. Users may also have additional access through their Deployment, Workspace, or Organization role, or through a Team membership. The table shows the following columns:
To edit a user’s Dag role:
Open the More actions menu (…) next to the Dag entry you want to update and select Edit role.
In the Edit Dag Access slide-out, select a new Dag role. The Dag ID and Deployment fields are read-only.
Click Save changes.
To remove a user’s access to a Dag, open the More actions menu (…) and select Remove.
Organization Owners can view and manage all role assignments for a specific Dag from the Dag’s Access Management page. This provides a Dag-centric view of access, showing all users, Teams, and API tokens that have roles on a particular Dag.
In the Astro UI, open the Dags page for your Deployment.
Open the More actions menu (…) for the Dag you want to manage and click Access Management.
The Access Management page shows three tabs:
Roles assigned by Dag ID can be added, edited, or removed from this page. Roles assigned by Dag tag are view-only because they are managed through the tag-based binding. To edit a tag-based role, go to Organization Settings > Access Management and manage the role from the entity’s Dags tab.
Click the tab for the entity type you want to add (Users, Teams, or API Tokens).
Click + User, + Team, or + API Token, depending on the selected tab.
In the slide-out:
Open the More actions menu (…) next to the entity you want to update.
Click Edit role to change the Dag role, or click Remove from Dag to remove the entity’s access to the Dag.
You can create custom Dag roles with granular permissions at the Organization level. After you create a custom Dag role, you can assign it to users, Teams, and API tokens for any Dag in any Deployment in the Organization.
In the Astro UI, click Organization Settings.
Go to Access Management, then click Roles.
Click Custom, then click + Add Role.
In the slide-out that appears, set the Scope dropdown to Dag.
Enter a Name and Description for the role.
(Optional) Use the Copy from an existing role dropdown to load the permissions of a default Dag role or an existing custom role as a starting point.
In the Permissions table, check the boxes for the permissions you want the role to have. See Custom role permissions reference for a complete list of available permissions.
Click Create Role.
Your custom Dag role is now available to assign to users, Teams, and API tokens at the Dag level in any Deployment.
Custom Deployment roles and custom Dag roles both use the custom role creation flow in Organization Settings > Access Management > Roles, but they differ in scope:
A user can have both a Deployment role and one or more Dag roles. Permissions are additive, meaning a user with multiple roles has the combined permissions of all their roles.
Most Airflow operations require a specific combination of permissions to work. Assigning a resource-specific permission without the required base permission results in access being denied, even when the user appears to have the relevant permission.
Two base permission patterns apply across all resources:
dag.airflow.dag.get alongside the specific resource read permission. For example, to view Dag runs, a role needs both dag.airflow.dag.get and dag.airflow.dagRun.get.dag.airflow.dag.update — not dag.airflow.dag.get — alongside the specific resource write permission. For example, to trigger a Dag run, a role needs dag.airflow.dag.update and dag.airflow.dagRun.create.Some nested resources also require permissions for all parent resources. For example, viewing task logs requires dag.airflow.dag.get, dag.airflow.dagRun.get, dag.airflow.taskInstance.get, and dag.airflow.taskLog.get.
The following examples show minimum permission sets for common role types. These are verified against Airflow API behavior but cover a subset of operations. Not all Airflow endpoints are represented here.
View Dags, Dag runs, and task execution details without making changes.
Trigger, update, and delete Dag runs.
View and manage individual task instances.
Full control over a Dag, including deletion.
The Airflow access control documentation covers a broader set of permissions but isn’t consistently maintained and may not reflect actual enforcement behavior. Use it as a general reference and verify requirements in your Deployment.