Mapping identity provider groups to Airflow roles

How to map identity provider groups to Airflow roles

Your identity provider administrator owns the groups, and your Airflow operator owns the roles. The mapping is where those two responsibilities meet. In the FAB auth manager, AUTH_ROLES_MAPPING translates identity provider groups or roles into Airflow roles, and AUTH_ROLES_SYNC_AT_LOGIN re-checks that mapping every time a user signs in, so a removed group membership takes effect at the next login rather than lingering. Teams need this design once user counts grow, once DAGs are owned by specific teams, or once auditors ask who could trigger, edit or view a pipeline and why. Remember that the mapping only grants roles. What a user can actually do is decided by the auth manager's resource checks, such as is_authorized_dag, is_authorized_connection, is_authorized_pool and is_authorized_variable, so a broad role can still expose more than you intended if the checks behind it are broad.

Before you write any mapping, agree on the list of Airflow roles you need and the groups that will hold them, and keep that list in version control next to your configuration. Ask your identity provider team to confirm exactly which claim carries group membership, whether it is a group name, a group identifier or an application role, because a mismatch there produces users with no access at all. Decide what happens to users who belong to no mapped group. AUTH_USER_REGISTRATION controls whether unknown users are created at first login, and AUTH_ROLE_PUBLIC should not be used as a shortcut for access, since setting it to a role effectively deactivates authentication. Confirm these settings in a staging environment with test accounts from each group before production. Keep at least one break-glass administrator outside the mapped groups, and review the current FAB auth manager documentation for the exact settings your provider version supports.

Role mapping options and when each fits

This table compares the FAB configuration keys that control how identity provider groups become Airflow roles and how users are admitted at login. Read each row for the situation where the setting fits and the main risk it introduces. The main takeaway is that the mapping, sync and registration settings should be set together, and that AUTH_ROLE_PUBLIC should never be used as a shortcut around sign-in.

Setting	When it fits	Main risk
AUTH_ROLES_MAPPING	Your identity provider sends group or role names that you can map one-to-one to Airflow roles such as Admin, Op, User and Viewer.	Groups that are unmapped or renamed silently grant no access, and broad groups can grant more than intended.
AUTH_ROLES_SYNC_AT_LOGIN	You need role changes in the identity provider to take effect at the user's next sign-in, for example after offboarding or a team change.	Roles assigned manually inside Airflow are overwritten at each login, so local role edits disappear without warning.
AUTH_USER_REGISTRATION	New staff should get an Airflow account on first sign-in without an administrator creating it beforehand.	Any user who can authenticate with the provider gets an account, so the provider's own access boundary must be strict.
Default role for new users	You want first-time users to land in a low-privilege role until a group mapping assigns their real role.	If the default is set too high, every newly registered user gains those permissions before anyone reviews them.
AUTH_ROLE_PUBLIC	Almost never for a production deployment. It may only be considered for a short, isolated test where no data or DAGs are exposed.	Setting it to a role effectively deactivates authentication, so anonymous visitors receive that role's permissions.
SECURITY_MANAGER_CLASS	Your login or role logic needs rules that the configuration keys cannot express, such as custom claim handling, and you have engineers who will maintain it.	Custom security manager code becomes part of your authentication path and must be reviewed and upgraded with each Airflow change.

Designing DAG-level permissions around team groups

Role mapping only works if the roles behind it reach the right objects. Airflow 3 authorizes each request through resource checks, so the group design should follow the DAGs, connections, pools and variables that each team actually touches. The cards below cover the checks, the design choices they force, and what to confirm before you rely on a custom role.

Know the four resource checks

The auth manager decides access through resource checks: is_authorized_dag, is_authorized_connection, is_authorized_pool and is_authorized_variable. Each group you map ends up with permissions against these entities, so the role model is only as precise as the checks it can reach. Write down which check governs each thing a team does before you assign any group to a role.

DAG runs and tasks follow the DAG

DAG runs, tasks and task instances are covered by the is_authorized_dag access entities rather than by their own separate checks. In practice, a user who can see or act on a DAG can also reach its runs and task instances, so you cannot give a team access to task logs without also giving it access to the DAG. Confirm this behavior in your Airflow version before promising a team read-only visibility into one stage of a pipeline.

One group per owning team

Map one identity provider group to each team that owns a set of DAGs, and avoid shared groups that span unrelated pipelines. Ownership should match the team that is paged when a run fails, because that team needs to pause, clear and trigger its own work. Ask your identity team to confirm that group membership changes flow from the directory without manual edits in Airflow.

Separate operators from viewers

Keep a viewer role for people who need to see run history, logs and graphs, and a separate operator role for those who trigger, pause or clear runs. Viewers are common among analysts and auditors, and giving them operator rights by default is the most frequent over-permissioning mistake. Test each role with a real account from every group before go-live.

Restrict connections and variables

Connections and variables usually hold credentials and environment settings that many DAGs depend on. Limit is_authorized_connection and is_authorized_variable to a platform admin group, so that DAG authors use references rather than editing secrets. Pools need the same care, since one team's pool settings can starve another team's tasks of workers.

Confirm custom role reach

Before you build a custom role, list every access entity it grants and test each one against a non-admin account, because a role that looks narrow can still reach connections or variables. Ask the auth manager documentation and your own test results to confirm the exact permissions, and record the result as evidence for your access review. Re-run this check after each Airflow upgrade, since permission sets can change between releases.

Setting up group-to-role mapping step by step

This sequence takes a team from an Airflow 3 install with no login mapping to a tested setup where each identity provider group lands on the Airflow role it was designed for. Each step closes with a check, so mistakes surface before real users sign in.

Confirm the FAB auth manager is active
Install the FAB provider package and set the auth_manager option to the FAB auth manager class, because Airflow 3 uses the Simple auth manager by default and allows only one auth manager at a time. Confirm that your deployment reads this setting from the same configuration your workers and API server use. Check that the API server starts, the login page appears, and the Simple auth manager no longer issues logins. Confirm the exact class path and package version against the FAB provider documentation before you pin them in your image.
Agree group names and the role model
Work with the identity team to decide which directory or IdP groups will exist for Airflow, such as one group per duty rather than one per person, and which Airflow roles each group should receive. Write down which groups may view DAGs, trigger runs, edit connections, or administer users, and who approves changes to that list. The output is a short table that maps each group to one role and names the owner of that table. Do not start the configuration until the group names are final, since renaming them later means changing both the IdP and the mapping.
Define AUTH_ROLES_MAPPING
In the FAB configuration file, add an AUTH_ROLES_MAPPING dictionary whose keys are the group names or role claims sent by your identity provider and whose values are lists of Airflow role names. Keep the keys exactly as the provider emits them, including case, because a mismatch silently grants nothing. Check the mapping by reading it back against the table from the previous step. Done means every group in the table appears once and no group is mapped to a role it was not approved for.
Set the sync and registration flags
Set AUTH_ROLES_SYNC_AT_LOGIN so Airflow re-reads group membership on every login, which lets removals in the directory take effect at the next sign-in. Decide whether AUTH_USER_REGISTRATION should create accounts for unknown users at first login, and if so, set AUTH_USER_REGISTRATION_ROLE to a low-privilege default. Leave AUTH_ROLE_PUBLIC unset or set to a role with no data access, because pointing it at a privileged role effectively disables authentication. Verify the settings by reviewing the effective configuration on the API server, not only the file in your repository.
Add custom login logic only when required
Most teams need nothing beyond the mapping and flags. Write a class that extends FabAirflowSecurityManagerOverride and assign it to SECURITY_MANAGER_CLASS only if a requirement cannot be met by mapping alone, such as deriving roles from a claim that is not a group or blocking users who lack a domain attribute. Keep the class small, review it with the security owner, and record why each override exists. The check is a unit test or a login attempt for each branch the override adds.
Test with one account per role
Create or use one test account in each mapped group, plus one account in no group, and sign in to each with a fresh browser session. For every account, confirm the DAG list, the connection pages, the variable pages and the user administration pages show exactly what the role table predicts. Where a role should not see a DAG, open its URL directly and confirm the access is refused. Record the results in a sign-off sheet with the Airflow version and the mapping file hash.
Confirm DAG-level permissions and removals
Check that permissions on individual DAGs match your design by testing a DAG-scoped role against a restricted DAG and an unrestricted one. Remove a test account from its group in the directory, sign in again, and confirm the roles drop at that login because sync is active. Review the auth manager authorization methods that enforce these checks, so the team knows which resource and DAG access checks apply to runs, tasks and connections. The output is a documented list of permitted and refused actions per role.
Hand over the mapping and its change process
Store the mapping and flags in version control, require review for every change, and tie each change to an approved row in the group-to-role table. Add the break-glass administrator outside the mapping so a directory outage cannot lock everyone out, and record who holds it. Schedule a repeat of the test-per-role check after each Airflow upgrade or identity provider change, since both can alter how groups and roles arrive. The handover is complete when the operations team can repeat the tests from the runbook without help.

Mapping choices by identity provider setup

When the identity provider places group names or app roles in the token or user info response, the FAB auth manager can map them directly. You list each external group under AUTH_ROLES_MAPPING in webserver_config.py, pointing it at one or more Airflow roles, and enable AUTH_ROLES_SYNC_AT_LOGIN so the mapping is re-evaluated on every login. The provider-specific work sits in the sibling topics, which cover how each provider emits its claims and how to request them.

Group names must be stable: Decide whether the mapping uses display names or immutable identifiers, because display names can change and silently break access.
Claim shape varies: Some providers return a flat list, others nest groups in a custom attribute, so confirm the exact claim path before writing the mapping.
Pagination and size limits: Large group memberships can be truncated or replaced by an overage indicator, which hides groups from Airflow.
Sync on every login: Removing a user from a group only takes effect after their next login, so set session lifetimes with that gap in mind.

Before go-live, sign in with a test account from each group and confirm the roles shown in Airflow match the design.

Some identity providers do not include groups in the default token, or they send identifiers that mean nothing to a reviewer. In these cases the mapping needs an extra step: a custom claim configured at the provider, a call to a directory or API during login, or a custom security manager class assigned through SECURITY_MANAGER_CLASS that extends FabAirflowSecurityManagerOverride. This is more code and more to maintain, and it moves part of your authorization logic into Airflow's login path.

Custom claim configuration: Add the group membership as an attribute or claim at the provider, and document who owns that configuration.
Lookup failures: Decide what happens if the directory call times out. Denying access is safer than falling back to a default role.
Mapping logic in code: Keep the translation from identifiers to role names in version-controlled code with tests, not in ad hoc edits on the server.
Upgrade exposure: A custom security manager depends on FAB internals, so check it against each provider upgrade.
Auditability: Log which groups were received and which roles were granted, so access reviews can reconstruct decisions.

Ask the provider team which claims are available to your application and whether the lookup can be cached without weakening revocation.

Some identity providers, and some social or consumer login options, do not send group membership at all. Here the group mapping layer has nothing to act on, so access depends on a default role for new users and manual assignment afterward. AUTH_USER_REGISTRATION controls whether unknown users are created at first login, and AUTH_USER_REGISTRATION_ROLE sets the role they receive. Keep that default narrow, because every new user receives it without review.

Narrow default role: Give new users a read-only or no-privilege role, and treat anything broader as a decision that needs an owner.
Manual assignment process: Define who can promote users, how requests are made, and where the approval is recorded.
Domain restrictions: Limit sign-in to approved domains or tenants at the provider, since registration otherwise admits anyone who can authenticate.
Drift over time: Manually assigned roles do not follow HR changes, so schedule reviews of who holds each role.
Break-glass access: Keep at least one local administrator path that does not depend on the external provider.

Confirm with the provider whether groups can be enabled later, because moving to group-based mapping later is cheaper than retrofitting manual assignments.

Security risks in role mapping

Role mapping decides who can see and change pipelines, so a small configuration mistake can grant far more access than intended. The cards below pair each common failure mode with the control that prevents it and the evidence worth keeping.

Public role disables authentication

Setting AUTH_ROLE_PUBLIC to a role effectively deactivates authentication in the FAB auth manager, so anyone who can reach the webserver may act with that role's permissions. Keep this value unset or set to the least-privileged role you intend, and confirm it in every environment after each change. Store the reviewed configuration in version control and keep the diff as evidence of who approved the setting.

Overly broad default role

When AUTH_USER_REGISTRATION creates accounts at first login, every new user receives the default role, which becomes the floor for anyone with a valid identity. Set the default to a read-only role and grant elevated access only through group mappings. Check the default role in the configuration and record who approved any change to it.

Stale access when sync is off

If AUTH_ROLES_SYNC_AT_LOGIN is disabled, roles assigned at first login persist after a user changes teams or leaves the company. Enable sync at login so group membership is re-checked on every sign-in, and confirm that removed groups actually remove roles in a test account. Pair this with offboarding in the identity provider, since Airflow only sees changes when the user signs in again.

Admin rights mapped by name

Mapping a group by display name lets anyone who can create or rename a group in the identity provider influence Airflow access. Map admin roles to stable group identifiers or immutable claims where the provider supports them, and restrict who can create groups with admin-equivalent names. Review the mapping table on a fixed schedule and keep the export as audit evidence.

DAG-level permission drift

Auth manager checks such as is_authorized_dag govern DAG runs, tasks and task instances, so a broad role can reach pipelines owned by other teams. Define roles per team or per DAG scope where the auth manager supports it, and test that a user from one team cannot trigger another team's DAG. Keep the test results with the change record.

Break-glass admin outside the IdP

If the identity provider fails or a mapping error locks out every administrator, recovery depends on an account that does not rely on it. Keep one break-glass admin stored in a local or separately managed credential store, with access limited to emergencies and every use logged. Test the procedure during a planned exercise and retain the logs and the test record.

Operating and changing role mappings over time

Treat the group-to-role mapping as configuration that changes through review, not as a setting someone edits in place on a live server. Keep the AUTH_ROLES_MAPPING dictionary in the same version-controlled repository as the rest of your Airflow configuration, so every change has an author, a diff and a reviewer. Because AUTH_ROLES_SYNC_AT_LOGIN re-checks roles on every login, a mistaken edit takes effect the next time each user signs in, which means an error can remove an operator's access without any further action on your part. Before a change is merged, agree with the owner of the identity provider which groups it touches and confirm that group membership in the directory matches what the mapping expects, including any group that carries break-glass or administrator rights.

Test each change in a non-production Airflow before it reaches production. In Airflow 3 the webserver has been replaced by the API server started with airflow api-server, and the DAG processor runs as a separate component, so the login path you test is the API server and its auth manager configuration, not the old webserver setup you may remember from Airflow 2. Confirm which auth manager is active through the auth_manager option, because only one can run at a time. If you are still moving from Airflow 2, the upgrade guide's advice to reach the latest 2.x release first and to check DAG code with Ruff rules AIR301 and AIR302 applies to the environment you test in, so the login test should run on the same versions you plan to run in production. Use a test account for each role, and check both the sign-in result and the actions that role can take on DAGs, connections and variables. Confirm the exact auth manager and provider versions in your own environment before you rely on them.

Record who approved each change, who requested it, the test run that verified it and the date it was deployed. Keep this record alongside the configuration history so an auditor or incident responder can see why a user held a given role at a given time. Keep at least one break-glass administrator path documented and tested separately from the mapping, so that a bad mapping does not lock every operator out. Review the mapping on a regular schedule and after any directory reorganization, because group names that were renamed or removed in the identity provider fail silently when no user matches them. Ask your identity team to notify you before group changes, and treat that notice as a trigger for a new test run.

Limits to confirm in your environment

The role mapping design above depends on details that vary by build, identity provider and auth manager. The cards below list what to confirm in your environment before you rely on the mapping in production, and where the vendor documentation is the place to settle each point.

FAB provider version in your build

The FAB auth manager ships from the FAB provider package, not from the core Airflow release, so the provider version in your Airflow 3.3.2 build determines which AUTH_ROLES_MAPPING, AUTH_ROLES_SYNC_AT_LOGIN and AUTH_USER_REGISTRATION settings and security manager hooks you can use. Pin the provider version in your constraints file, then read the webserver authentication page for that release. Confirm the exact provider version against your image before writing any mapping.

Group claims in the token

Role mapping only works if your identity provider sends group or role values in the token format Airflow reads. Some providers omit groups by default, send group IDs instead of names, or cap the number of groups per token. Check what your provider emits for a test user in the ID token or user info response, and confirm that the claim name matches what your FAB OAuth configuration expects.

Access entity behavior for custom roles

Auth managers authorize through resource checks such as is_authorized_dag, is_authorized_connection, is_authorized_pool and is_authorized_variable, and DAG runs, tasks and task instances fall under the DAG access entity. A custom role that grants DAG access may not behave as you expect for connections, pools or variables. Test each access entity with a role that has only the permission you intend, and record the results as evidence.

Auth manager behavior match

Airflow allows one auth manager at a time, set by the auth_manager option, and the default is the Simple auth manager. Role names, permission checks and login flows differ between the FAB, Keycloak and AWS auth managers, so a mapping designed for one does not carry over. Confirm which auth manager your build uses and whether its documented behavior matches the mapping you designed.

Break-glass access and sync behavior

Syncing roles at every login means a group removal in the identity provider takes effect at the user's next sign-in, so confirm how quickly your provider revokes group membership and how long existing sessions remain valid. Keep a local administrator path that does not depend on the identity provider, and test that it still works after the mapping is in place. Confirm the recovery steps with your provider's documentation and your own change process.

Questions teams ask before mapping Airflow roles

What drives the cost of mapping identity provider groups to Airflow roles?

The cost follows the size of the role model and how much custom logic it needs. The main drivers are the number of groups to map, whether the identity provider sends groups in a clean claim or needs transformation, whether you need DAG-level permissions beyond the standard roles, and how much testing covers each login path. Each of these adds design, configuration and verification work. Ask any partner for a quote that lists each group, each custom method or security manager change, and each test case, since those line items show what you are paying for. A one-time build is the bulk of the cost. Ongoing cost comes from reviewing the mapping when groups change and retesting after upgrades.

How long does it take to scope a role mapping project?

Scoping depends on how quickly your identity team can produce an accurate group inventory and how many Airflow environments need the same design. A small mapping with a few groups and one environment scopes faster than a model with many teams, per-DAG rules and several environments. Scoping usually settles three things: the role matrix, the identity provider claims Airflow will read, and the test cases that prove each role gets the right access. No duration is fixed here. Ask for a written scope with a timeline that names the dependencies on your team, such as directory access and review cycles.

What must our team provide before the work starts?

Three inputs unblock most projects. First, administrator access to the identity provider, or a named contact who can read group membership, group claim settings and any token mapping rules. Second, a complete group inventory that lists each group, its members in broad terms, and who owns it. Third, a role matrix that states which group should receive Admin, User, Op, Viewer or any custom role, and which DAGs, connections or pools each role can reach. Also confirm which Airflow version and auth manager you run, because the enforcement methods differ. Gaps in these inputs usually show up as rework during testing.

Can an internal team map Airflow roles without a partner?

Yes, a capable internal team can do the work if it has someone who understands both the identity provider and the Airflow auth manager. The FAB auth manager uses AUTH_ROLES_MAPPING and AUTH_ROLES_SYNC_AT_LOGIN for basic mapping, so a small group model can be configured directly. The harder parts are custom login logic, which means a class extending FabAirflowSecurityManagerOverride, and DAG-level permissions enforced through resource checks such as is_authorized_dag. Teams that have not written these before often benefit from an outside review of the design and tests. Decide early which parts your staff will own after handover.

How does an Airflow upgrade change our role mapping?

An upgrade can change how roles are checked, so the mapping needs retesting after every version change. Airflow 3 uses the Simple auth manager by default and allows only one auth manager at a time, set by the auth_manager option, so a move to a different auth manager is a configuration change with its own test plan. The FAB auth manager comes from the FAB provider, so provider version changes can affect login behavior. Check the upgrade notes for your target release, confirm that group claim names still arrive unchanged, and rerun the login and DAG access tests for every role. Airflow 2 reached end of life on April 22, 2026, so an older deployment also needs a migration plan before role work can be treated as current.

What testing should cover role mapping before we go live?

Testing should prove that each group gets exactly the access in the role matrix, and that users outside those groups get none. Cover first login for a new user, a returning user whose group membership changed, and a user removed from every group. With AUTH_ROLES_SYNC_AT_LOGIN enabled, check that roles are removed as well as added. For DAG-level permissions, test DAG runs, tasks and task instances, since the auth manager covers them through the is_authorized_dag access entities. Also test the public role setting: AUTH_ROLE_PUBLIC set to a role effectively deactivates authentication, so confirm it is not enabled. Keep the test results as change evidence.

Which identity provider claim format causes the most mapping problems?

Mapping problems usually come from group names that differ between the identity provider and what Airflow expects. Common issues include groups sent as opaque IDs instead of names, nested groups that do not flatten into the token, groups truncated or omitted when a user belongs to many of them, and claim names that change between provider configurations. Confirm the exact claim your provider sends for a test user before writing the mapping. Then compare the value in a real token with the value in AUTH_ROLES_MAPPING. Partners and internal teams both tend to lose time here, so treat claim verification as a first task rather than a final check.

Does role mapping help with audit evidence for access reviews?

It can, if the mapping is documented and the changes are traceable. Auditors typically want to see who can access which DAGs, how that access was approved, and how removals happen when people change roles. A written role matrix, the configuration that enforces it, and test results from each change give that evidence a clear starting point. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors and certification bodies issue any audit report or certification. Ask your assessor which artifacts they expect before you finalize the design.

How DeployOpen scopes role mapping for Airflow

DeployOpen treats Airflow role mapping as a written design decision before any configuration is changed. We scope which identity provider groups map to which Airflow roles, how those mappings sync at login, and which DAG-level permissions each team receives, then build and test the result in your own infrastructure.

How we scope

Inventory the identity provider groups that need Airflow access and agree which auth manager your Airflow 3 deployment will use.
Document the role model, default role for new users, and whether AUTH_ROLES_SYNC_AT_LOGIN re-checks roles on every login.
Set out in writing which DAG, connection, pool and variable permissions each team needs, so the fixed scope is explicit before work starts.

How we build

Configure the group-to-role mapping in your chosen auth manager and keep the mapping under version control alongside deployment code.
Test sign-in with sample accounts for each role, including denied paths for users outside the mapped groups.
Verify DAG-level access checks for DAG runs, task instances and connections, since those are enforced by the auth manager's resource checks.

How we hand over

Provide written documentation of each group, role, permission and login setting, with the reasoning behind each decision.
Walk your identity and platform teams through the procedure for adding a group, changing a role, or removing a user's access.
Document a break-glass administrator path so Airflow stays reachable if the identity provider is unavailable.

How we support

Ongoing support, upgrades and continuous testing are available as retainers, including review of role mappings when Airflow versions change.
Re-verify role mappings after identity provider group changes or Airflow upgrades, so access stays aligned with your access policy.
Confirm with your identity provider and Airflow release notes which claim formats and auth manager methods your version supports before each change.