Core Extension Contracts
Purpose and Scope
Airflow providers are not only packages of operators and hooks. They can also extend core Airflow behavior through named contracts that the core runtime, API server, web UI, and provider packages agree to use. In the provider documentation these contracts are grouped under Core Extensions, including auth managers, connections, executors, extra links, writing logs, message queues, notifications, and secret backends. This page explains the extension model from the source evidence available here, then shows how to read the auth-manager contract as the clearest concrete example of the pattern. 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
A core extension contract is a boundary: Airflow core defines the shape of data and the call sites, while providers contribute implementations that are selected by configuration, packaging metadata, or provider-specific integration code. This lets the project keep scheduler and API semantics stable while allowing integrations to adapt authentication systems, connection forms, external log links, notification targets, secret stores, executor backends, and message-queue integrations. The most important design point is that a provider extension must speak in Airflow terms first, such as users, DAGs, task logs, connections, variables, pools, and resource methods, before it translates those terms to an external service.
Relevant Source Files
- airflow-core/src/airflow/api_fastapi/auth/managers/models/init.py — Marks the auth-manager models package and establishes it as part of the core API auth model namespace.
- airflow-core/src/airflow/api_fastapi/auth/managers/models/base_user.py — Defines the minimal user interface that auth managers expose to Airflow: a user id and a display/name value.
- airflow-core/src/airflow/api_fastapi/auth/managers/models/batch_apis.py — Defines typed request dictionaries for batch authorization checks over connections, DAGs, pools, and variables.
- airflow-core/src/airflow/api_fastapi/auth/managers/models/resource_details.py — Defines dataclass payloads and enums that describe protected Airflow resources and DAG sub-resources.
- providers/fab/src/airflow/providers/fab/www/extensions/init_session.py — Shows a provider-side web extension choosing and installing a Flask session interface from Airflow configuration.
- providers/amazon/docs/img/diagram_auth_manager_architecture.py — Documents the Amazon auth-manager architecture as a provider implementation that delegates authentication and authorization to AWS services.
Extension Model
The common provider extension model has three participants. Airflow core owns the vocabulary and lifecycle, provider packages implement one or more extension points, and operators or administrators activate those implementations by installing providers and configuring Airflow. For connections, the provider-facing contract lets a provider define connection types, custom parameters, UI behavior, and hook lookup behavior. For extra links, the provider contributes buttons that appear from task pages and send users to external systems. For secret backends, logging, notification, executor, and message-queue extensions, the same idea applies: Airflow invokes a known category of behavior, while the provider supplies environment-specific implementation details.
The auth-manager model files show why these contracts are intentionally small and explicit. Airflow does not require every identity provider to expose the same internal user object; it asks for a BaseUser with get_id() and get_name(). Airflow does not ask a provider to parse arbitrary API route names; it passes typed details such as connection id, DAG id, pool name, variable key, team name, and selected DAG access entity. Those data shapes make authorization decisions portable across FAB, Amazon, Keycloak, or another provider implementation without hard-coding any one identity system into the API server. 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
Auth Manager Contract
The minimal user contract is intentionally narrow. BaseUser is documented as a user model interface and requires implementations to return a stable string identifier and a string name. That is enough for Airflow surfaces that need to know who is acting, log or display that actor, and pass the actor into the selected auth manager. Provider implementations can carry richer identity-provider state internally, but the core-facing object is deliberately reduced to the fields Airflow needs at the boundary. This is a good pattern to follow when designing provider extensions: keep the public Airflow contract stable and put vendor-specific complexity behind it. Sources: airflow-core/src/airflow/api_fastapi/auth/managers/models/base_user.py
Authorization requests are similarly shaped around Airflow resources rather than provider internals. IsAuthorizedConnectionRequest, IsAuthorizedDagRequest, IsAuthorizedPoolRequest, and IsAuthorizedVariableRequest are TypedDict request types. Each request carries a method and an optional details object, while the DAG request can also carry an access_entity. The use of total=False means callers and implementations can handle partial requests, which is useful when the API needs to ask broad permission questions as well as resource-specific ones. The provider contract therefore supports both coarse checks, such as whether a user may list a resource type, and narrow checks, such as access to a named DAG task log. 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
resource_details.py is the compact reference for the protected-resource vocabulary. Configuration checks can include a section. Connection checks can include conn_id and team_name. DAG, pool, and variable checks include their identifiers plus optional team names. Asset and asset-alias checks identify data-aware scheduling resources. The AccessView enum names broader UI views such as cluster activity, docs, import errors, jobs, plugins, providers, triggers, and website. The DagAccessEntity enum names sub-resources such as audit log, code, dependencies, human-in-the-loop detail, run, task, task instance, task logs, version, warning, and XCom. Sources: airflow-core/src/airflow/api_fastapi/auth/managers/models/resource_details.py
Provider Runtime Examples
The FAB provider snippet illustrates that extension contracts often meet configuration at runtime. init_airflow_session_interface(app, db) reads [fab] SESSION_BACKEND, chooses either a secure-cookie session interface or a database-backed session interface, and installs the selected interface on the Flask application. It also handles Airflow-specific cookie permanence and raises an AirflowConfigException when the configured backend is neither database nor securecookie. This is not the whole auth-manager system, but it is a practical example of provider web code adapting core UI behavior through a controlled extension point instead of requiring application code to know provider internals. Sources: providers/fab/src/airflow/providers/fab/www/extensions/init_session.py
The Amazon provider diagram source shows the other side of the extension boundary: a provider auth manager can delegate identity and policy decisions to external services. The generated diagram places Airflow users and admins around an Airflow environment with webservers and an AWS auth manager, then connects the auth manager to AWS IAM Identity Center for authentication and Amazon Verified Permissions for authorization. That source is documentation code, but it captures an important contract constraint: Airflow asks the provider whether an action is allowed, while the provider may implement that answer through external identity, group, and policy systems. Sources: providers/amazon/docs/img/diagram_auth_manager_architecture.py
Contract Reference
| Extension area | Core contract idea | Provider responsibility |
|---|---|---|
| Auth managers | User identity, resource details, resource methods, and authorization request shapes | Authenticate users and authorize API/UI actions against Airflow resources |
| Connections | Connection type, custom fields, UI behavior, and hook resolution | Define integration-specific connection metadata and hook creation behavior |
| Executors | Runtime execution backend selected by Airflow configuration | Run tasks using the provider's execution system while preserving Airflow task semantics |
| Extra links | Task-page links associated with operators | Render links to external systems such as logs, jobs, clusters, or query results |
| Writing logs | Log handler behavior selected by logging configuration | Store, fetch, or render task logs through provider-specific backends |
| Notifications | Notification target contract | Send Airflow events or callbacks to provider-specific messaging systems |
| Secret backends | Secret lookup interface | Resolve variables, connections, and configuration secrets from an external store |
| Message queues | Messaging integration boundary | Provide queue or broker integrations used by Airflow runtime features |
When implementing or reviewing any provider core extension, start by identifying which Airflow nouns cross the boundary. Auth managers receive ConnectionDetails, DagDetails, PoolDetails, VariableDetails, and DAG access entities rather than raw HTTP route names. Connection extensions should describe Airflow connection types and hook behavior rather than only cloud credentials. Extra links should be attached to operators and task pages rather than arbitrary UI locations. This keeps extensions discoverable in provider docs and makes them testable from Airflow behavior, not just from the external system's behavior.
Next Steps
If you are choosing an existing extension, install the relevant provider and read its provider documentation entry for the extension category. If you are building one, model the public boundary first: define the Airflow resource names, request shapes, configuration keys, and UI behavior before adding vendor-specific code. For auth-manager work, use BaseUser, the batch authorization request dictionaries, and resource_details.py as the primary vocabulary to keep API and UI decisions consistent. For broader provider work, continue with the pages on Providers Overview and Installation, Custom Providers, Operators and Hooks Reference, Connections, Security Model, and API Authentication and JWT.