How Apache Airflow SSO with Microsoft Entra ID works
The supported route for signing in to self-hosted Airflow 3 with Microsoft Entra ID is the FAB auth manager with the azure OAuth provider, configured in webserver_config.py. Airflow 3 does not use this route by default, because it ships with the Simple auth manager and allows only one auth manager at a time, set by the auth_manager option. Your team must install the FAB provider, select FabAuthManager, and then point the OAuth settings at your Entra ID tenant. Teams that have not yet confirmed this path against their Airflow 3 version should check the FAB provider documentation before planning any login work.
In this design Entra ID is the identity provider, and Airflow is the relying party. Entra ID authenticates the user and issues tokens, and Airflow trusts those tokens to decide who is signed in. Roles come from claims that Entra ID sends with the login, either group claims or app role claims. FAB reads those claims and maps them to the Airflow roles Admin, Op and Viewer through AUTH_ROLES_MAPPING. AUTH_ROLES_SYNC_AT_LOGIN re-checks roles on every login, so a change in Entra ID takes effect at the next sign-in, and AUTH_USER_REGISTRATION controls whether unknown users are created at first login. Decide early which claim type your tenant can emit reliably, because that choice shapes the app registration and the mapping.
Scope this work in writing before it starts. DeployOpen does not publish prices, and a quote follows from the agreed scope, which should name the tenant and app registration owner, the Airflow versions and deployment method in use, the role model, and who tests break-glass access. Ask any partner to confirm the exact provider settings against your Airflow and FAB provider versions, and ask your own identity team to confirm which claims your tenant can emit before the build begins.
What you need before configuring Entra ID login
Entra ID login depends on a working Airflow 3 deployment, a supported metadata database and a few access rights that sit outside Airflow. Confirm these items first, because a missing redirect path, an untrusted certificate or a read-only tenant role stops the setup at the point where it is hardest to diagnose.
Airflow 3 on a supported version
Run Airflow 3.3.2, the current patch release in the version table, or a later patch in the 3.x line. Airflow 2 reached end of life on April 22, 2026, so it receives no fixes and should not be the base for a new SSO build. If you are still on 2.x, the upgrade work comes before any identity configuration. Confirm the exact patch version with your team before you copy any settings from this page.
Python and runtime prerequisites
Airflow 3.3.2 supports Python 3.10 to 3.14, so pin the interpreter in the image or virtual environment you build from. Install the FAB provider from the same constraints file as Airflow so that the auth manager and its dependencies match the core version. Mixing provider and core versions is a common cause of login failures that look like configuration errors.
Production metadata database
Use PostgreSQL 14 to 18 or MySQL (8.0, 8.4 or an Innovation release) for the metadata database. SQLite is for testing only and risks data loss, and MariaDB is not a supported metadata database. Entra ID sign-in does not work around a weak database choice, and user and role records written at first login live in this database.
FAB provider and FabAuthManager
Airflow 3 defaults to the Simple auth manager and allows only one auth manager at a time, set by the auth_manager option. Entra ID login through the azure OAuth provider requires the FAB provider and FabAuthManager, so decide this before you write webserver_config.py. Confirm that your team accepts FAB as the auth manager for this environment.
Entra tenant and app registration rights
Someone must be able to register applications in the Microsoft Entra tenant, create a client secret or certificate, and assign groups or app roles to users. Confirm whether your tenant restricts app registration to administrators and who approves new enterprise applications. Without these rights the redirect URL and client credentials cannot be created, and the rest of the build stops.
Public HTTPS hostname and TLS trust
Entra ID redirects users back to the Airflow API server on a public HTTPS hostname, so the name and certificate must be reachable from the internet and match the redirect URL you register. The Airflow host must also trust the certificate chain of the identity endpoints it calls. Check the chain from the API server itself, because a corporate proxy or private CA that works on a laptop often fails inside the container.
Configuring the FAB azure provider step by step
This sequence takes an Airflow 3 install from the default Simple auth manager to Microsoft Entra ID sign-in through the FAB provider, with group claims mapped to Admin, Op and Viewer. Each step ends with a check you can run before moving on.
Install the FAB provider and switch the auth manager
The platform engineer installs the FAB provider package into the same Python environment as Airflow 3, pinned to a version that matches the Airflow release in use. Then they set the auth_manager option in airflow.cfg to the FabAuthManager class, because Airflow 3 allows only one auth manager at a time. Verification: the API server starts without import errors, and the login page reflects the FAB auth manager rather than the Simple auth manager.
Register the Entra application and record credentials
An identity administrator creates an app registration in Microsoft Entra ID for the Airflow web UI and records the tenant ID, the application (client) ID and a client secret. Confirm with your Entra administrator whether the secret lifetime and the secret storage approach meet your policy, since both affect rotation work later. Verification: the three values are stored in your secrets store, not in a shared document, and the application appears in the tenant with the expected name.
Add redirect URLs under the auth path
In the app registration, the administrator adds a web redirect URI that points to the Airflow host with the /auth path in the callback route, using the exact scheme and host your users will open. Airflow 3 moved its auth routes under /auth, so a callback URL copied from a Airflow 2 setup will fail. Verification: the redirect URI list matches the callback that the FAB provider generates, character for character, including the trailing path segments.
Emit group or app role claims in the token
The identity administrator configures the token to include group claims or app roles, choosing one approach and documenting which one was picked. Group object IDs are stable but opaque, so role mapping will reference those IDs; app roles give readable names but require assignment to users or groups. Verification: sign in once in a test browser, decode the ID token, and confirm the expected claim lists the groups or roles for the test account.
Write the OAuth provider block and role mapping
The platform engineer adds the azure OAuth provider entry to webserver_config.py, reading the tenant, client ID and secret from environment variables or the secrets backend rather than hard-coding them. They then define AUTH_ROLES_MAPPING so each Entra group or app role maps to Admin, Op or Viewer, and keep a single documented owner for that mapping. Verification: the configuration file loads without errors, and a test user in each mapped group reaches a login page with the role they expect.
Enable role sync at login
The engineer sets AUTH_ROLES_SYNC_AT_LOGIN so Airflow re-checks the Entra claims on every login, which means a user removed from an Entra group loses the matching Airflow role at the next sign-in. Confirm with your security team whether that behavior matches your access review cycle. Verification: move a test user out of a mapped group, sign in again, and confirm the Airflow role changed to the expected value.
Decide user registration and test the callback
The engineer decides whether AUTH_USER_REGISTRATION should create accounts for unknown users at first login, or whether only pre-provisioned users may enter. Pre-provisioning is the more restrictive choice and should be agreed with the access owner before go-live. Verification: run a full sign-in from a clean browser session, confirm the callback completes, and confirm that a user outside the mapped groups is handled as the chosen registration policy requires.
Why callback URLs under /auth break first after an upgrade
Airflow 3 moves its auth routes under /auth, so an OAuth redirect URI registered for an older path no longer matches what Airflow sends to Entra ID. Depending on how the login flow fails, users may land on a generic error page, get bounced back to the login screen, or hit a redirect error in the Entra ID sign-in log. Because the failure often looks like a general sign-in problem, teams lose time checking group claims or client secrets before they look at the redirect URI. Before you cut over, open the app registration in Entra ID and confirm that every redirect URI ends in the path Airflow 3 actually calls, not the path your Airflow 2 deployment used. The Airflow 3 upgrade guide describes the route change, and the callback path your FAB provider expects should be checked against your installed provider version.
In the browser flow, the user opens the Airflow UI, which redirects to the Entra ID authorize endpoint with the client ID, requested scopes and the registered redirect URI. After the user signs in, Entra ID redirects the browser back to the Airflow callback URL with an authorization code. Airflow then calls Entra ID's token endpoint from the server side, using the client secret, and receives an ID token. Airflow validates the ID token on the server, checking the signature, issuer and audience, before it reads the user's identity and any group or app role claims to assign roles. The token never needs to reach the browser for this to work, so a misconfigured redirect shows up as a failed exchange on the Airflow host, and your Airflow logs are usually the fastest place to confirm which step failed.
During testing, register both the local hostname you use for development, such as a localhost address, and the production hostname that users will see, and keep them as separate entries in the same app registration. This lets you verify the full flow before cutover without editing the registration on the day of the change. Remove the local entries once cutover is complete, so the registration only accepts URLs you operate. Ask your identity team to confirm whether your tenant applies any restrictions on http redirect URIs, since that determines whether local testing needs a different hostname setup. Keep the old Airflow 2 entries until the rollback window closes, then remove them.
Mapping Entra groups and app roles to Admin, Op and Viewer
This table shows how each Entra source claim maps to an Airflow role in AUTH_ROLES_MAPPING and what that role can do. Read each row as a pairing: the value Entra sends in the token on the left, the Airflow role it should resolve to in the middle, and the access the role grants on the right. Group overage can stop group claims from arriving at all, so confirm in your own tenant which claim your token actually carries before you write the mapping.
| Source claim and value | Airflow role | Access granted |
|---|---|---|
| groups: object ID of the Airflow Admins group | Admin | Full access to all DAGs, connections, variables and user management |
| groups: object ID of the Airflow Operators group | Op | Trigger, pause and clear DAG runs and task instances, with no user or security administration |
| groups: object ID of the Airflow Viewers group | Viewer | Read-only access to DAGs, runs, logs and task status |
| roles: app role value Airflow.Admin on the Enterprise Application | Admin | Same as the Admin group, used when group claims are unavailable or overage applies |
| roles: app role value Airflow.Op on the Enterprise Application | Op | Same as the Operator group, assigned directly to users or groups in Entra |
| roles: app role value Airflow.Viewer on the Enterprise Application | Viewer | Same as the Viewer group, the least privileged mapping to start from |
| No matching group or app role in the token | Default role, or no access if registration is off | Depends on AUTH_USER_REGISTRATION and the default role you set; confirm before go-live |
| Claim name differs in your tenant or token configuration | Not mapped until corrected | Check the emitted token claims in your tenant and align the mapping keys before testing with users |
Hardening the Entra ID login for production
The FAB OAuth login works in a test tenant long before it is safe for production. The cards below cover the controls this integration adds on top of Airflow itself: how the client secret is handled, who in Entra can sign in, whether Airflow creates accounts on its own, how you keep a way in when the identity provider is down, and how least privilege is applied to Admin.
Client secret storage and rotation
The Entra app registration issues a client secret that the FAB OAuth configuration in webserver_config.py uses to exchange authorization codes. Do not hard-code it in the file that lives in source control. Load it from your secrets store or a container secret at startup, restrict read access to the scheduler and API server hosts, and set an expiry in Entra that matches your rotation calendar. Ask your team who owns the rotation runbook, because an expired secret locks every user out at once. Confirm the exact rotation steps against the FAB provider documentation for your version.
Assignment required in Entra
By default, any user in your tenant who can reach the Airflow login may be able to authenticate. Turn on the Entra setting that requires user assignment to the enterprise application, then assign only the groups or users who should reach Airflow. This control sits in Entra, so it holds even if the Airflow role mapping has a gap. Review assignments on the same schedule as your access reviews, and confirm with your Entra administrators whether guest accounts can be assigned.
Blocking self-provisioning with registration settings
AUTH_USER_REGISTRATION lets Airflow create a user record the first time someone signs in. Keep it disabled unless you have a defined default role and a reason to create accounts on first login. If it is enabled, new users receive the default role you set, so a broad default turns every assigned Entra user into a DAG editor. Pair the setting with AUTH_ROLES_SYNC_AT_LOGIN so that roles follow Entra group membership on each login rather than staying at whatever was first assigned.
Break-glass local admin
If Entra, the network path to it, or the OAuth callback fails, nobody can sign in through the browser. Plan a separate local administrator account in the FAB auth manager, with a long generated password held in your sealed-credential process and no daily use. Test the break-glass login after each configuration change, and record each use in your audit trail. Confirm with your identity team that the account cannot be disabled by the same Entra change that causes an outage.
TLS on the API server
The OAuth redirect to /auth returns a token and session to the browser, so the API server must be served over HTTPS with a certificate your organization trusts. The redirect URI registered in Entra must match the public scheme and hostname exactly, including the /auth path. Confirm that the reverse proxy or load balancer passes the original host and scheme through, and that cookies are marked secure. Ask your platform team who renews the certificate and how renewal is tested.
Least-privilege mapping for Admin
Map only a small, named Entra group to the Admin role, and keep Admin away from the groups used for day-to-day DAG work. Use AUTH_ROLES_MAPPING to send operators to Op and analysts to Viewer, and check that every group value in the mapping matches the claim your tenant actually sends. Review Admin membership quarterly, and document who approves additions. Confirm with your Airflow owners which permissions Admin grants in your version before you assign it to anyone.
Why Entra ID sign-in fails and how to fix it
This table lists the failures teams most often hit when wiring Entra ID into Airflow 3 through the FAB provider, with the likely cause and the fix for each. Read it when a login breaks, a user cannot reach a page, or a role change does not appear in Airflow, and check the cause column against your own tenant and configuration before changing anything.
| Symptom | Likely cause | Fix |
|---|---|---|
| Redirect URI mismatch after login | The redirect URI in the Entra app registration still uses the pre-Airflow 3 callback path. Airflow 3 moved auth routes under /auth, so the old callback no longer matches. | Update the redirect URI in the app registration to the /auth callback for your Airflow base URL, then confirm the exact value matches the one the FAB azure provider sends. |
| AADSTS errors at sign-in | The tenant ID in the OAuth provider settings does not match the tenant that owns the app registration, or the client secret has expired or was copied incorrectly. | Check the tenant ID and client ID against the app registration overview, then create a new client secret, store it in your secrets backend and restart the API server. |
| User signs in but has no access | The user's Entra group or app role does not map to Admin, Op or Viewer in AUTH_ROLES_MAPPING, and no default role applies to unknown users. | Map each group or app role explicitly, decide whether AUTH_USER_REGISTRATION is enabled, and confirm the default role for new users is the one you intend. |
| Expected groups are missing from the token | Entra ID returns a group overage indicator instead of the full group list when a user belongs to many groups, so the claim Airflow reads is empty or incomplete. | Switch to app roles assigned to users or groups for Airflow, or configure the group claim option in the token configuration, then sign out and back in to get a fresh token. |
| Tokens rejected intermittently | Clock skew between the Airflow host and Entra ID makes token timestamps appear not yet valid or already expired. | Synchronize the Airflow hosts with a trusted time source such as NTP, and check that container and VM clocks are not drifting. |
| Role changes in Entra ID do not take effect | AUTH_ROLES_SYNC_AT_LOGIN is off, so Airflow keeps the roles it stored at first login and does not re-read groups on later logins. | Set AUTH_ROLES_SYNC_AT_LOGIN to enabled in webserver_config.py, then have the user sign out and sign in again to confirm the new role is applied. |
Questions buyers ask before configuring Entra ID login
How much effort does Entra ID login for Airflow take?
The effort depends on how much of the setup is new work. A single app registration, one redirect URL set and a short list of role groups is a small job. Effort grows with tenant complexity, such as multiple Entra tenants, guest users, conditional access policies or group claims that need custom handling. It also grows with the number of role groups you map to Airflow roles, and with the number of environments, since each one needs its own app registration, redirect URLs and secrets. Ask any partner to base the quote on a written list of these factors rather than a general estimate.
Can our team configure Entra ID login alone using the FAB documentation?
Often yes, if your team already runs Airflow 3 with the FAB auth manager installed and has someone comfortable with OAuth and Entra app registrations. The FAB webserver authentication documentation covers the OAuth provider settings, AUTH_ROLES_MAPPING, AUTH_ROLES_SYNC_AT_LOGIN and AUTH_USER_REGISTRATION. The harder parts are usually outside Airflow: choosing whether roles come from group or app role claims, testing with real user accounts, and keeping a break-glass admin working if the identity provider is unavailable. Teams without those skills in-house often choose a fixed-scope engagement for that part.
What do we need from the Entra admins and the Airflow admins?
The Entra side needs someone who can register an application, set redirect URLs, create or assign client secrets or certificates, and configure the token claims that carry groups or app roles. The Airflow side needs someone who can edit the webserver configuration, manage the FAB provider package and deploy changes to each environment. Both teams should agree on the role names, who owns each Entra group and how new users are approved. Plan access for at least one person on each side during testing, because redirect and claim problems usually show up only in the browser.
How long does testing take, and what changes the duration?
Testing duration depends on scope. A single environment with a few role groups needs a short round of sign-in tests across each role, plus checks of logout, session expiry and access for users with no mapped group. Adding staging and production, guest accounts, multiple tenants or DAG-level permissions adds test cases. Ask for a test plan that lists each role, each environment and each failure case, and ask how the partner will record results. No duration should be accepted without that list.
What does a fixed-scope quote for this work cover?
A fixed-scope quote follows from a written scope that is agreed before work starts. For this topic, it should name the Entra tenants and applications in scope, the Airflow environments, the role groups and their mapping to Admin, Op and Viewer, the redirect URL and callback changes, the testing plan and the handover documentation. Deliverables should include the configuration in your environment and a record of tests. Ask what is excluded, such as identity governance changes in Entra, changes to other providers or ongoing support after handover.
Does the Entra ID setup change after an Airflow upgrade?
It can. Airflow 3 moved authentication routes under /auth, so OAuth callback URLs in Entra must match the new paths. If you are moving from an Airflow 2 deployment that used the older webserver routes, the redirect URLs and the FAB provider configuration need review during the upgrade. Confirm the exact callback paths and the FAB provider version for the Airflow release you run, and retest sign-in after every upgrade and after any change to the auth manager configuration.
Which Airflow auth manager should we use if we are unsure about FAB?
Airflow 3 uses the Simple auth manager by default, and only one auth manager can be active at a time, set by the auth_manager option. Using Entra ID login with the OAuth provider requires the FAB auth manager from the FAB provider. If your organization is not ready for FAB, confirm which alternatives are supported for your version before committing to a design, and document the trade-off with your security team. Changing auth managers later is a deployment change, so the decision should be recorded early.
What to confirm with your Entra admins and Airflow owners
Settle the identity decisions before anyone opens the Entra admin center. First, decide the tenant and app registration model: whether Airflow gets its own app registration in the tenant that owns your workforce identities, or shares one with another internal tool. Confirm who in the Entra team owns that registration, who can change its redirect URIs, and whether your security team wants the registration reviewed as part of its normal access review cycle. Second, decide whether group claims or app roles carry role data into Airflow. Groups are simpler to start with but can be large for some users, and app roles require the Entra admins to define and assign them. Either way, the Airflow owners must know which identifiers arrive in the token, because the role mapping in webserver_config.py depends on them.
Next, agree on who owns the client secret. The secret is a credential that Airflow reads from its configuration, so the Entra admins and the Airflow owners need to agree on where it is stored, how it is rotated, and who is notified when it expires. Your secrets management tooling should hold it, not a file in a DAG repository. Then set the default role policy for new users. Decide whether AUTH_USER_REGISTRATION is enabled, and if it is, which role a first-time sign-in receives. Many teams prefer Viewer as the default and manual promotion for anyone who needs to trigger or edit DAGs.
Finally, list every hostname and environment that needs a callback URL. Development, staging and production usually use different Airflow base URLs, and each one needs its own redirect entry under the /auth path that Airflow 3 uses. Confirm these hostnames with your network team before the build, since a mismatch will block sign-in and is easy to miss. Also confirm the exact option names with the current FAB provider documentation, such as the FAB webserver authentication guide, and check them against the provider version you install, because option names and provider behavior can change between releases.
How DeployOpen scopes and delivers Entra ID login for Airflow
DeployOpen plans Apache Airflow SSO with Microsoft Entra ID as a defined piece of work inside infrastructure you control. The engagement covers the Airflow 3 auth manager choice, the Entra ID app registration, the FAB azure provider configuration, role mapping and the verification steps that show who gets which role before users depend on it.
How we scope
- Confirm whether the target is Airflow 3 with the FAB auth manager or another auth manager before any configuration is written
- Agree in writing which Entra ID tenant, app registration, group or app role claims and Airflow roles are in scope
- Record the break-glass admin path, the redirect URLs under /auth and the environments covered in the fixed-scope document
How we build
- Configure the Entra ID app registration, redirect URIs and API permissions alongside the FAB provider settings in webserver_config.py
- Map Entra ID groups or app roles to Admin, Op and Viewer, and test each mapping with accounts that represent every role
- Test sign-in, role sync at login and denial for users outside the mapped groups in a staging environment first
How we hand over
- Document the app registration settings, the redirect URL list, the claim sources and the role mapping table for your team
- Provide a runbook for rotating the client secret, adding a group to a role and recovering access if the identity provider is down
- Walk your identity and platform engineers through the verification results and the open items agreed in scope
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover
- Revalidate the login flow when the Airflow version, the FAB provider or the Entra ID tenant configuration changes
- Ask any provider to confirm which settings, claims and tenant options apply to your Entra ID setup before you rely on them
