How Apache Airflow SSO with Okta works through FAB
A security or platform team that needs Airflow logins governed by Okta groups should know the mechanism before writing any configuration. In Airflow 3, Okta sign-in runs through the FAB auth manager using its OAuth support, with the okta provider configured in webserver_config.py. Okta groups are then mapped to Airflow roles, so access follows the group memberships your identity team already maintains. FAB supports several OAuth providers, including Okta, and the auth manager itself is chosen with the auth_manager option. Only one auth manager can be active at a time, so the Simple auth manager default must be replaced rather than run alongside FAB.
The practical consequence is that Okta does not replace Airflow's own authorization layer. Okta proves who the user is and, if the app is configured to send them, which groups the user belongs to. FAB then decides what that user can do inside Airflow. Your team needs to confirm three things with Okta administrators before building: that the Okta application can emit a groups claim in the ID token or user info response, that the group names are stable enough to use as mapping keys, and that the same users will be the ones who need the Admin, Op, User or Viewer roles. Confirm the exact FAB and Okta behavior against the provider documentation for your installed versions, since claim names and provider settings are version-dependent.
Two settings decide how far this integration reaches. AUTH_ROLES_SYNC_AT_LOGIN determines whether role assignments are re-evaluated every time a user signs in, so a user removed from an Okta group loses the matching Airflow role at the next login. AUTH_USER_REGISTRATION determines whether a user with no existing Airflow account is created on first login and with which default role. Leaving registration open with a permissive default role is a common source of unintended access, so decide both settings before the first pilot login. Keep a local break-glass admin path documented for the case where Okta is unavailable. Because FAB's own documentation covers the webserver authentication options in detail, use it as the reference for each key while you plan the build. FAB webserver authentication
What you need before configuring Okta login
Okta login for Airflow depends on four things lining up before any configuration is written: a supported Airflow and FAB provider version, a production metadata database, an Okta org with the right admin rights, and a reachable HTTPS callback URL. A break-glass admin plan sits alongside them so that a misconfigured login cannot lock every operator out.
Airflow and FAB provider versions
Confirm the Airflow 3 patch release you plan to run and the matching apache-airflow-providers-fab version against the version life cycle and prerequisites pages before you start. Airflow 3 uses the Simple auth manager by default, so the FAB auth manager must be installed from the FAB provider and selected through the auth_manager option. Record both versions in your change request, since the OAuth settings you write depend on them.
PostgreSQL or MySQL metadata database
Okta sign-in is only as durable as the metadata database behind the API server. SQLite is for testing only, so plan a PostgreSQL or MySQL instance with backups before go-live. Confirm the engine version against the prerequisites page, because MariaDB is not supported as a metadata database and the supported PostgreSQL and MySQL releases differ between Airflow versions.
Okta org admin rights
Someone must be able to create OIDC web applications and assign groups in the Okta org. Confirm that your admin account can do both in production, and that group membership is maintained by a team that will still exist after go-live. Decide whether group claims will carry full group names or a filtered prefix, because role mapping in Airflow depends on the exact values Okta sends.
HTTPS and the callback URL
The FAB OAuth flow redirects users back to Airflow, so the API server must be served over HTTPS under a hostname that Okta can reach from the user browser. Confirm the public URL, the TLS certificate chain, and the redirect path that FAB uses under /auth. Any mismatch between the URL registered in Okta and the URL Airflow presents will fail at sign-in, so agree the exact string before you create the app.
Break-glass local admin plan
Keep a local admin account that does not depend on Okta, so an operator can still sign in if the identity provider is down or a role mapping is wrong. Decide how its credentials are stored, who may use it, and how each use is logged and reviewed. Test that the account works in the staging environment before you enable Okta login in production.
Configuring the Okta app and Airflow in sequence
This sequence takes you from an empty Okta tenant to an Airflow login that maps Okta groups to Airflow roles, creates users on first sign-in and keeps roles current at every login. Each step closes with a check, so a failure is caught before the next layer depends on it.
Create the OIDC web application in Okta
An Okta administrator creates a new app integration of the OIDC type with the web application application type, then records the client ID and client secret in your secrets store. Set the sign-in redirect URI to the FAB OAuth callback under your Airflow base URL, which the FAB webserver authentication documentation gives as the callback path for the okta provider. Confirm the redirect URI in Okta matches your Airflow URL exactly, including scheme, host and trailing path, because Okta rejects mismatched callbacks at sign-in.
Add a groups claim to the ID token
In the Okta application's sign-on settings, add a groups claim to the ID token that filters groups by a name pattern or an explicit group list, so only the Airflow-relevant groups are sent. Assign the Airflow user groups to the application so members can sign in. Verify the claim by signing in with a test account and inspecting the returned ID token or the userinfo response, confirming the groups array contains the expected group names before you map them in Airflow.
Set the FAB auth manager in Airflow configuration
On the Airflow host or in your Helm values, set the auth_manager option in the [core] section of airflow.cfg, or the equivalent environment variable, to the FAB auth manager class. Airflow 3 allows only one auth manager at a time, so this replaces the default Simple auth manager. Install the FAB provider package in the same image or environment as the API server and scheduler. Confirm the setting by running airflow config get-value and checking that the reported auth manager is the FAB class.
Write the Okta provider block in webserver_config.py
Create or edit webserver_config.py and set AUTH_TYPE to the OAuth type, then add an OAUTH_PROVIDERS entry named okta that holds the client ID, client secret and the Okta server metadata URL for your authorization server, which is the well-known OpenID configuration endpoint. Read the client secret from an environment variable or secrets backend rather than writing it into the file. Verify the configuration loads by starting the API server and confirming the Okta button appears on the login page without configuration errors in the logs.
Enable registration and role mapping
Set AUTH_USER_REGISTRATION to True so first-time Okta users get an Airflow account, and set AUTH_ROLES_SYNC_AT_LOGIN to True so roles are recomputed on every sign-in. Define AUTH_ROLES_MAPPING as a dictionary that maps each Okta group name to one or more Airflow roles such as Admin, Op, User, Viewer or Public, and set AUTH_USER_REGISTRATION_ROLE to a low-privilege default. Confirm your mapping covers every group you assigned in Okta, since a user matching no group receives only the default role.
Keep a break-glass admin account
Before you restrict the login page, keep one local administrator account that does not depend on Okta, either through database password authentication in the same FAB configuration or through a documented emergency procedure. Test that this account signs in and that Okta sign-in still works in the same browser session. Without this check, an Okta outage or a mapping error can lock every operator out of the UI, so confirm the fallback before you rely on SSO alone.
Test login with one user in each group
Sign in with a test user from each Okta group that appears in AUTH_ROLES_MAPPING, and check that the Airflow user menu shows the role you expect for each. Then add a user with no mapped group and confirm they receive only the default role. Remove a test user from a group, sign in again, and confirm the role downgrades because of AUTH_ROLES_SYNC_AT_LOGIN. The sequence is complete when every group and the no-group case behave as designed.
Mapping Okta groups to Airflow roles
This table lists the Okta claims, Airflow settings and role decisions that shape sign-in for each person who uses the Airflow UI. Read each row as a question to settle in the design: what Okta sends, what Airflow does with it at first login and at every later login, and what you must confirm in your own Okta authorization server before go-live.
| Design point | What to set or decide | What to confirm or watch for |
|---|---|---|
| Okta group claim | Map the Okta group claim to AUTH_ROLES_MAPPING so each Okta group name points to one or more Airflow roles such as Admin, Op, User or Viewer. | Confirm the exact claim name and whether it carries group names or IDs in your Okta authorization server, and that the group is included in the ID token or userinfo response. |
| User attributes | Map username, email, first name and last name from the Okta claims so Airflow can create a complete user record. | Confirm which claims Okta emits for each attribute, and test with a non-admin account because missing email or name claims can block registration. |
| Default role for new users | Set the role assigned to users who register at first login and do not match any mapping entry. | Keep this role minimal, such as Viewer or User, so an unmapped Okta account cannot gain write or admin access. |
| Registration of new users | Enable AUTH_USER_REGISTRATION so Okta users are created in Airflow at first sign-in rather than pre-provisioned by hand. | Decide who may sign in at all, since Okta app assignment and group membership control access before Airflow sees the login. |
| Role sync at login | Enable AUTH_ROLES_SYNC_AT_LOGIN so Airflow re-checks Okta groups on every login. | A user removed from an Okta group loses the mapped role at the next login, not at once. Confirm how long existing sessions remain valid in your setup. |
| Break-glass admin | Keep at least one local or documented admin path that does not depend on Okta group membership. | Test the path before go-live. A mapping error can lock out every admin at once. |
| Unmapped or multiple groups | Define the precedence when a user belongs to several mapped groups, and decide whether the highest role wins. | Review the effective role in the UI for test users in each group, because overlapping mappings are easy to miss. |
| Change verification | Record the mapping file, Okta group assignments and test results for each release of the configuration. | Auditors typically ask who can grant roles and how removal is enforced, so keep evidence of both the group assignment and the login test. |
How the OIDC login flow reaches Airflow
The browser never talks to Okta on Airflow's behalf in a way you can skip: the sign-in starts at the Airflow UI, which redirects the user to the Okta authorization endpoint with the client ID, requested scopes and a redirect URI that points back to Airflow's OAuth callback under /auth. Okta authenticates the user, applies your org and app policies (MFA, network zones, assignment), and redirects the browser back to that callback with a one-time authorization code. The FAB auth manager, which provides the okta OAuth provider, then exchanges that code server-to-server at Okta's token endpoint for an ID token and an access token. Because the exchange happens on the Airflow API side, the client secret never reaches the browser. When debugging, confirm the redirect URI in the Okta app matches the callback Airflow generates character for character, including scheme, host and port behind any reverse proxy.
Airflow then reads the identity from the ID token, and where needed calls the provider's user info endpoint to fill in fields such as name, email and group claims. The FAB provider uses those claims to decide who the user is and which roles apply. This is where the local user record is created or updated in the Airflow metadata database. AUTH_USER_REGISTRATION controls whether an unknown user gets a new record on first login, and AUTH_ROLES_SYNC_AT_LOGIN controls whether roles are recalculated from the claims on every sign-in. Before go-live, confirm with your own Okta admin that the groups claim is present in the ID token or user info response for test users, because a missing claim quietly results in users with no useful role.
After the callback succeeds, the Airflow UI receives its session token in an httponly cookie named _token, so scripts and browser developer tools cannot read it directly. Each auth manager exposes a token endpoint, usually POST /auth/token, and expired tokens are refreshed through the auth manager's refresh path where that is supported. When a user is signed in but sees errors on API calls, check whether the _token cookie is present and whether the token endpoint returns a valid response. Confirm the exact endpoint, cookie behavior and refresh support for your Airflow version and FAB provider release in the auth manager documentation before writing monitoring or runbooks around them.
Hardening Okta login for production
A working Okta sign-in is not yet a production one. The cards below cover who can sign in, where secrets live, how traffic is protected, how new accounts are created, who holds Admin, and how you recover and audit sign-in activity. Each control is set in Okta, in webserver_config.py, or in your logging pipeline, so it should be reviewed across all three together.
Restrict sign-in to named Okta groups
Okta authenticates anyone assigned to the Airflow application, so the first control is the assignment itself. Assign the application only to the groups that should reach Airflow, and confirm that broad groups such as Everyone are not attached. On the Airflow side, FAB role mapping decides what a signed-in user can do, but it does not stop a user who was never assigned in Okta from reaching the login page. Test with an account outside the allowed groups and confirm it is refused.
Keep the client secret out of config
The Okta client secret is a credential that lets Airflow exchange authorization codes, so it should not sit in a plain webserver_config.py committed to source control. Load it from an environment variable injected by your secrets store or Kubernetes secret, and restrict who can read the file on the webserver host. Rotate the secret on a set schedule and after any staff change to the people who can read the deployment. Ask your platform team which store is approved for this.
Serve Airflow only over HTTPS
OAuth redirects and session cookies must travel over TLS, and the redirect URI registered in Okta must match the Airflow callback exactly, including scheme, host and path. Register only the production hostname, remove stale localhost entries, and confirm that the API server is not reachable over plain HTTP from outside the load balancer. A mismatched redirect URI usually fails at login, so test it in staging before production cutover.
Limit self-registration defaults
With AUTH_USER_REGISTRATION enabled, an Okta user who signs in for the first time is created in Airflow automatically. Set the registration default role to the least privileged role that makes sense, typically Viewer or Public, and let mapped groups grant anything higher. Review whether your Okta tenant has self-service sign-up or broad group membership that would let unexpected users reach the registration path. Confirm the chosen default with your security team before enabling it.
Review Admin role assignments
Admin in Airflow can change connections, variables and user roles, so the group that maps to Admin deserves the tightest review. Keep the list of Okta groups that map to Admin short, record the owner of each group, and review membership on a fixed schedule. Also check that AUTH_ROLES_SYNC_AT_LOGIN behaves as you expect, because a user removed from an Admin group should lose that role at their next sign-in.
Keep a break-glass local account
If Okta is unavailable or a misconfiguration locks out every administrator, you need a way back in. Plan one local break-glass account with a strong, vaulted password, held by a small named group, and tested before go-live. Disable it for daily use, log every use, and rotate its password after each use. Confirm with your team whether the FAB configuration you choose still allows database-backed local login alongside OAuth.
Log sign-in and role events
Okta keeps its own system log of authentication events, but Airflow logs are what show which role a user actually received. Forward Airflow webserver and API server logs to your central store, and correlate login timestamps with Okta events for the same user. Alert on new Admin grants, registrations outside expected groups and repeated failed callbacks. Confirm retention with your compliance team, since the period depends on your own policy.
Giving automation API access outside the browser
Browser SSO only covers people who sign in through Okta and open the Airflow UI. Scripts, CI jobs, monitoring checks and deployment pipelines that call the Airflow REST API have no browser session, so they need their own way to authenticate. Decide this before you finish the Okta configuration, because the choice affects who owns the credential, how it is rotated and what audit trail a call leaves behind. The two options to compare are a service account with API credentials issued through your identity provider, and tokens obtained from the auth manager token endpoint, usually POST /auth/token, using a credential the automation holds.
A service account keeps non-human access in the same identity system as people, so you can disable it, scope its group membership and review it in the same access reviews. The cost is that you must define who owns each automation identity, where its secret lives and how it is rotated. Token-based access fits automation that should receive short-lived credentials, but the token itself is only as safe as the secret used to obtain it. Map each automation job to one identity, keep it out of shared accounts, and record which Airflow role it inherits so that a compromised job cannot exceed what it needs.
Before you standardize on either approach, confirm with the FAB provider documentation for your target Airflow and provider versions how tokens are issued, when they expire and whether and how they are refreshed. Test a long-running job against a real expiry window, and confirm how a revoked Okta account or disabled service account affects tokens already in circulation. Pin these answers in your runbook, because the behavior of token endpoints and cookies can change between releases and automation that silently fails after an expiry is harder to diagnose than a failed login.
Why Okta login to Airflow fails
This table lists the failures teams usually hit when wiring Okta into the FAB OAuth provider, with the likely cause and the fix for each. Read it while testing sign-in, because most failures show up as a redirect error, a user with no access, or a session that expires too early.
| Failure | Likely cause | Fix |
|---|---|---|
| Redirect URI mismatch | The sign-in redirect URL registered in the Okta app does not exactly match the callback URL Airflow sends, often because of a different host, port, or missing /auth path. | Copy the callback URL from the Airflow login error, register it exactly in the Okta app, and confirm the scheme and host match the public address users type. |
| Missing group claim or wrong claim name | The Okta authorization server does not include a groups claim in the ID token or userinfo response, or the claim name in webserver_config.py differs from the one Okta sends. | Add a groups claim to the Okta token with a filter that matches the intended groups, then confirm the claim name in the decoded token before editing AUTH_ROLES_MAPPING. |
| Users without a mapped role get no access | The user's Okta groups do not match any key in AUTH_ROLES_MAPPING, and no default role is set for new users. | Map every group that should reach Airflow, decide on a default role for users with no mapped group, and test with one account from each group. |
| Sync at login removes roles unexpectedly | AUTH_ROLES_SYNC_AT_LOGIN re-checks roles on each login, so a group removed in Okta or a temporary manual role change is overwritten the next time the user signs in. | Manage roles only through Okta groups when sync is on, or turn sync off if roles are assigned by hand. Keep a documented break-glass admin account either way. |
| Expired or missing _token cookie | The UI receives its token in an httponly cookie named _token. Cookies are lost when the browser blocks them, the domain or path changes, or the token expires without a refresh. | Confirm the Airflow URL does not change between login and use, check browser cookie settings for the Airflow host, and verify that the auth manager refresh path works for your version. |
| Clock skew between servers and Okta | Token validity checks such as issued-at and expiry fail when the Airflow host or its container clock drifts from real time. | Enable time synchronization on all Airflow hosts and nodes, then retest. Confirm the clock source with your infrastructure team before changing Airflow settings. |
| HTTPS or reverse proxy header problems | Airflow sees plain HTTP or the wrong host behind a load balancer or ingress, so it builds http:// callback URLs or rejects forwarded headers. | Configure the proxy to forward the original scheme and host, make Airflow trust the proxy headers you control, and test the login flow through the same public URL users will use. |
Questions buyers ask before configuring Okta with Airflow
How much effort does Okta SSO for Airflow take, and what drives it?
The effort depends mostly on how many Okta groups must map to Airflow roles, how many Airflow environments need their own OIDC application, and whether automation outside the browser needs API access set up as well. A single production instance with three or four groups is a small configuration task. Each added environment, custom role, or DAG-level permission rule adds review, testing, and documentation work. Ask any partner to break the quote down by these items so you can see which ones you need now and which can wait.
Can our internal team set up Okta with Airflow without a partner?
Yes, if your team already runs Airflow 3 and has someone comfortable with OAuth and OIDC. The work is mostly configuration in the FAB auth manager (through webserver_config.py), an Okta application with the correct redirect URLs, and role mapping. The parts teams most often underestimate are group claim design, testing role sync at login, and keeping a break-glass admin that still works when Okta is unavailable. A partner is useful when you need the work documented, tested in each environment, and handed over with a runbook your staff can keep operating.
What do we need from our Okta and Airflow administrators?
Your Okta administrator needs to create or approve an OIDC web application, decide which groups or claims will be sent in the ID token, and confirm who may sign in. Your Airflow administrator needs to own the webserver_config.py file, the deployment secrets that hold the client secret, and the role mapping decisions. Both should agree on group naming, the default role for new users, and who approves changes. Plan time for these people to review test results in a non-production environment before production access changes.
How long does Okta SSO for Airflow take to set up?
Duration depends on scope, approvals, and how many environments are involved. A single development instance with a short list of groups is usually quicker to finish than a multi-environment rollout that includes change control, security review, and API access for automation. The longest steps are often waiting for Okta app approval and agreeing on role design, not the Airflow changes themselves. Ask for a timeline tied to a written scope with named milestones, and confirm which approvals sit on your side.
Does Apache Airflow have a paid edition that includes SSO?
No. Apache Airflow is an Apache Software Foundation project released under the Apache License 2.0 (Apache-2.0), and the project does not offer a paid edition. The FAB auth manager and its OAuth providers, including Okta, are part of the open-source distribution. Your costs are the infrastructure you run Airflow on, the people who operate it, and any implementation partner you choose to engage. Confirm licensing terms for any third-party components you add around Airflow, since those may differ.
What changes if we later move Airflow to another auth manager?
Airflow 3 allows only one auth manager at a time, set by the auth_manager option, so changing providers is a deliberate configuration change rather than a switch you can toggle per user. The Okta-specific settings in webserver_config.py, the OIDC application, and the role mapping would need to be redesigned for the new manager, and users, roles, and permissions would need to be migrated or recreated. Plan for a test environment, a parallel break-glass admin during cutover, and a review of which DAG-level permissions the new manager enforces. Confirm the target manager's behavior with its own documentation before committing.
Which Okta and Airflow decisions cause the most rework later?
Most rework comes from group design, not from the Airflow settings themselves. Groups that were named by team but later reorganized, roles granted directly to individuals instead of through groups, and missing decisions about the default role for new users all force a second pass. Settle role mapping, role sync at every login, and the handling of API tokens for automation before the first production sign-in. Written decisions reduce the number of changes you will need to make after go-live.
How DeployOpen scopes and delivers Airflow SSO with Okta
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, and Airflow SSO with Okta follows the same method. We agree the scope in writing first, then build the FAB okta OAuth login, group mapping and API access in your environment and hand over the configuration and runbooks.
How we scope
- Confirm the Airflow 3 version, the auth_manager setting and the FAB provider version your deployment runs.
- Agree the Okta org, OIDC app type, group claims and the role mapping that your teams need.
- Write down who registers new users, which roles they receive and which break-glass admin stays available.
How we build
- Configure webserver_config.py for the okta provider, redirect URLs under /auth and AUTH_ROLES_MAPPING.
- Test login, role sync at each sign-in and registration of a new user in a non-production environment first.
- Set up token-based API access for automation outside the browser, using the auth manager token endpoint and its expiry behavior.
How we hand over
- Deliver the written configuration, with secrets kept out of source files and stored in your chosen secrets store.
- Provide a test script and checklist that your team can rerun after Okta or Airflow changes.
- Document the role mapping, the Okta app settings and the steps for rotating client credentials.
How we support
- Fixed-scope engagements end at the agreed handover, with deliverables and timelines set out in the written scope.
- Ongoing support, upgrades and re-testing after Airflow or FAB provider updates are available as a retainer.
- Ask any quote to state which components, environments and test cases are included and which remain with your team.
