Auth Managers

Auth managers are the Airflow extension point responsible for deciding who a user is and whether that user may perform an action in the UI or API. In practical terms, an auth manager sits between a request and the protected resource the request wants to access. The official provider documentation frames this as a provider-supplied capability: community providers can expose their own auth managers, and an Airflow deployment can configure one to handle authentication and authorization for UI and API actions. The source paths on this page show the shared model layer that those managers use and two provider-oriented integration signals.

Purpose and Scope

This page explains auth managers from the perspective of an Airflow developer or operator who needs to understand the contract, not merely the provider catalog. The contract begins with a user abstraction, continues through request-shaped authorization inputs, and ends with resource-detail objects that carry the identifiers needed for decisions. Those objects deliberately avoid tying authorization to one provider or one identity system. A provider can map them to Flask AppBuilder roles, AWS identity and policy services, Keycloak groups, or another backend while still speaking the same Airflow resource language.

The supplied core source is intentionally model-focused. It defines BaseUser, several typed dictionaries for batched authorization calls, dataclasses for resource details, and enums for view-level and DAG-level access targets. That makes the model layer a stable vocabulary shared by the API server, UI-facing checks, and provider implementations. The provider examples show how this vocabulary becomes operational: the FAB provider configures web session handling, while the Amazon provider documentation diagram places an AWS auth manager inside the Airflow environment and delegates identity and policy checks to AWS services.

Sources: airflow-core/src/airflow/api_fastapi/auth/managers/models/base_user.py, airflow-core/src/airflow/api_fastapi/auth/managers/models/batch_apis.py, airflow-core/src/airflow/api_fastapi/auth/managers/models/resource_details.py, providers/fab/src/airflow/providers/fab/www/extensions/init_session.py, providers/amazon/docs/img/diagram_auth_manager_architecture.py

Relevant Source Files

airflow-core/src/airflow/api_fastapi/auth/managers/models/__init__.py marks the auth-manager model package in core Airflow. It carries the standard ASF license header and anchors the package namespace used by the concrete model modules.
airflow-core/src/airflow/api_fastapi/auth/managers/models/base_user.py defines BaseUser, the minimal user interface expected by auth-manager code. Implementations provide get_id() and get_name() so Airflow can reason about an authenticated principal without depending on a concrete identity backend.
airflow-core/src/airflow/api_fastapi/auth/managers/models/batch_apis.py defines typed request payloads for batched authorization checks over connections, DAGs, pools, and variables. These types describe the method being attempted and the optional resource details needed to decide access.
airflow-core/src/airflow/api_fastapi/auth/managers/models/resource_details.py defines dataclasses and enums that name the resources and sub-resources Airflow authorization can target, including DAG runs, task logs, variables, pools, configuration sections, teams, assets, and UI views.
providers/fab/src/airflow/providers/fab/www/extensions/init_session.py shows provider-side web session setup for the FAB provider, including the supported securecookie and database session backends and the configuration error raised for unsupported values.
providers/amazon/docs/img/diagram_auth_manager_architecture.py generates the Amazon provider architecture diagram, showing the AWS auth manager between Airflow webservers and AWS IAM Identity Center plus Amazon Verified Permissions.

Core Model Contract

The smallest model in the contract is BaseUser. It is an interface with two abstract methods: get_id() returns a string identifier, and get_name() returns a display or principal name. Keeping the interface this small is important because identity providers vary widely. A FAB-backed deployment may represent users through application database records, while an AWS-backed deployment may derive identity from IAM Identity Center. Airflow authorization code can still ask the same two questions: what stable identifier represents this user, and what name should be associated with the action?

resource_details.py gives authorization checks context. Instead of passing raw strings everywhere, Airflow defines small dataclasses such as ConnectionDetails, DagDetails, PoolDetails, VariableDetails, TeamDetails, AssetDetails, and ConfigurationDetails. Many of these classes include a resource identifier and, where applicable, a team_name. That combination supports both object-level checks and team-scoped policies. For example, a connection decision can be made with a conn_id, a team name, or both, while a variable decision can be scoped by key and team_name.

The same file also defines enumerations for non-object access surfaces. AccessView lists named UI or platform views such as CLUSTER_ACTIVITY, IMPORT_ERRORS, JOBS, PLUGINS, PROVIDERS, TRIGGERS, and WEBSITE. DagAccessEntity narrows DAG authorization to particular DAG-adjacent capabilities: CODE, RUN, TASK, TASK_INSTANCE, TASK_LOGS, XCOM, AUDIT_LOG, DEPENDENCIES, HITL_DETAIL, VERSION, and WARNING. These enums help avoid ambiguous string checks and let an auth manager distinguish reading a DAG definition from reading task logs or manipulating DAG runs.

Sources: airflow-core/src/airflow/api_fastapi/auth/managers/models/base_user.py, airflow-core/src/airflow/api_fastapi/auth/managers/models/resource_details.py

Authorization Request Shapes

The batch API model file defines typed dictionaries for common authorization requests. Each dictionary mirrors an auth-manager method name: IsAuthorizedConnectionRequest represents is_authorized_connection, IsAuthorizedDagRequest represents is_authorized_dag, IsAuthorizedPoolRequest represents is_authorized_pool, and IsAuthorizedVariableRequest represents is_authorized_variable. All four are declared with total=False, so the shape can omit fields when a particular request does not need every piece of context. That is useful for list endpoints, aggregate checks, and UI screens that ask many questions at once.

Each request includes a method field typed as ResourceMethod, imported for type checking from the base auth manager module, and a details object appropriate to the resource. DAG requests can also include an access_entity, because DAG authorization is not a single yes-or-no resource check. A user might be allowed to read the DAG graph but not view TASK_LOGS, or allowed to inspect a run but not access XCOM. The model therefore separates the HTTP or resource method from the DAG sub-entity being protected.

This design encourages auth-manager implementations to be explicit about decision inputs. A provider does not need to parse route names or infer semantics from UI screens; it receives typed resource details and a named method. It also allows the API server to batch checks without changing the provider-facing vocabulary. When adding new protected surfaces, maintainers should prefer extending the shared detail and enum model rather than hiding resource identity inside provider-specific code paths.

Sources: airflow-core/src/airflow/api_fastapi/auth/managers/models/batch_apis.py, airflow-core/src/airflow/api_fastapi/auth/managers/models/resource_details.py

Provider Integration Patterns

Provider documentation lists community-managed auth manager implementations such as Amazon, FAB, and Keycloak. The source evidence illustrates two different kinds of provider work. The FAB provider file is not the auth decision engine itself; it configures the Flask session interface used by the web application. It reads [fab] SESSION_BACKEND through the shared compatibility configuration object, accepts securecookie and database, and raises AirflowConfigException when another value is configured. That kind of session plumbing is part of making an auth manager usable in the web UI.

The FAB session setup also shows an operational distinction that matters to deployers. With securecookie, the provider installs AirflowSecureCookieSessionInterface and can mark the built-in Flask session as permanent before each request when SESSION_PERMANENT is enabled. With database, it installs AirflowDatabaseSessionInterface with the session table, an empty key prefix, signer usage, and the configured permanence setting. These choices affect how browser sessions survive restarts and how much state is stored server-side, which is separate from the authorization decision for a particular DAG, pool, or variable.

The Amazon provider diagram source shows a more externalized architecture. It draws an Airflow user accessing the UI or REST API, then an Airflow webserver calling an AWS auth manager inside an Amazon provider cluster. From there, authentication goes to AWS IAM Identity Center, while authorization goes to Amazon Verified Permissions. Admin actors manage users and groups in Identity Center and permissions in Verified Permissions. This diagram makes the provider boundary clear: Airflow hosts the manager, but the manager can delegate identity and policy evaluation to external services.

Sources: providers/fab/src/airflow/providers/fab/www/extensions/init_session.py, providers/amazon/docs/img/diagram_auth_manager_architecture.py

Compact Reference

Contract item	Source-level name	What it represents
User identity	`BaseUser.get_id() -> str`	Stable authenticated-user identifier used by auth-manager logic.
User display name	`BaseUser.get_name() -> str`	Name associated with the authenticated principal.
Connection request	`IsAuthorizedConnectionRequest`	Authorization input for connection operations, including `method` and optional `ConnectionDetails`.
DAG request	`IsAuthorizedDagRequest`	Authorization input for DAG operations, including `method`, optional `DagAccessEntity`, and optional `DagDetails`.
Pool request	`IsAuthorizedPoolRequest`	Authorization input for pool operations, including `method` and optional `PoolDetails`.
Variable request	`IsAuthorizedVariableRequest`	Authorization input for variable operations, including `method` and optional `VariableDetails`.
UI views	`AccessView`	Named platform views such as providers, triggers, jobs, docs, plugins, and import errors.
DAG sub-resources	`DagAccessEntity`	DAG-specific access targets such as run, task, task instance, task logs, XCom, code, and audit log.
FAB session backend	`[fab] SESSION_BACKEND`	Provider configuration choosing `securecookie` or `database` session storage.
AWS architecture	`generate_auth_manager_diagram()`	Documentation generator for the AWS auth-manager architecture diagram.

Execution Flow

A typical protected request starts when a user accesses the Airflow UI or REST API. The configured web stack establishes a session or receives authentication material, then resolves an Airflow user object that satisfies the auth-manager user contract. When the request targets a protected object, Airflow constructs an authorization question using the shared method and resource-detail vocabulary. For a DAG logs screen, that question can include the DAG id and the TASK_LOGS DAG access entity. For a variable endpoint, it can include the variable key and team name.

The auth manager then evaluates the question using its backend. A FAB-oriented manager may evaluate roles, permissions, and web session state inside the Airflow application environment. An AWS-oriented manager can authenticate through IAM Identity Center and authorize through Amazon Verified Permissions, as shown by the generated architecture diagram. In both cases, the rest of Airflow should not need to know the backend-specific mechanics. It needs an authenticated principal, a resource method, and enough typed details to ask the right authorization question.

For maintainers, the main design rule is to keep resource semantics in the core model layer and backend mechanics in provider code. If a new UI view needs protection, model it as a named AccessView when it is a platform-level screen. If a new DAG-adjacent capability needs protection, model it as a DagAccessEntity. If a resource needs object-level checks, add or reuse a details dataclass that carries identifiers clearly. That keeps the public extension surface comprehensible for provider authors and auditable for operators reviewing security behavior.

Sources: airflow-core/src/airflow/api_fastapi/auth/managers/models/resource_details.py, providers/fab/src/airflow/providers/fab/www/extensions/init_session.py, providers/amazon/docs/img/diagram_auth_manager_architecture.py

Implementation Notes and Next Steps

When configuring or implementing an auth manager, separate three concerns: identity, session transport, and authorization policy. Identity answers who the caller is and maps naturally to BaseUser. Session transport determines how the UI remembers that caller across requests; the FAB provider source shows this as a configurable choice between secure-cookie and database-backed session interfaces. Authorization policy decides whether the caller may perform a method on a resource, using request shapes and resource details from core Airflow rather than provider-specific route parsing.

Next, read the provider-specific documentation for the auth manager you plan to operate, because the backend systems, required configuration, and user-management workflow differ. For AWS, expect an architecture that integrates with IAM Identity Center and Amazon Verified Permissions. For FAB, pay close attention to web session configuration and the security properties of the selected session backend. For extension authors, begin with the model contracts here, then implement backend-specific identity and policy translation while preserving Airflow’s named resources, methods, and DAG access entities.

Ask a question...