Apache Airflow login with GitHub teams

Apache Airflow login with GitHub teams: what the integration does

If your Airflow 3 team wants developers to sign in with their GitHub organization accounts and team memberships instead of local passwords, the integration is built through the FAB auth manager. FAB supports OAuth, and its github provider lets Airflow send users to GitHub for sign-in. Team membership does not come across automatically in a usable form, so you write a custom map_roles function that converts GitHub team IDs into Airflow roles, and you wire that function into a class that extends FabAirflowSecurityManagerOverride, assigned to SECURITY_MANAGER_CLASS. Those three parts, the provider, the role mapping and the security manager class, are what the integration consists of.

Airflow 3 allows only one auth manager at a time, selected with the auth_manager option. The default is the Simple auth manager, so you must change that setting to the FAB auth manager and install it from the FAB provider package before any GitHub configuration takes effect. Plan this as a deployment change, not a webserver setting, because the API server, which replaces the webserver in Airflow 3, reads the auth manager configuration. Confirm the provider version you will install against the Airflow 3.3.2 release and the FAB documentation before you start, since provider packages are versioned separately from Airflow itself.

Before you build this, decide who owns the GitHub OAuth application, who maps teams to roles and how you will recover if GitHub or the mapping fails. Keep at least one local break-glass administrator that does not depend on GitHub, and test that account before going live. Also note that AUTH_ROLE_PUBLIC set to a role effectively disables authentication, so review that setting carefully. The FAB webserver authentication documentation is the reference for the exact configuration keys in your provider version.

What you need before configuring GitHub sign-in

GitHub sign-in sits on top of a working Airflow 3 installation, so the platform baseline comes first. The cards below cover the Airflow version, the metadata database, the FAB provider, the GitHub side of the setup and the TLS requirement that protects the login flow.

Airflow 3.3.2 and supported Python

Start from a current Airflow 3 release. The 3.3.2 patch release is the current baseline in the version support table, and its prerequisites list Python 3.10 to 3.14. Confirm that your Python build, base image and dependency constraints match that range before you install the FAB provider, since a mismatch is the most common reason an install fails before any login configuration is tested. Do not start a new GitHub login project on Airflow 2, which reached end of life on April 22, 2026.

PostgreSQL or MySQL metadata database

Airflow stores users, roles and sessions in its metadata database, so the login setup depends on it. Use PostgreSQL or MySQL in any environment where users sign in. The production guide warns that SQLite can lose data, and MariaDB is not supported as the metadata database. Confirm the exact PostgreSQL or MySQL version your platform team supports against the prerequisites page before you provision it.

FAB provider version match

In Airflow 3, the FAB auth manager comes from the separate FAB provider package, and only one auth manager can be active at a time through the auth_manager option. Pin the FAB provider version to the release that matches your Airflow version by checking the provider documentation, not the latest package on PyPI. Record the pinned version in your constraints file so that upgrades do not silently change the OAuth behavior.

GitHub OAuth app and callback URL

Register an OAuth app in the GitHub organization that owns the teams you want to map. The authorization callback URL must point at your Airflow host, and it must match the host users reach in the browser exactly, including scheme and port. A mismatch produces a redirect error at sign-in, so decide the public hostname before you register the app. Store the client ID and secret in your secrets manager, not in webserver_config.py.

Organization and team structure

GitHub team mapping depends on teams that already reflect who should administer, operate or only view Airflow. Confirm that the organization exists, that the relevant teams are populated, and that the people who will sign in are members of an organization your security team controls. Ask who can create or rename teams, because a changed team name or membership can change Airflow access on the next login.

Numeric team ID lookup and TLS

The role mapping uses numeric GitHub team IDs rather than team names, so collect each team ID through the GitHub API before writing the mapping function. Serve the Airflow API server over TLS before enabling OAuth, because the login redirect and session cookies must not travel in plain text. Confirm which certificate authority and load balancer or ingress terminates TLS, and whether it forwards the original host header.

How to configure GitHub OAuth in webserver_config.py

This sequence takes a self-hosted Airflow 3 deployment from the default auth manager to GitHub sign-in through the FAB auth manager, with team-based role assignment and anonymous access turned off. Each step ends with a check that confirms the piece works before the next one starts.

Select the FAB auth manager
Confirm that the Airflow environment uses the Fab auth manager rather than the Simple auth manager that Airflow 3 applies by default. Airflow allows only one auth manager at a time, and it is set through the auth_manager option in the Airflow configuration. Install the FAB provider package in the same environment as Airflow, using the version pinned to your Airflow release, so the webserver_config.py settings load. The check is that the API server starts with the FAB auth manager selected and the login page no longer shows the Simple auth manager's default behavior. Record the provider version in your change ticket so the upgrade path stays traceable.
Create the GitHub OAuth app
Create an OAuth application in the GitHub organization that owns the teams you plan to map, and set the authorization callback URL to the Airflow address with the FAB OAuth path. The organization owner or an administrator with OAuth app permissions usually performs this step. Store the client ID and client secret in your secrets manager or environment variables, not in webserver_config.py or version control. The check is that the app appears in the organization's OAuth application list with the expected callback URL and that the secret is readable by the Airflow process only. Confirm the exact callback path against the FAB documentation for your provider version.
Add the GitHub provider entry
In webserver_config.py, add an entry to OAUTH_PROVIDERS with the name github and the OAuth settings for GitHub, reading the client ID and secret from environment variables. The configuration names and provider keys should be copied from the FAB webserver authentication page for your provider version, since they are the parts most likely to differ between releases. Do not hard-code the secret in the file. The check is that the configuration file loads without errors when the API server starts and that the login page shows a GitHub sign-in option. If the option is missing, the provider name or the environment variable names are the first things to recheck.
Assign a custom security manager class
Create a class that extends FabAirflowSecurityManagerOverride in webserver_config.py and assign it to SECURITY_MANAGER_CLASS. This class is where the GitHub login logic lives, including the function that converts team membership into Airflow roles in the next phase. Keep the class small at this stage so that a single change can be traced during testing. The check is that the API server starts with the custom class loaded and that a GitHub sign-in reaches the Airflow user interface without a configuration error. Record which class name is in use so that later role mapping changes are reviewed against the correct file.
Map GitHub team IDs to Airflow roles
Inside the security manager class, implement the map_roles logic described in the FAB GitHub example so that each GitHub team ID returned for the signed-in user maps to an Airflow role such as Admin, Op, User or Viewer. Decide which team gets the most privileged role and document the mapping as a table in your repository. Use team IDs rather than team names, because names can change while IDs stay fixed, and confirm each ID against the organization's API output. The check is that a test user in each mapped team signs in and sees the role expected for that team, and that a user in no mapped team receives no elevated role.
Set AUTH_ROLE_PUBLIC to none
Set AUTH_ROLE_PUBLIC in webserver_config.py to None so that unauthenticated visitors do not receive a public role. The FAB documentation notes that assigning a role to this setting effectively deactivates authentication, so leave it unset or set to None for any deployment that should require sign-in. Confirm that the setting is applied in the file that the API server reads, not in a copy. The check is that a browser session without login is redirected to the sign-in page for every protected path, including the API paths you use for automation. Test with a private browser window and an unauthenticated API call.
Test each team and a user outside the teams
Run a login test with one test account per mapped GitHub team, plus one account that belongs to none of them. Each team account should reach the roles assigned in the previous step, and the account outside the teams should be denied elevated access or refused entry, depending on how the class is written. Record the results in your test notes and repeat the test after any change to the mapping or the provider settings. Include the sign-out and session expiry behavior in the test, because role changes in GitHub may only apply after the next sign-in. Treat any unexpected role as a defect to fix before you move the configuration to a shared environment.

How team IDs become Airflow roles in map_roles

When a user signs in to Airflow through the GitHub OAuth provider in FAB, GitHub returns the user's identity and, when the OAuth app requests the right scope, the teams that user belongs to. Airflow does not decide on its own which teams matter. The FAB documentation's GitHub example supplies a custom map_roles function inside a class that extends FabAirflowSecurityManagerOverride, and that function receives the team data and returns the Airflow roles for the session. The mapping logic is therefore code you own and review, and it runs on every login, so a change to team membership takes effect the next time the user signs in.

The example keys its mapping on GitHub team IDs rather than team names or slugs, and the reason is stability. A team's display name is editable by organization owners, and a renamed team can silently stop matching a rule written against its old name, or worse, a new team created under a reused name can start matching it. Numeric IDs survive renames. Confirm the ID format and the exact response fields against the GitHub API version your deployment calls before you write rules, since the field you map on must be the one GitHub actually returns.

Hard-coding IDs in map_roles is simple to review and keeps the policy in one file under version control, but every new team or change of ownership becomes a code change and a redeployment. Reading the IDs from configuration, such as an environment variable or a file mounted from a secret, lets operators adjust access without a release, at the cost of a second source of truth that someone must audit. Whichever you choose, map each team to one of the standard roles (Admin, Op, User or Viewer), define a fallback for users in no mapped team, and keep at least one break-glass account outside GitHub. Test the mapping with a team member from each tier before go-live.

Mapping GitHub organization, teams and Airflow roles

This table lists each decision the mapping needs, what it controls and who should own it. Read it as a checklist: every GitHub organization, team and fallback rule should have a named owner and a recorded Airflow role before the login goes live.

Mapping element	What to record	Owner who approves changes	Where it usually fails
GitHub organization	Exact organization login allowed to sign in, and the org ID confirmed from the GitHub API for that organization	Identity or platform lead	Mapping written against a similarly named or renamed organization
Team ID to Airflow role	One row per team ID mapped to Admin, Op, User, Viewer or a custom role, with the team slug kept as a note	Airflow platform owner with the business owner of the team	Team renamed in GitHub, so the numeric ID is kept but nobody updates the notes
Permissions granted	The DAG, connection, variable and audit permissions each role gives, written out for reviewers	Security or compliance reviewer	Custom role inherits more access than the team expects
Roles per user	Whether a user can hold several roles from several teams, and which role wins when they conflict	Airflow platform owner	Overlapping team membership silently grants the highest role
Fallback for users with no mapped team	Default role, or deny access, chosen deliberately and documented	Security owner	Default role left at a permissive value from a test setup
Break-glass admin	A named local account or documented recovery path that does not depend on GitHub membership	Security owner	Only admin was a GitHub team, so a lockout blocks recovery
Review trigger	Team renames, team restructures, org changes and staff moves recorded as events that reopen the mapping	Identity or platform lead	Mapping reviewed once at launch and never again
Change record	Who requested each change, the GitHub API evidence for the new ID and the approval date	Change management owner	Changes made directly in the webserver config with no ticket

Restricting sign-in to your GitHub organization

Any GitHub account that completes the OAuth flow can reach the login step, so organization membership has to be enforced in more than one place. The cards below cover what the custom security manager should check, how unmapped users are handled, and which GitHub organization settings reduce exposure before Airflow sees a request.

Check organization membership at login

GitHub OAuth proves who the user is, not that they belong to your organization. Your custom security manager, the class you assign to SECURITY_MANAGER_CLASS, should call GitHub for the user's organization and team memberships during the login callback and refuse the session when the user is outside your organization. Confirm the exact API calls and the scopes they need against the current FAB and GitHub documentation, because membership reads depend on the token permissions you grant.

Reject users without a mapped team

Membership in the organization is not the same as permission to use Airflow. Decide which GitHub team IDs grant access, and deny login when none of a user's teams appears in your role map. Without this step, a new employee in an unrelated team of the organization could sign in with a default role. Test the rejection path with an account that is an organization member but holds no mapped team, and confirm that the user sees a denial rather than a session with reduced rights.

Disable self-registration of unmapped users

FAB can create a user record on first login. For GitHub sign-in, turn off automatic registration for users who do not match a mapped team, so that no local account is created for them. Review the user table after the first login tests to confirm that only mapped users exist. Confirm the registration settings and their names in the FAB documentation for your provider version, since these behaviors have changed across releases.

Restrict OAuth app access in GitHub

GitHub organization owners can control which OAuth apps members and outside collaborators may use, and whether third-party access to organization data needs approval. Register the Airflow OAuth app under the organization rather than a personal account, and review the app's access requests in the organization settings. Confirm the current options and where they appear in the GitHub documentation for your plan, because the organization settings are the outer layer that applies even if the Airflow code has a gap.

Keep the client secret out of the config file

The OAuth client secret lets anyone who holds it impersonate the Airflow application during the flow. Store it in a secrets backend or an environment variable injected at deploy time instead of a plain value in webserver_config.py, and limit who can read the deployment manifests. Rotate the secret on a schedule you document, and confirm the rotation steps in GitHub before you rely on them during an incident.

Review membership changes and session lifetime

Removing someone from a GitHub team does not end an Airflow session that is already open. Set a session lifetime that matches your access review cycle, and check membership again on each login rather than only at account creation. Ask the team to test a removal end to end, from GitHub to a refused login in Airflow, and record the result as evidence. Confirm how role and session refresh behave in your FAB version before you commit to a lifetime.

When GitHub login is the right choice and when a central identity provider is better

GitHub login fits a team where most people who operate Airflow already have GitHub accounts, source code and pipeline definitions live in GitHub, and the team manages its own membership directly. In that setting, the people who can open the Airflow UI are the people who already belong to the right GitHub organization and teams, and the team can see that relationship clearly without a separate directory project. The FAB auth manager supports GitHub OAuth through webserver_config.py, so the setup stays inside the Airflow configuration the team already maintains.

Low setup surface: One OAuth application and a small mapping function are usually enough to start.
Access follows code ownership: Team membership in GitHub often mirrors who maintains the DAG repository.
Fewer moving parts: No additional identity service needs to be installed, patched or backed up.
Clear limits: Access reflects GitHub membership, so removing someone from a team is the main offboarding control.
Sizing signal: The approach suits a bounded user group that the team can review directly.

Before committing, confirm that every person who needs Airflow access already has a managed GitHub account and that your GitHub organization enforces two-factor authentication for members.

Security settings for GitHub OAuth in Airflow

GitHub sign-in turns Airflow's login into a trust relationship with an external platform, so the controls around it matter as much as the role mapping. The cards below cover where the client secret lives, how callbacks and tokens are protected, what access the login path grants by default, and how to keep an administrator able to sign in if GitHub or the mapping fails.

Keep the client secret out of plain text

The GitHub OAuth client secret lets anyone holding it impersonate your application, so it should not sit in webserver_config.py as a literal value committed to a repository or image. Load it from an environment variable injected by your secrets backend or Kubernetes secret, and confirm that it does not appear in rendered configuration, container inspect output or logs. Plan a rotation procedure that updates the GitHub app and the Airflow secret in the same change window.

Allow only HTTPS callback URLs

The authorization callback must point to an HTTPS address on the Airflow host, and the URL registered in the GitHub OAuth app must match the one Airflow sends exactly, including scheme, host and path. Check that the external load balancer or ingress terminates TLS and that plain HTTP requests are redirected rather than served. A mismatched or HTTP callback is a common cause of sign-in failures that teams work around by weakening the setting, so resolve it in configuration instead.

Request the narrowest OAuth scopes

The GitHub provider needs only enough access to read the user's identity and organization team membership used for role mapping. Review each scope the FAB provider requests, remove any the mapping does not use, and document why the remaining ones are needed. Ask your security team to review the GitHub app's permissions at registration and again after each Airflow provider upgrade, since requested scopes can change between releases.

Set session and token lifetimes

Airflow 3 issues its own session and API tokens after GitHub authenticates the user, so the lifetime of those tokens determines how long a revoked GitHub user keeps access. Set the session timeout in configuration to match your policy, and confirm that removing someone from the GitHub team ends access at the next role sync, not only at the next manual cleanup. Test this with a non-admin account before relying on it.

Disable public access and the default user

Setting AUTH_ROLE_PUBLIC to a role effectively deactivates authentication, so anonymous visitors would receive that role's access without signing in. Confirm the setting is absent or empty in every environment. After cutover, remove the default user created by the Simple auth manager and verify that its credentials no longer work, because a leftover account with a known password bypasses GitHub entirely.

Store the break-glass admin outside GitHub

Keep one local administrator account, with a strong password and multi-factor controls held in your password vault or sealed secrets store rather than in GitHub. Use it only when GitHub is unavailable or the team mapping is broken, and test that it can sign in before cutover. Log each use, review the event, and rotate the credential afterward. Document who may retrieve it and how that access is approved.

Why GitHub login fails in Airflow and how to fix it

This table lists the failures teams most often hit when wiring GitHub sign-in to Airflow, with the cause and fix for each. Read it in order during setup, or use it as a checklist when a login breaks after a change to the GitHub organization, the proxy or the Airflow configuration.

Failure	Likely cause	Fix
Callback URL mismatch	The authorization callback URL registered in the GitHub OAuth app does not match the URL Airflow sends, often because of a different host, port or path.	Set the callback URL in the GitHub OAuth app to the exact address Airflow serves for the FAB OAuth callback, then test with the same hostname users type in the browser.
User logs in with no role	The map_roles function returns an empty list for that user, so FAB grants no Airflow role.	Add a fallback role for users with no matching team, or confirm the user's team IDs are in the mapping. Check the role list returned for a test account before rollout.
Team IDs changed after reorganization	Mappings use numeric GitHub team IDs. Renaming, moving or recreating a team creates a new ID, so old mappings match nothing.	Look up current team IDs through the GitHub API for the organization and update the mapping. Record the ID next to the team name so future changes are visible in review.
User not in the organization	The GitHub account is not a member of the organization that owns the teams, so no team membership appears in the lookup.	Invite the user to the organization and confirm team membership. If the lookup is restricted to the organization, users outside it cannot sign in by design.
FAB provider not selected	Airflow 3 allows only one auth manager at a time, set by the auth_manager option. The default Simple auth manager is still active, so the GitHub OAuth settings are ignored.	Set auth_manager to the FAB auth manager in the Airflow configuration, install the FAB provider, and restart the API server and other components.
Login loop behind a reverse proxy	The proxy terminates TLS but Airflow sees http, so generated redirect URLs use the wrong scheme and the browser keeps bouncing between sign-in and callback.	Forward the original scheme and host headers from the proxy and configure Airflow to trust them. Confirm the callback URL in GitHub uses https and the public hostname.

Questions buyers ask about GitHub login for Airflow

How much effort does a GitHub login setup for Airflow take?

Effort depends mostly on how many teams you map, how much custom authorization logic you need, and how many roles you must test. A setup that maps a handful of GitHub teams to the standard Airflow roles is small. A setup that maps many teams, restricts access by organization, handles users who belong to several teams, and needs per-DAG rules takes considerably more design and testing. The GitHub OAuth app, the callback configuration, the role mapping function and the TLS setup are each a discrete piece of work. Ask any partner to break the quote into those pieces so you can see which ones your team could take on.

Can our internal team set up GitHub login for Airflow alone?

A team with working Python skills and some Airflow administration experience can often build the basic setup, but the work touches the FAB auth manager, its webserver configuration file and a custom security manager class. Engineers need to understand how the FAB provider handles OAuth callbacks, how role mapping runs at login, and how a misconfiguration can disable authentication. Someone on the team should also be comfortable reviewing the code paths that grant Admin rights. If that knowledge is thin, a fixed-scope engagement can cover the build while your team learns to run and change it.

How long does a test cycle take when staging is limited?

Test cycles are governed by how quickly you can get a staging Airflow instance with its own GitHub OAuth app and a test organization or test teams. If a staging environment, DNS name, TLS certificate and test accounts are ready, testing each role takes far less time than when those prerequisites must be requested first. Testing should cover each mapped team, users in no mapped team, users in several teams, removed members and the organization restriction. Ask the partner to state which environment and accounts they need before the test window opens, because that dependency usually sets the schedule.

What do we need to provide for a GitHub login engagement?

The work needs several inputs from your side before it starts:

GitHub organization owner or admin access to create or approve an OAuth app and to read team IDs
A list of the GitHub teams that should map to each Airflow role, with their numeric team IDs
A TLS certificate and a stable public hostname for the Airflow web address
An approved role model that states what Admin, Op, User, Viewer and Public may do
A staging environment that matches production closely enough to test the callback and role logic

Confirm the exact access level your security team requires for the OAuth app before the kickoff, since it determines who must approve the setup.

Can we move from GitHub login to a central identity provider later?

Yes, but the change is a real configuration and access review, not a switch. GitHub login is an OAuth provider inside FAB, so moving to a central identity provider such as Keycloak, Okta or Entra ID means registering a new OAuth client, changing the provider and role mapping, and testing every role again. Existing users keep their Airflow accounts, but their roles will come from the new provider's groups or claims, so you must map those groups before cutover. Plan the break-glass admin account so it survives the change. Confirm with the partner which parts of the mapping code can be reused.

What does a fixed-scope quote for GitHub login cover?

A fixed-scope quote follows from a written scope agreed before work starts. It should list the Airflow version and FAB provider version in scope, the number of GitHub organizations and teams to map, the role model, the organization restriction, the TLS and hostname work, the staging and production deployment steps, the test cases for each role, and the handover documentation. It should also state what is excluded, such as changes to GitHub organization structure, other identity providers or DAG-level permissions. DeployOpen does not publish a price list, so ask for a quote tied to that written scope and compare line items across bidders.

Is GitHub login secure enough for production Airflow?

GitHub login can be a reasonable choice for a small, GitHub-centered team, but its security depends on the configuration you choose. The main risks are misconfigured role mapping that grants Admin too broadly, missing organization restrictions that let accounts outside your company sign in, and a shared admin path that bypasses SSO. Your security team should review the OAuth app scope, the callback hostname, the TLS setup and the audit trail for role changes. Confirm each item against the current FAB documentation and your own policy before you approve production use.

Keeping role mappings current after teams change

GitHub team membership is read at sign-in, so a role mapping only stays accurate if two things happen: the person is removed from the GitHub team, and their Airflow session ends. Removing someone from a team in GitHub does not revoke an Airflow session that is already open. Until the session expires or is invalidated, the user keeps the roles they had at last login. Confirm the session lifetime your Airflow deployment uses for the FAB webserver and API server, and decide whether that window is acceptable for privileged roles such as Admin. For offboarding, treat GitHub removal as the first step and session termination as the second, and document both in the same runbook.

Set a review cadence for the team-to-role mapping itself, separate from individual access reviews. At each review, compare the team IDs referenced in map_roles against the current GitHub organization structure, confirm that every team still exists under the same ID, and confirm that each team's Airflow role matches the access your DAG owners have approved. Teams are renamed, split and deleted, and a recycled or reassigned team can silently grant a role it was never meant to carry. Ask your GitHub administrators to notify the Airflow owners before organization-level team changes, and record the review outcome as a dated entry.

Keep map_roles and the webserver_config.py settings that call it under version control, and change them through the same review path as DAG code. Each change should name the team ID, the role granted, the approver and the reason. This is the evidence an auditor will ask for when they test whether role changes were authorized. Log role assignments at login, including the username, GitHub team IDs received, roles granted and time, and send those logs to your central log store with retention that matches your access policy. Confirm with the FAB provider documentation which log events the webserver emits by default, and add any missing events before relying on them as audit evidence.

How DeployOpen scopes and delivers GitHub login for Airflow

DeployOpen plans, builds and hands over GitHub sign-in for a self-hosted Apache Airflow inside your own infrastructure. Each engagement starts with a written scope that settles the GitHub organization, team-to-role mapping and the fallback admin path before any configuration changes are made.

How we scope

Confirm which GitHub organization and teams will map to Airflow roles, and who approves changes to that mapping.
Agree in writing whether sign-in is restricted to one organization and how external collaborators are handled.
Decide with you whether GitHub is the right identity source or whether a central identity provider should front Airflow instead.

How we build

Configure the FAB auth manager with the GitHub OAuth provider and a custom role mapping keyed on team IDs.
Set up the OAuth application, callback URLs and secrets so they are stored outside the repository.
Test sign-in, role assignment, denied access and API access for automation before the build is accepted.

How we hand over

Deliver the webserver configuration, role mapping table and a runbook for adding or removing teams.
Document the break-glass admin procedure and verify it works before handover.
Walk your administrators through the configuration and record the decisions made during scoping.

How we support

Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
Ongoing support, upgrades and continuous testing are available as a retainer.
Ask for a quote based on the written scope, covering one-time build work and any recurring support you want.