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:

• Dag tags (recommended): Bind roles to one or more Dag tags. Any Dag with a matching tag is automatically included in the role binding. This is the recommended approach because new Dags that share the same tag are automatically covered without needing to update role assignments.
• Dag IDs: Bind roles to specific Dag IDs. Dag IDs are unique per Deployment. Use this approach when you need to grant access to a specific Dag that doesn’t share tags with other Dags.

Prerequisites

• An Astro Deployment running Astro Runtime 3.1-12 or later.
• The user being assigned a Dag role must be an Organization Member. If the user does not already have a Workspace role, Astro automatically grants them the Workspace Accessor role when you assign them a Dag role. See Workspace Accessor.
• Organization Owner permissions to create custom Dag roles.
• Workspace Owner or Deployment Admin permissions to assign Dag roles to users, Teams, and API tokens.

Default Dag roles

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.

Assign Dag roles to users

1. In the Astro UI, click Organization Settings > Access Management.
2. Click Users, then click the user you want to manage.
3. Click the Dags tab.
4. Click + Dag.
5. In the Add User to Dag slide-out, select a Deployment.
6. Under Target Dag by, select Dag Tag or Dag ID. Astronomer recommends using Dag tags so that the role automatically applies to any new Dags with the same tag.
7. Select the Dag tag or Dag ID you want to bind the role to.
8. Select a Dag Role and click Add to Dag.

Assign Dag roles to Teams

You can assign Dag roles to Teams so that all Team members share the same Dag-level permissions.

1. In the Astro UI, click Organization Settings > Access Management.
2. Click Teams, then click the Team you want to manage.
3. Click the Dags tab, then click + Dag.
4. In the slide-out, select a Deployment.
5. Under Target Dag by, select Dag Tag or Dag ID. Astronomer recommends using Dag tags so that the role automatically applies to any new Dags with the same tag.
6. Select the Dag tag or Dag ID you want to bind the role to.
7. Select a Dag Role and click Add to Dag.

Assign Dag roles to API tokens

You can assign Dag roles to Organization API tokens to give them fine-grained access to specific Dags within a Deployment. Only Organization-level tokens support Dag role assignments. Workspace and Deployment API tokens cannot be assigned Dag roles.

1. In the Astro UI, click Organization Settings > Access Management.
2. Click API Tokens, then click the Organization API token you want to manage.
3. Click the Dags tab, then click + Dag.
4. In the slide-out, select a Deployment.
5. Under Target Dag by, select Dag Tag or Dag ID. Astronomer recommends using Dag tags so that the role automatically applies to any new Dags with the same tag.
6. Select the Dag tag or Dag ID you want to bind the role to.
7. Select a Dag Role and click Add to Dag.

View and edit a user’s Dag access

Organization Owners can view and manage all of a user’s Dag role assignments from a centralized page.

1. In the Astro UI, click Organization Settings > Access Management.

2. Click Users, then click the user whose Dag access you want to view.

3. 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:

• Dag ID: The ID of the Dag the role is bound to.
• Dag Tag: The Dag tag the role is bound to.
• Deployment: The Deployment the binding belongs to.
• Dag Role: The Dag role assigned to the user.

To edit a user’s Dag role:

1. Open the More actions menu (…) next to the Dag entry you want to update and select Edit role.

2. In the Edit Dag Access slide-out, select a new Dag role. The Dag ID and Deployment fields are read-only.

3. Click Save changes.

To remove a user’s access to a Dag, open the More actions menu (…) and select Remove.

Create a custom Dag role

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.

1. In the Astro UI, click Organization Settings.

2. Go to Access Management, then click Roles.

3. Click Custom, then click + Add Role.

4. In the slide-out that appears, set the Scope dropdown to Dag.

5. Enter a Name and Description for the role.

6. (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.

7. 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.

8. 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 Dag roles vs. custom Deployment roles

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:

• Custom Deployment roles grant permissions across all Dags and resources in a Deployment. See Create and assign custom Deployment roles.
• Custom Dag roles grant permissions to specific Dags within a Deployment, bound by Dag tag or Dag ID.

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.

See also

• User permissions reference
• Create and assign custom Deployment roles
• Custom role permissions reference
• Configure Teams on Astro
• Create and manage Organization API tokens