Apache Airflow SSO with authentik through FAB OAuth
A platform team that wants Airflow users to sign in with their central identity provider, and to receive Airflow roles from the groups they already hold in that provider, has a supported path today: the FAB auth manager's OAuth provider, configured in webserver_config.py, with authentik acting as the OpenID Connect issuer. This section sets the boundaries of that choice before the configuration details appear in the sections that follow. In Airflow 3, only one auth manager can be active at a time, selected through the auth_manager option, and the FAB auth manager is installed from the FAB provider rather than included in core. Confirm that the FAB provider version you install matches the Airflow 3.3.2 line you run, and decide early that FAB will be the auth manager for the whole deployment, because switching later changes how every user and role is authorized.
The integration does one job: it sends a user to authentik, validates the returned ID token against the expected issuer and audience, and then maps the groups in the token to Airflow roles at login. It does not cover API access for scripts and automation, which needs its own credential design and is handled separately. It also does not cover LDAP or Active Directory, Microsoft Entra ID, Okta, Google or GitHub, each of which has its own provider settings and sibling page. authentik itself can federate upstream directories and expose other protocols, but this page assumes authentik publishes an OAuth2/OIDC provider and application for Airflow and that group membership is included in the claims Airflow reads. Verify that the group claim name and the group names in your authentik instance match what the role mapping expects before you go live.
Plan for two operational risks at the start. First, the Airflow login depends on authentik, so an outage or misconfigured provider locks out every interactive user, which is why a local break-glass administrator should be designed in advance rather than improvised during an incident. Second, the authentik side is a separately versioned product with its own upgrade cadence, so decide which authentik release line you will track and who approves upgrades that could change token contents. Review the FAB webserver authentication documentation for the exact option names and the current provider behavior before you write the configuration.
What you need before configuring authentik and Airflow
Before touching webserver_config.py or an authentik provider, settle the versions, database, identity infrastructure and network paths that the login flow depends on. Most failed SSO attempts trace back to one of these layers rather than to the OAuth settings themselves.
Airflow 3 runtime and Python
Confirm you are deploying Airflow 3, currently at patch 3.3.2, on a Python version within the supported range of 3.10 to 3.14. Airflow 3 replaces the webserver with the API server and requires the DAG processor to run as its own component, so the SSO callback lands on the API server, not the old webserver. Ask your team which process will serve the /auth callback before you write the redirect URL.
Metadata database
Use PostgreSQL 14 to 18 or MySQL 8.0, 8.4 or an Innovation release for the Airflow metadata database. MariaDB is not supported, and SQLite is unsuitable for production because it risks data loss. Confirm the database is backed up and reachable from every Airflow component, since the FAB auth manager stores users and roles there once a login creates them.
Kubernetes or virtual machine host
Decide whether Airflow runs on Kubernetes 1.30 to 1.35 or on virtual machines with at least 4 GB of RAM recommended per host. The Helm chart and official container image suit Kubernetes, while VM installs need you to manage Python dependencies and service units yourself. Either way, the FAB provider must be installed in the same environment as Airflow, because the OAuth code runs there.
FAB provider alongside Airflow
Airflow 3 defaults to the Simple auth manager and runs only one auth manager at a time, set through the auth_manager option. Plan to install the FAB provider package, pin it with your Airflow constraints file, and set the auth manager to FAB before writing OAuth settings. Record the provider version in your change record so an upgrade does not silently change login behavior.
authentik release line
Choose an authentik release from a line that still receives security fixes, currently 2026.5.x and 2026.8.x according to the security policy, and plan to follow those lines as they move. Confirm the exact image tag you intend to deploy against the releases page, because the project announces security releases at least 24 hours in advance and you need time to schedule the upgrade window.
PostgreSQL-backed authentik and network paths
authentik runs as a server container and a worker container, with PostgreSQL holding all configuration and data except uploaded files. Since the 2025.10 release Redis is no longer used, so PostgreSQL carries caching, tasks and sessions, and connection counts rise. Confirm the browser, the Airflow API server and authentik can reach each other over TLS with certificates your internal CA trusts, and that the issuer URL in the Airflow configuration matches the one authentik publishes. Treat Compose, which the project positions for testing and small-scale production, as a starting point and plan a high-availability layout for anything more.
Configuring the authentik provider and Airflow OAuth in order
This sequence connects an authentik OAuth2/OIDC provider to Airflow's FAB auth manager so that a test user signs in, receives a role from their authentik group, and is recorded in Airflow with the expected access. Each step ends with a check that the next step depends on.
Create the OAuth2/OIDC provider in authentik
An authentik administrator creates an OAuth2/OIDC provider and an application that uses it, and sets the redirect URI to the Airflow callback path under /auth that the FAB OAuth flow expects. Confirm the redirect URI against the Airflow version and FAB provider release you are deploying, since the callback path is set by that package. Choose a signing key and the scopes Airflow will request, including the scope that carries group membership. The step is done when the provider appears in the application list with a client ID and client secret and the redirect URI matches your Airflow base URL exactly. Note that authentik's Docker Compose guide is intended for test and small-scale setups, so plan where the authentik server and worker run before this step.
Record the issuer and client credentials
Copy the client ID and client secret from the provider and store the secret in your secrets store, not in a shared document or a DAG file. Then open the provider's OpenID configuration and record the issuer value exactly as authentik publishes it, including any trailing slash. Confirm the issuer, authorization, token and JWKS endpoints resolve from the Airflow API server host, because the token exchange runs there and not in the browser. The step is done when you can fetch the discovery document from that host and the issuer in it matches the value you recorded.
Set the issuer in client_kwargs
In webserver_config.py, add the OAuth provider entry for authentik with the client ID, client secret and server metadata URL, and set the issuer under client_kwargs. The FAB check compares the ID token's issuer and audience, and login fails if the provider metadata lacks an issuer, so this setting is required for authentik. Keep the client secret loaded from an environment variable or secret file. The step is done when the configuration file loads without error in a Python shell on the API server image and the issuer value is identical to the one you recorded in the previous step.
Select the FAB auth manager
Set the auth_manager option in the Airflow configuration to the FAB auth manager, since Airflow 3 allows only one auth manager at a time and uses the Simple auth manager by default. Confirm the FAB provider package is installed in the same image or environment as the API server, because the auth manager comes from that package. Restart the API server and the DAG processor so both read the new configuration. The step is done when the API server starts and the login page offers the authentik provider rather than the Simple auth manager's login.
Map authentik groups to Airflow roles
Define AUTH_ROLES_MAPPING so that each authentik group name maps to the Airflow role it should receive, and confirm the group claim is included in the ID token or userinfo response by the scope you requested. Decide which role unknown users get, if any, and document the mapping as the access record auditors will ask for. Keep a break-glass administrator account outside SSO. The step is done when a group claim with the expected values appears in a decoded token from a test login, and each group name in the mapping matches that claim exactly.
Set user registration and role sync at login
Set AUTH_USER_REGISTRATION to decide whether Airflow creates an account on first login, and set AUTH_ROLES_SYNC_AT_LOGIN so that roles are re-read from the identity provider on every login. Enabling role sync means removing someone from an authentik group takes effect at their next sign-in, so state that expectation in your access procedure. Confirm both values in the loaded configuration. The step is done when the settings are present in the running configuration and you have written down the behavior you expect for new and departing users.
Verify login and decode the ID token
Sign in with a test user who belongs to exactly one mapped group, then decode the ID token and confirm the issuer and audience claims match the client configuration and the group claim contains the expected value. Check in the Airflow user list that the account was created or updated and holds only the role mapped to that group. Repeat with a user in a second group and with a user in no group. The step is done when the three test users receive the expected roles and a sign-out followed by a failed login for an unmapped user behaves as your access policy requires.
Choosing how authentik groups map to Airflow roles
Mapping groups is the approach that gives the most control over DAG administration, because access follows the groups your team already manages in authentik. The FAB auth manager reads a list of groups or roles from the ID token or user info response and translates each entry through AUTH_ROLES_MAPPING in webserver_config.py. For this to work, authentik must send a groups claim on the OAuth2/OIDC provider, which depends on the scope and property mappings you attach to that provider.
- Groups claim: Configure the authentik provider so the token or user info includes a groups claim listing each user's group names. Confirm the claim name your authentik version emits and the name FAB reads.
- Explicit mapping: Map each authentik group to one Airflow role in
AUTH_ROLES_MAPPING, for example a platform group to Admin and an analyst group to Viewer. Keep the table short so reviewers can read it in one pass. - Sync at login: Enable
AUTH_ROLES_SYNC_AT_LOGINso that removing a user from a group in authentik takes effect at their next sign-in, not only at first registration. - Admin scope: Map only the groups that should edit DAGs, connections and variables to Admin. Op or a narrower role suits teams that trigger runs but should not change pipeline code or secrets.
Before mapping production users, run a test login with a known group membership and confirm the role that Airflow assigns.
A user who signs in through authentik but belongs to none of the mapped groups still needs a decision. FAB can create an account at first login when registration is enabled, and the role assigned at creation determines what that person can see before anyone reviews the account. A default role is useful for a broad read-only audience, but it can also give access to people who should not have an Airflow account at all.
- Registration setting:
AUTH_USER_REGISTRATIONcontrols whether unknown users receive an account at first login. Leave it off if only named groups should have access. - Lowest default role: Set the registration default to a read-only role such as Viewer so that a missing group never grants write access to DAGs or connections.
- Interaction with sync: When role sync at login is enabled, the default role is re-evaluated at each sign-in, so a user who later joins a mapped group receives the mapped role. Test that transition explicitly.
- Read exposure: A Viewer can still see DAG metadata, run history and, depending on configuration, task logs. Decide whether every authenticated authentik user should have that visibility.
Confirm the exact name of the default role setting and its behavior in the FAB webserver authentication documentation for your provider version, then test with an account that belongs to no group.
A break-glass admin is a local account that still works when authentik, its certificate or the network path to it is unavailable. Without one, a wrong role mapping or an identity outage can lock every administrator out of Airflow. The account exists for recovery only, so it needs the same protection as other privileged credentials and a documented procedure for each use.
- Local login: Keep a database-password login available to one or two named administrators. Confirm in your configuration that password login remains enabled while OAuth is set up.
- Credential storage: Hold the password in a sealed vault with two-person retrieval, and keep it out of the DAG repository and shared documents.
- Usage record: Log each use, the reason, and any change made during the session so the event can be reviewed as privileged access.
- Login testing: Verify the break-glass login during every change to the auth configuration, so it is known to work before an incident needs it.
Ask your security team to confirm where the credential is held, who can retrieve it, and how often the login is tested.
The three approaches answer different questions. Group mapping decides who administers DAGs during normal operation, the default role decides what an unmapped but authenticated user can reach, and the break-glass account decides who can recover Airflow when SSO fails. Reviewing them side by side shows where admin reach comes from and how large each population is.
- Mapped groups: Admin reach follows authentik group membership, so it is only as tight as the process that adds people to those groups.
- Default role: Reach for anyone without a group is fixed at the default role, so a read-only default keeps unmapped users from changing DAGs.
- Break-glass account: Reach is full administrative access, which makes it the largest single exposure, so the number of people who can use it should stay very small.
- Combined model: Most deployments use all three: groups for daily administration, a read-only default for everyone else, and one recovery path that is tested and logged.
Record the mapping table, the default role and the break-glass procedure in your change record so a reviewer can trace each login to a role and a responsible owner.
Mapping authentik claims and groups to Airflow identities and roles
This table lists the OIDC claims the FAB OAuth provider reads from an authentik ID token, the authentik source for each, and the Airflow role a group should map to. Use it as a checklist when you build the mapping, then confirm each claim name and role name against the FAB provider version you run. The main takeaway is that the issuer and audience checks fail closed, so a missing issuer setting or a mismatched client ID blocks every login before any role is applied.
| Claim or setting | authentik source | Airflow use |
|---|---|---|
| Issuer (iss) | Issuer URL of the authentik OAuth2/OIDC provider, set in client_kwargs | FAB checks it against the ID token; login fails if the metadata lacks it |
| Audience (aud) | Client ID of the Airflow application in authentik | FAB checks the token audience matches the client it registered |
| Subject (sub) | Stable user identifier from the openid scope | Identifies the user; confirm FAB uses it for the username or only for logging |
| email scope, from the user's authentik profile | Used for the Airflow user record; confirm the claim name FAB reads in your version | |
| Name | profile scope, from the user's authentik profile | Used for first and last name fields on the Airflow user |
| Groups | groups scope mapping that emits group names, added to the Airflow provider | Input to AUTH_ROLES_MAPPING; the group claim name must match the FAB configuration |
| Admin group to Admin role | Group such as airflow-admins in authentik | Maps to the Admin role in AUTH_ROLES_MAPPING; confirm role name in your FAB release |
| Operator and viewer groups | Groups such as airflow-ops and airflow-viewers | Map to Op and Viewer roles; keep the most privileged group a small, reviewed set |
Hardening the authentik to Airflow trust relationship
Once authentik issues tokens that Airflow trusts for sign-in, the weakest points are validation settings, stored secrets, redirect targets and the people who can change roles. The cards below cover each link in that chain, from token checks to the authentik admin accounts that sit above all of them.
Strict issuer and audience checks
Airflow's FAB OAuth login should accept an ID token only when its issuer and audience match the authentik application it was configured for. Set the issuer explicitly in client_kwargs so login does not depend on metadata alone, and test with a token from a second application to confirm it is rejected. Review this setting again after any change to the authentik provider or slug.
Client secrets outside source control
The OAuth client secret in webserver_config.py grants the ability to impersonate the Airflow application, so it should never be committed to a DAG bundle, Helm values file or image layer. Inject it at runtime from your secrets store and rotate it when staff with repository or cluster access change. Confirm that Airflow logs and support bundles do not echo the configuration.
Exact redirect URI registration
Register only the exact callback URL that Airflow uses under its /auth path, with the scheme and host of your production deployment. Wildcard or multiple redirect entries widen the set of places an authorization code can be sent. Remove test and staging callbacks from the production authentik application before go-live.
Control who edits Airflow roles
Role mapping is only as trustworthy as the authentik groups that feed it. Limit membership of the groups mapped to Airflow Admin to a named set of administrators, and require approval for changes to those groups. Treat a change to the mapping in webserver_config.py as a change-managed event, since it alters who gets elevated access.
Role sync at login
Turn on role synchronization at each login so that a user removed from an authentik group loses the matching Airflow role the next time they sign in. Without it, a revoked role can persist for as long as the Airflow user record exists. Test removal explicitly, because existing sessions may remain valid until they expire, and confirm that behavior against your session settings.
Protect authentik admin accounts
Anyone who administers authentik can change applications, groups and the claims Airflow relies on, which makes the authentik admin tier a path into Airflow itself. Keep a small number of named administrators, enforce strong multi-factor authentication for them, and keep a separate break-glass account in a sealed process. Confirm how your chosen edition handles audit logging, since the Enterprise features are separate from the open-source code and must be verified against the edition you select.
Running authentik and Airflow together in infrastructure you control
Self-hosting authentik next to Airflow adds a second stateful platform to your estate, and the sign-in path for every Airflow user depends on it. Plan for two separate PostgreSQL-backed systems: authentik's server and worker containers, which store all configuration and data in PostgreSQL except uploaded files, and the Airflow metadata database, which should be PostgreSQL or MySQL rather than SQLite. Decide whether these share a database server or run on separate instances, and whether each has its own backup schedule and restore test. Authentik's 2025.10 release moved caching, tasks, sessions and WebSocket functions off Redis and onto PostgreSQL, and the release notes warn of roughly 50% more PostgreSQL connections after upgrading. Confirm that your database server's connection limits and any pooler configuration account for that increase before you cut over, and check the authentik 2025.10 release notes against the version you intend to deploy.
Upgrade cadence is where the two projects differ most, so write a joint calendar rather than two separate ones. Authentik's security policy names its supported release lines as the ones receiving security fixes, and it announces security releases at least 24 hours in advance, so subscribe to those notices and keep your authentik version on a supported line. Airflow's support policy gives limited-maintenance versions security and critical bug fixes only, and end-of-life versions no fixes at all. Confirm the current status of the Airflow line you run in the Airflow version life cycle before you approve a go-live date. An authentik upgrade can change the OIDC behavior your Airflow client depends on, so test login, role sync and API access in staging after each one, and keep a rollback path for the authentik database as well as the containers.
Why Airflow login with authentik fails and how to fix it
This table lists the failures teams most often hit when wiring the FAB OAuth provider to authentik, with the likely cause and the fix for each. Read it when a login loop, an error page or an unexpected role appears, and work down the rows from the issuer check, since it is the most frequent cause.
| Symptom | Likely cause | Fix |
|---|---|---|
| Login fails after authentik redirects back to Airflow | The issuer is missing from client_kwargs, so FAB cannot check the id_token against the issuer when authentik's provider metadata does not include one | Set the issuer in client_kwargs to the authentik issuer URL for this OAuth application, then confirm the value matches the iss claim in a decoded id_token |
| id_token rejected with an audience error | The aud claim does not contain the client ID that Airflow uses, often because the client ID was copied from another provider or the wrong authentik application was used | Compare the client ID in webserver_config.py with the Client ID on the authentik provider, and check that the aud claim in the id_token includes it |
| Redirect error or browser returns to an error page | The redirect URI registered in authentik does not exactly match the callback Airflow sends, such as a different host, scheme, port or missing /auth path segment | Register the full callback URL that Airflow generates for the FAB OAuth provider in the authentik provider, using the exact public host and https scheme |
| User signs in but has no roles or sees a near-empty UI | AUTH_ROLES_MAPPING does not match the group names or IDs that authentik sends, or the groups scope is not included in the provider's scopes | Confirm the groups claim is present in the token, add the scope that carries it, and map each authentik group name to the matching Airflow role |
| New users are refused or created with no role | AUTH_USER_REGISTRATION is off, or it is on without a default role that gives users any access | Enable user registration only if your policy allows it, set a deliberate default role, and test one account from each authentik group |
| Role change in authentik does not appear in Airflow | AUTH_ROLES_SYNC_AT_LOGIN is disabled, so roles are set once at first login and not refreshed | Enable AUTH_ROLES_SYNC_AT_LOGIN, then sign out and back in to confirm the new role applies |
| Token request fails with a certificate or TLS trust error | Airflow does not trust the CA that signs the authentik certificate, which is common with private or internal certificate authorities | Add the internal CA to the trust store used by the Airflow webserver and API server containers or hosts, then retest the token exchange |
| Login works in the browser but automation or API calls fail | Browser OAuth is configured, but the API server does not accept the token type or the client used by the automation | Confirm which authentication path the automation uses and test it separately from browser sign-in before changing the provider settings |
Questions teams ask before configuring authentik SSO for Airflow
What drives the effort of connecting authentik to Airflow?
The effort depends on four things: how many identity provider groups must map to Airflow roles, how much authentik configuration already exists, how TLS and network paths are set up between Airflow, the browser and authentik, and how many roles the access model needs. A small team with a clean authentik tenant and three roles is a short configuration task. A tenant with many groups, nested group logic and existing applications needs design time before anyone edits webserver_config.py. Ask any partner to list these four inputs in the written scope, because they set the work.
Is the open-source authentik edition enough for Airflow SSO?
The OAuth2/OIDC provider that Airflow's FAB auth manager uses is part of the open-source authentik project, which is released under the MIT license for most of its code. The enterprise features on the pricing page, such as Microsoft Entra ID and Google Workspace integrations, mTLS, and enhanced audit logging, are not needed to sign Airflow users in through OIDC. Confirm against the authentik pricing page and the license file for your exact needs, and check whether your audit or support requirements call for a paid edition.
What is one-time work and what recurs after go-live?
One-time work covers the authentik provider and application setup, the issuer and audience checks, the FAB OAuth configuration, the group-to-role mapping design, and testing with break-glass access. Recurring work covers authentik and Airflow upgrades, certificate renewal, group membership reviews, changes to role design, and re-testing after either system changes. Software licenses for Airflow and the open-source authentik edition carry no fee, so recurring cost is mostly staff time and any support retainer you choose. Ask for the recurring items to be listed separately in the quote.
Can an in-house team configure authentik SSO for Airflow alone?
Yes, a team that already runs authentik and Airflow can do this internally, provided it has someone who understands OIDC token validation and someone who owns Airflow's webserver_config.py. The risk sits in the details: a missing issuer in the client settings stops login, and an unchecked audience claim weakens the trust check. Teams without an OIDC background, or without a test environment to try role mapping before production, often get more value from a fixed-scope engagement with written acceptance tests.
What do identity and platform staff need to provide?
Identity staff need to supply the authentik administrator access, the group names and membership rules that define Airflow roles, and the decision on who may self-register. Platform staff need to supply the Airflow hostnames, the TLS certificate chain, DNS, network paths from Airflow to authentik, and the place where secrets such as the OAuth client secret will be stored. Both teams should agree on a named owner for role changes, since group membership in authentik controls Airflow access after every login.
How is API access for automation handled separately from SSO?
Browser sign-in through SSO does not cover scripts, CI jobs or other services that call the Airflow REST API. Those need their own credentials and token handling, planned separately so that service accounts do not depend on a person's browser session. Decide which automation needs API access, which roles it receives, and how credentials are rotated and stored. Because Airflow 3 changes how the API server and token handling work, confirm the approach against the Airflow auth manager documentation before you design it.
How long does an authentik SSO setup for Airflow take?
The duration depends on the drivers already covered: group count, authentik maturity, network and TLS readiness, and role design. No duration is set for this integration, so ask for a timeline based on your written scope rather than a generic estimate. A realistic plan separates design, a test environment, a pilot group of users, and production cutover, with time reserved for the break-glass admin check. Ask any partner to show which of these phases the quote includes.
How DeployOpen scopes the authentik and Airflow integration
Every authentik and Airflow SSO engagement starts with a written scope agreed before any configuration changes are made. DeployOpen does not begin work on the identity provider or the Airflow webserver until the deliverables, the environments covered and the acceptance criteria are recorded in that document. For this integration, a typical scope covers the authentik OAuth2/OIDC provider and application for Airflow, the webserver_config.py file that sets the FAB OAuth provider and the issuer in client_kwargs, the AUTH_ROLES_MAPPING and AUTH_ROLES_SYNC_AT_LOGIN settings, a test plan that covers valid and invalid token paths, and a runbook for rotating the client secret and recovering an admin login. Timelines and fees follow from that written scope and are quoted separately, so the reader should ask for each deliverable to be listed by name.
The client supplies the inputs that cannot be guessed from outside. That means administrative access to the authentik tenant, or a named administrator who can create the provider, application, groups and bindings, and a decision on the group design that will feed role mapping, including which authentik groups correspond to Airflow Admin, Op and Viewer. The client also provides test users in each group, a staging Airflow environment for verification, and the TLS certificates and trusted CA chain used by both services, including any internal certificate authority. If the authentik server or the Airflow webserver will run on infrastructure the client controls, the client should confirm who owns the DNS names and the redirect URL path that Airflow uses for OAuth callbacks.
Two items should be confirmed in the scoping call rather than assumed. First, confirm the authentik release line your organization will run, because the authentik security policy defines which versions receive security fixes and the project announces security releases in advance. Second, confirm whether the break-glass admin account will remain on the Simple auth manager or FAB database login, since Airflow allows only one auth manager at a time through the auth_manager option. Ask the DeployOpen team to state these assumptions in the written scope so that any change to them is handled as a change request with its own effect on cost and schedule.
How DeployOpen works on this
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For Airflow SSO with authentik, the work runs from a written scope through a tested FAB OAuth configuration to a handover your team can operate without us.
How we scope
- Confirm the Airflow version, the authentik version and where both will run before any configuration starts.
- Map which authentik groups should become Airflow Admin, Op and Viewer roles, and who approves that mapping.
- Agree in writing whether new users are registered at first login and whether break-glass access stays local.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work begins.
How we build
- Configure the FAB OAuth provider in webserver_config.py, including the issuer in client_kwargs for authentik.
- Set AUTH_ROLES_MAPPING and AUTH_ROLES_SYNC_AT_LOGIN to match the agreed group design.
- Test id_token issuer and audience checks, role sync on repeated logins and denied access for users outside the groups.
How we hand over
- Deliver documented configuration, the group-to-role mapping table and the redirect URL and client settings used in authentik.
- Record the test cases run, their results and the steps to repeat them after an Airflow or authentik upgrade.
- Walk your operators through login troubleshooting, including what to check when the issuer or group claims change.
How we support
- Ongoing support, upgrades and continuous testing for this integration are available as a retainer.
- Plan authentik and Airflow upgrades against the release and support notes each project publishes, with your change control.
- Confirm current supported versions and security advisories with each vendor before scheduling a change window.
