How the Keycloak auth manager puts Airflow 3 access in Keycloak
If you run self-hosted Airflow 3 and want sign-in, roles and API access governed by Keycloak, the Keycloak auth manager is the route the Airflow project provides for moving user, group and permission data into Keycloak. It covers Airflow's own access model, so it is narrower than a general single sign-on design, which also has to decide how Keycloak fronts the Airflow UI, how sessions expire and how other applications share the same realm. Plan those questions separately before you configure anything in Airflow.
Airflow allows only one auth manager at a time, and the auth_manager option selects it. The Simple auth manager is the default in Airflow 3, so a fresh deployment does not use Keycloak until you change that setting and install the provider that ships the Keycloak component. Switching the auth manager changes where Airflow looks for users and permissions, so treat it as a planned change for an existing environment, not a toggle. Confirm the exact provider package and its version against the auth manager documentation for the Airflow release you run, since the packaging of auth managers has changed between releases.
The Keycloak auth manager is an alpha component, and its multi-team client limits are the main reason to scope it tightly. Later sections cover what the alpha status means for your support and upgrade plans, and how a single Keycloak client maps onto teams and roles. For now, decide whether your deployment has one team or several, and whether Keycloak will be the only auth manager you need for the lifetime of this Airflow environment. Those two answers determine most of the design that follows.
What you need before enabling the Keycloak auth manager
Enabling the Keycloak auth manager touches the Airflow release line, the metadata database, the Keycloak deployment and the network between them. Each card below is a component to confirm before any configuration starts, because a gap in one usually shows up as a login or permission failure in another.
Supported Airflow 3 release line
Pick an Airflow 3 patch release and check it against the version life cycle before you plan the auth change. The current patch release supplied is 3.3.2, and Airflow 3 was first released on April 22, 2025. Airflow 2 has reached end of life, so an auth manager set up on it would not get fixes. Confirm the Python and Kubernetes versions in the prerequisites page, and confirm that the Keycloak auth manager's provider package version matches your Airflow release.
PostgreSQL or MySQL metadata database
The Airflow metadata database holds the state that the auth layer and the scheduler both depend on. Use PostgreSQL or MySQL in production. SQLite is for testing only and can lead to data loss, and MariaDB is not supported as the Airflow metadata database. Confirm the version your database team will run against the prerequisites list before the cluster is built.
Keycloak target release and database
Target the current Keycloak release, 26.8.1, published October 13, 2026, and confirm it is compatible with the Airflow provider package version you plan to install. Keycloak needs a supported production database, such as PostgreSQL 14 to 18, and the dev-file database is for development only. Decide now whether you will run the upstream release or a vendor distribution, since that choice changes your support path.
Network path to Keycloak
Map every connection the flow needs: users' browsers to Keycloak, users and the Airflow API server to Keycloak endpoints, and the API server to Keycloak for token and metadata checks. Firewalls, proxies and DNS names that differ between the browser and the server are a common cause of redirect and token errors. Document the path in both directions before opening change requests.
Realm, admin and ownership roles
Name the team that owns the Keycloak realm and the Airflow permission model before configuration begins. Plan at least one Keycloak administrator account with break-glass access that is stored and audited separately, and a named Airflow administrator who can map groups to roles. Agree who approves changes to clients, roles and group membership, since these settings decide who can run and change DAGs.
TLS certificates and trust
Issue TLS certificates for the Keycloak hostname and the Airflow API server, and make sure the Airflow services trust the certificate authority that signed them. Certificate mismatches and missing CA bundles block the OIDC flow in ways that look like application errors. Confirm the certificate renewal process and who holds the private keys before go-live.
Configuring Keycloak and Airflow in sequence
Follow this order to connect Airflow 3 to Keycloak through the Keycloak auth manager, starting in a non-production environment. The sequence confirms the upgrade path, installs the provider, models identity in Keycloak, and proves role limits and API access before any production change.
Confirm the Airflow version and upgrade path
Your platform team confirms which Airflow release runs today and whether it can move to Airflow 3 directly. Airflow 2 reached end of life on April 22, 2026, so it receives no fixes. Airflow 3 requires Airflow 2.7 or later before the upgrade, so move to the latest 2.x first and check DAG code with the Ruff AIR301 and AIR302 rules. Done when the target 3.x patch release is confirmed in the version support table and the upgrade plan is approved.
Install the Keycloak provider package
The platform team installs the Keycloak provider package named in the Airflow auth manager documentation into the image or virtual environment used by every Airflow component, including the API server, scheduler and DAG processor. Pin it with the Airflow constraints file so the provider matches your Airflow version. Done when the provider appears in the installed providers list on each component and the image build is recorded in your change system.
Create a dedicated realm and Airflow client
A Keycloak administrator creates a realm used only for Airflow, so Airflow users, groups and roles stay separate from other applications. Inside that realm, register a confidential client for Airflow using the redirect URIs and client settings the provider documentation lists. Store the client secret in your secrets store, never in DAG code. Done when the realm login page loads and the Airflow deployment team can retrieve the client secret through the approved channel.
Map groups and roles to Airflow permissions
Read the provider documentation to find which Airflow roles and permissions the Keycloak auth manager expects. Create Keycloak groups for each team and role, assign users to groups, and keep direct role grants to a minimum. Configure the token mapping the provider needs so group or role claims reach Airflow. Done when a decoded test token for one user shows the expected group and role claims.
Set the auth_manager option and provider settings
Set the
auth_manageroption in the Airflow configuration to the Keycloak auth manager class named in the provider documentation. Add the provider settings using the exact configuration keys from that documentation, and do not guess key names. Airflow 3 allows only one auth manager at a time, so the Keycloak setting replaces the default Simple auth manager and does not run alongside it. Done when the API server starts cleanly and its logs show the Keycloak auth manager loaded.Sign in with one test user per group
Create one test user in each Keycloak group, plus one user with no Airflow group membership. Sign in to the Airflow UI as each user and record which pages, DAGs and actions each one can see and run. Confirm that the views match the role design from the earlier step and that the user without a group is denied access. Done when the results are written up for every group and any mismatch is fixed in Keycloak or the provider settings before you continue.
Issue and test one API token
Generate one API token for a test user using the method the provider documentation describes, then call the Airflow REST API with it. Check that a request inside the user's role succeeds and that a request outside that role is refused. Store the token only in the calling system's secrets store and give it a limited lifetime. Done when both the allowed and refused calls return the expected responses and the test token is revoked afterward.
Record caveats and decide on production
Before any production change, review the status of the Keycloak auth manager in the provider documentation and release notes, and list every caveat it names. Confirm how it handles multi-team access and whether your team boundaries fit that model. Plan for Keycloak changes as well, since the project plans four minor releases a year. Done when a signed review states whether to proceed, with each caveat and its owner recorded.
How Keycloak users, groups and roles map to Airflow permissions
This table compares each Keycloak object with the Airflow permission scope it would influence and the design decision you need to make before rollout. Read it as a checklist for agreeing the mapping with your security and data owners. The main takeaway is that the mapping decides who can trigger, pause and view DAGs and who can manage connections, so confirm every row against the Keycloak auth manager documentation for your installed provider version.
| Keycloak object | Airflow permission scope | Design decision |
|---|---|---|
| Users | Individual sign-in identity that Airflow records against actions such as triggering or pausing a DAG | Decide whether named accounts are the only identities, and how service accounts for automation are created, owned and disabled |
| Groups | Collections of users that can be mapped to a shared set of Airflow access levels | Decide which groups correspond to teams, environments or job owners, and who is allowed to change group membership |
| Realm roles | Realm-wide access levels that apply across all Airflow instances using the realm | Decide whether any realm role grants admin-level Airflow rights, and keep that set as small as possible |
| Client roles | Roles scoped to the Airflow client in Keycloak, which can express Airflow-specific levels | Decide which client roles exist (for example viewer, operator, editor), and confirm the exact role names the provider expects |
| Team or DAG access | Restriction of visibility and actions to specific DAGs or teams, where the provider and your Airflow version support it | Confirm whether team scoping is supported in your version, and define which DAG tags or bundles each team owns before mapping |
| Connection management | Ability to create, edit and read connections, which hold credentials for external systems | Limit this right to a small group, and confirm whether read access to connection details can be separated from edit access |
| Admin rights | Full administrative control over users, pools, variables, connections and configuration | Keep admin mapping to named platform owners, and record who approves changes to that mapping |
Why the Keycloak auth manager is still an alpha component
Alpha status means the Keycloak auth manager can change under you. For an enterprise rollout, the practical meaning is that interfaces, configuration keys and behavior may change between Airflow releases, and the team cannot assume that a setting that works today will survive the next upgrade. Fixes may also arrive on a different schedule from Airflow core, so a defect in the Keycloak integration may be patched later than a defect in the scheduler or API server. The team that adopts this component therefore takes on the testing and the rollback plan that a mature, generally available component would normally carry for them. Before committing, ask the provider maintainers for the current status of the component, the list of known issues, and the changes planned for the next minor release.
Airflow's support policy adds a second constraint. Only supported release lines receive fixes: limited-maintenance versions get security and critical bug fixes only, and end-of-life versions get none. An alpha auth manager on an Airflow line that has moved to limited maintenance or reached end of life leaves you with no path to a fix for the identity layer, which is the component that decides who can trigger, edit and view DAGs. Check the version life cycle table against your planned Airflow version before you choose a target, and plan the upgrade cadence so the Airflow line you run stays inside support for the full life of the deployment.
Pin the Airflow version and the provider version together, and treat the pair as one release unit. Record the exact Airflow patch release, the provider package version and the Keycloak release in your change records, and promote all three through the same staging path. Test each combination against your own Keycloak realm, role mappings and API token flow before it reaches production, and keep the previous pair available so you can roll back the auth configuration without rolling back the whole platform. This page does not promise that the Keycloak auth manager is ready for production use in your environment. Whether it is acceptable depends on your risk tolerance, your test coverage and the answers you receive from the maintainers.
Single-team or multi-team client layout for Keycloak
A single-team layout gives one Airflow deployment its own Keycloak client inside a realm that only that team's users and groups reach. The identity boundary is the realm, so accounts, roles and sessions stay inside one administrative scope. The people who run Airflow often administer Keycloak as well, which keeps change requests short but concentrates trust in a small group.
- Identity boundary: one realm and one Airflow client, with redirect URIs limited to that deployment's hostnames.
- Groups and roles: map a small set of groups, such as admin, operator and viewer, to Airflow roles. Confirm the role names the provider expects.
- Administration: the platform team usually holds realm administration. Record who can change clients, mappers and role assignments.
- Blast radius: a misconfigured client affects only this team's Airflow, but a wrong role mapping can still grant write access to every DAG in the deployment.
- Testing: sign in with one test account per role, confirm that disallowed actions are refused, and check token expiry and logout behavior.
Confirm that the realm administrator list is short, reviewed on a schedule, and matches the people who are allowed to deploy DAGs.
A shared client serves several teams from one Airflow deployment, so separation depends on group membership and on the roles Airflow reads from each user's token. The identity boundary is weaker in this layout because every team's users sit in the same realm and sign in to the same client. This is the layout that needs the most caution while the Keycloak auth manager is in alpha. Confirm what the provider supports for team separation before you choose it.
- Identity boundary: one shared realm and client. Separation is enforced by group claims and Airflow permissions, not by directory structure alone.
- Groups and roles: create one group per team with team-scoped roles. Verify that the token carries the team information Airflow needs to filter DAGs, runs and logs.
- Administration: a central identity team often owns the groups while team leads request membership changes. Define who may add users to each team group.
- Blast radius: one mapper error or a group assigned to the wrong team can expose one team's DAGs, logs and connections to another team.
- Testing: create test users in at least two teams and check that each cannot see, trigger or edit the other team's DAGs, runs, logs and connections.
Get the provider's team separation behavior confirmed in writing, and repeat these checks after every Keycloak or Airflow upgrade.
Separate clients or realms per team move the identity boundary outward, so a configuration error or account compromise stays inside one team's identity scope. Airflow allows only one auth manager at a time, and each deployment reads a single auth manager configuration. Before any team depends on this layout, confirm how one Airflow instance can accept tokens from more than one Keycloak client or realm. A separate Airflow deployment per team avoids that question, at the cost of running more components.
- Identity boundary: each team has its own realm or client, with its own login policies and administrators.
- Groups and roles: roles stay simpler within each realm, but shared operator roles and cross-team reporting need their own design.
- Administration: delegate realm administration to each team only if the platform team keeps control of the Airflow side.
- Blast radius: a bad change stays within one realm, but if the Airflow configuration is shared, one error still affects every team that uses it.
- Testing: verify token acceptance from each realm or client, and test how Airflow behaves when one identity source is unavailable.
Ask the provider and the Airflow community to confirm whether this layout is supported before you write it into the design.
Security settings to lock down for Keycloak-backed Airflow access
Keycloak holds the users, groups and permissions that Airflow trusts, so a weak setting in either system opens the other. The cards below cover the controls that connect them: transport, secret storage, token lifetimes, admin accounts, logging and emergency access.
TLS on every endpoint
Encrypt traffic to the Keycloak server, the Airflow API server, the metadata database and the OIDC redirect paths, not only the public login page. Check that Airflow's configured base URL and Keycloak's redirect URIs use HTTPS and match exactly, since mismatched redirects are a common source of both failed logins and loose configurations. Confirm how certificates are issued and rotated for internal hostnames, and test renewal before the first expiry.
Client secrets kept out of DAG code
The Keycloak client secret that Airflow uses should live in a secrets backend or a Kubernetes Secret, not in DAG files, Git repositories or plain configuration files that many people can read. Review who can read the Airflow configuration and the Git history of the deployment repository. Rotate the secret on a schedule and after any staff change, and confirm how the auth manager reads its settings in your Airflow version.
Short token lifetimes and revocation
API tokens issued for automation should expire quickly, and each team should have a documented way to revoke a token without changing the shared client. Decide who may request tokens, how a leaked token is detected and who approves its replacement. Confirm the token lifetime and signing settings against the Airflow security documentation for your version before you set Keycloak session lengths, because the two systems set lifetimes separately.
Least-privilege Keycloak admin accounts
Keycloak administrators can change realms, clients, role mappings and group membership, which decide what every Airflow user can do. Give platform staff separate admin accounts with only the realm roles their task needs, and keep the Airflow client owners distinct from the people who manage the realm. Require multi-factor sign-in for admin consoles and review admin role membership on a regular schedule.
Sign-in and admin change logging
Record sign-in events and administrative changes in Keycloak, and record Airflow's own authentication and permission activity, then send both to a store your security team can search. Keycloak admin events must be enabled explicitly, so confirm they are on in every realm. Test that a role change made in Keycloak appears in the logs and that someone outside the platform team can review it.
Break-glass local admin with tight access
Keep one local administrator path for Airflow that works when Keycloak is down or misconfigured, and keep its credentials sealed and monitored. Limit it to named people, require a second approver to use it, and alert on every use. Test the path during planned maintenance, since an emergency login that has never been tried often fails when it is needed. Confirm with the Airflow documentation which auth manager settings remain available if the Keycloak provider is unreachable.
Common Keycloak auth manager failures, causes and fixes
This table pairs common failures with their likely causes and fixes when Airflow 3 uses the Keycloak auth manager. Read each row as a starting point, then confirm error messages and option names against the Airflow and Keycloak versions you have installed. Most failures trace back to redirect URIs, role or group naming, token lifetimes, a single auth manager setting, schema migration order, or session handling across Keycloak nodes.
| Failure | Likely cause | Fix to try first |
|---|---|---|
| Sign-in loop or redirect error after Keycloak login | The redirect URI registered on the Keycloak client does not exactly match the callback URL Airflow sends, often because of scheme, host, port or trailing slash differences behind a reverse proxy. | Copy the exact callback URL from the Airflow login error or logs, register it verbatim on the Keycloak client, and confirm the public base URL Airflow advertises matches the proxy hostname. |
| Signed in successfully but user sees no DAGs or menus | Keycloak group or role names do not match the role names Airflow expects for its permissions, so the user maps to no effective access. | Compare the Keycloak group and role names character by character with the mapping in the Keycloak auth manager configuration, then log in again so new claims are issued. |
| API token rejected after expiry | The access token lifetime in Keycloak has passed, or the client's token settings were changed, so the bearer token no longer validates. | Request a new token from the same client, check the token lifetime set in the Keycloak realm, and confirm your scripts refresh tokens rather than reusing a stored one. |
| API token rejected after a realm change | The token was issued by a realm that was recreated, renamed or re-keyed, so its issuer and signing keys no longer match the configured realm. | Update the realm URL and client settings in Airflow, generate new tokens from the current realm, and retire tokens issued by the old realm. |
| Auth manager does not load at startup | Only one auth manager can be active at a time, and the auth_manager option is unset, points to another manager, or two managers are configured together. | Set the auth_manager option to the Keycloak auth manager class in your Airflow configuration, remove other managers from the setting, and restart the API server and scheduler together. |
| Keycloak or Airflow fails after an upgrade with schema errors | Keycloak migrates its database schema at startup by default, so a version jump, a second node starting on a different version, or a failed migration can leave the database in a partial state. | Back up the Keycloak database before upgrading, upgrade one version at a time, use manual migration for large deployments as the upgrading guide describes, and confirm the Airflow and Keycloak versions are compatible. |
| Users are logged out or tokens fail after a high availability change | Sessions are held in node memory or the new topology is not synchronously replicated, so a node change or failover invalidates sessions and cached keys. | Confirm the database is synchronously replicated for the chosen high availability design, check that all nodes share the same realm configuration, and test failover with a live login before cutover. |
What teams ask before bringing in a partner for Airflow and Keycloak
How much effort does an Airflow and Keycloak auth manager integration take?
The effort depends mostly on how many teams share the Airflow environment, how complex the role model is, how mature the existing Keycloak realm is, and how much testing the change needs. A single team with a simple admin and viewer model is a small job. Several teams that need separate DAG visibility, group-to-role mappings, and API token access for automation take longer because each mapping must be designed, reviewed and tested. Ask any partner to break its estimate into these four drivers so you can see which ones your environment triggers.
Can our own team set up the Keycloak auth manager without a partner?
Yes, if you have people who administer Keycloak and people who administer Airflow, and you have time to test an alpha-stage component carefully. The work involves configuring the auth manager option, creating clients and realm roles, mapping groups to Airflow permissions, and generating API tokens. Teams without prior Keycloak experience usually find the realm and group design the hardest part. A partner can make sense when that expertise is missing or when you want an outside review of the permission model before users depend on it.
What do we need to provide for the integration?
Plan to provide four things. First, decisions on realm and group design, including which Keycloak groups map to which Airflow roles and which teams can see which DAGs. Second, test accounts across each role so permissions can be verified rather than assumed. Third, a non-production environment that mirrors your Keycloak and Airflow versions. Fourth, a change approval path for both the Keycloak and Airflow changes, since the two systems are often owned by different teams. Missing any of these tends to extend the schedule because the open questions stall the build.
Is the Keycloak auth manager suitable for production given its alpha status?
That is a risk decision your team must make with current project information. The auth manager is an alpha component, so its behavior, configuration keys and compatibility may change between releases. Before relying on it in production, confirm the current status in the Airflow auth manager documentation, test your exact role model in staging, and decide how you will roll back to another auth manager if needed. Many organizations keep a tested fallback path and document it in their change records.
Does the multi-team setup change the scope of the work?
Yes. When several teams share one Airflow deployment, the work expands from configuring a single sign-in to designing team boundaries, verifying that each team's permissions hold, and confirming that API tokens issued for automation stay within the right scope. Testing scope grows with each team because every role combination needs a check. Ask how the partner plans to test cross-team access, since that is where permission gaps are most likely to appear.
What does a DeployOpen quote depend on?
A DeployOpen quote follows from a written scope agreed before work starts. That scope states the number of teams and environments, the role and group model to be implemented, the Keycloak state you start from, the testing expected, and any ongoing support you want afterward. Ongoing support, upgrades and continuous testing are available as retainers and are priced separately from the one-time build. DeployOpen does not publish a price list, so ask for a written scope and quote against it.
Who owns the system after the integration is finished?
Your organization keeps ownership of the Keycloak realm, the Airflow deployment and the role mappings. Someone on your team needs to manage group membership, review role changes, rotate or revoke API tokens and track Airflow and Keycloak upgrades. Clarify in the scope who will own each of these tasks after handover, and whether any upgrade or retesting support is needed later, since an alpha component may require adjustments as it changes.
How DeployOpen scopes, delivers and supports this integration
DeployOpen plans and implements the Keycloak auth manager for Airflow 3 inside infrastructure you control, starting from a written scope that names your roles, groups, clients and token needs. The work covers configuration, testing, documentation and handover, with ongoing support available as a retainer.
How we scope
- Written scope lists which Airflow roles, teams and permissions map to Keycloak groups and clients.
- Scope records the Airflow 3 and Keycloak versions you run, and the database each one uses.
- Scope states how the alpha status of the Keycloak auth manager is accepted, tested and monitored.
How we build
- Configure the Keycloak realm, clients and role mappings in a non-production environment first.
- Test sign-in, role-based access and API token generation against your agreed permission matrix.
- Run negative tests for users outside the mapped groups and for multi-team access boundaries.
How we hand over
- Deliver configuration as code with a runbook for realm changes, client rotation and role updates.
- Document the permission model, known caveats and the steps to confirm before each upgrade.
- Walk your identity and platform teams through the handover and record open risks in writing.
How we support
- Support retainers can cover Airflow and Keycloak upgrades, including checks on the auth manager after each release.
- Re-test role mappings whenever groups, clients or Airflow teams change in your organization.
- Ongoing testing can be scheduled as a retainer, with findings tracked against your agreed scope.
