This is an automated email from the ASF dual-hosted git repository.
vincbeck pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 7a2f65cba4c Add caveat details in auth manager doc (#53397)
7a2f65cba4c is described below
commit 7a2f65cba4c903d43e7ac094021ea9ddc20ab876
Author: Zach <[email protected]>
AuthorDate: Tue Jul 22 09:39:31 2025 -0400
Add caveat details in auth manager doc (#53397)
* Add caveat details in auth manager doc
* fix relative link to erd schema
* Add section on DAG and DAGAccessEntity authz
* Update airflow-core/docs/core-concepts/auth-manager/index.rst
Co-authored-by: Vincent <[email protected]>
* Remove MENU ref + clarify get_authorized_dag_ids vs
filter_authorized_dag_ids
* address nit
* Spellcheck fix + list rendering fixes
---------
Co-authored-by: Vincent <[email protected]>
---
.../docs/core-concepts/auth-manager/index.rst | 42 ++++++++++++++++++----
1 file changed, 36 insertions(+), 6 deletions(-)
diff --git a/airflow-core/docs/core-concepts/auth-manager/index.rst
b/airflow-core/docs/core-concepts/auth-manager/index.rst
index b0c99abf4bf..b729fc5a848 100644
--- a/airflow-core/docs/core-concepts/auth-manager/index.rst
+++ b/airflow-core/docs/core-concepts/auth-manager/index.rst
@@ -63,7 +63,7 @@ users does not need the same user management as an
environment used by thousand
This is why the whole user management (user authentication and user
authorization) is packaged in one component
called auth manager. So that it is easy to plug-and-play an auth manager that
suits your specific needs.
-By default, Airflow comes with the
:doc:`apache-airflow-providers-fab:auth-manager/index`.
+By default, Airflow comes with the :doc:`simple/index`.
.. note::
Switching to a different auth manager is a heavy operation and should be
considered as such. It will
@@ -123,11 +123,11 @@ Let's go over the different parameters used by most of
these methods.
* ``POST``: Can the user create a resource?
* ``PUT``: Can the user modify the resource?
* ``DELETE``: Can the user delete the resource?
- * ``MENU``: Can the user see the resource in the menu?
* ``details``: Optional details about the resource being accessed.
* ``user``: The user trying to access the resource.
+
These authorization methods are:
* ``is_authorized_configuration``: Return whether the user is authorized to
access Airflow configuration. Some details about the configuration can be
provided (e.g. the config section).
@@ -145,6 +145,9 @@ These authorization methods are:
* ``is_authorized_custom_view``: Return whether the user is authorized to
access a specific view not defined in Airflow. This view can be provided by the
auth manager itself or a plugin defined by the user.
* ``filter_authorized_menu_items``: Given the list of menu items in the UI,
return the list of menu items the user has access to.
+It should be noted that the ``method`` parameter listed above may only have
relevance for a specific subset of the auth manager's authorization methods.
+For example, the ``configuration`` resource is by definition read-only, so
only the ``GET`` parameter is relevant in the context of
``is_authorized_configuration``.
+
JWT token management by auth managers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The auth manager is responsible for creating the JWT token needed to interact
with Airflow public API.
@@ -152,10 +155,9 @@ To achieve this, the auth manager **must** provide an
endpoint to create this JW
available at ``POST /auth/token``.
Please double check the auth manager documentation to find the accurate token
generation endpoint.
-The auth manager is also responsible of passing the JWT token to Airflow UI.
The protocol to exchange the JWT
+The auth manager is also responsible for passing the JWT token to the Airflow
UI. The protocol to exchange the JWT
token between the auth manager and Airflow UI is using cookies. The auth
manager needs to save the JWT token in a
-cookie named ``_token`` before redirecting to the Airflow UI. The Airflow UI
will then read the cookie, save it and
-delete the cookie.
+cookie named ``_token`` before redirecting to the Airflow UI. The Airflow UI
will then read the cookie, save it, and delete it.
.. code-block:: python
@@ -163,7 +165,7 @@ delete the cookie.
response = RedirectResponse(url="/")
- secure = bool(conf.get("api", "ssl_cert", fallback=""))
+ secure = request.base_url.scheme == "https" or bool(conf.get("api",
"ssl_cert", fallback=""))
response.set_cookie(COOKIE_NAME_JWT_TOKEN, token, secure=secure)
return response
@@ -179,6 +181,9 @@ The following methods aren't required to override to have a
functional Airflow a
* ``batch_is_authorized_dag``: Batch version of ``is_authorized_dag``. If not
overridden, it will call ``is_authorized_dag`` for every single item.
* ``get_authorized_dag_ids``: Return the list of DAG IDs the user has access
to. If not overridden, it will call ``is_authorized_dag`` for every single DAG
available in the environment.
+ * Note: To filter the results of ``get_authorized_dag_ids``, it is
recommended that you define the filtering logic in your
``filter_authorized_dag_ids`` method. For example, this may be useful if you
rely on per-DAG access controls derived from one or more fields on a given DAG
(e.g. DAG tags).
+ * This method requires an active session with the Airflow metadata database.
As such, overriding the ``get_authorized_dag_ids`` method is an advanced use
case, which should be considered carefully -- it is recommended you refer to
the :doc:`../../database-erd-ref`.
+
CLI
^^^
@@ -229,6 +234,31 @@ Other optional methods
their class paths need to be returned as part of this method. By doing so,
they will be automatically added to the
config ``[database] external_db_managers``.
+
+Additional Caveats
+^^^^^^^^^^^^^^^^^^
+
+* Your auth manager should not reference anything from the
``airflow.security.permissions`` module, as that module is in the process of
being deprecated.
+ Instead, your code should use the definitions in
``airflow.api_fastapi.auth.managers.models.resource_details``.
+* The ``access_control`` attribute of a DAG instance is only compatible with
the FAB auth manager. Custom auth manager implementations should leverage
``get_authorized_dag_ids`` for DAG instance attribute-based access controls in
more customizable ways (e.g. authorization based on DAG tags, DAG bundles,
etc.).
+* You may find it useful to define a private, generalized ``_is_authorized``
method which acts as the standardized authorization mechanism, and which each
+ public ``is_authorized_*`` method calls with the appropriate parameters.
+ For concrete examples of this, refer to the
``SimpleAuthManager._is_authorized_method``. Further, it may be useful to
optionally use the
``airflow.api_fastapi.auth.managers.base_auth_manager.ExtendedResourceMethod``
reference within your private method.
+
+DAG and DAG Sub-Component Authorization
+---------------------------------------
+
+Given the hierarchical structure of DAGs and their composite resources, the
auth manager's ``is_authorized_dag`` method should also handle the
authorization logic for DAG runs, tasks, and task instances.
+The ``access_entity`` parameter passed to ``is_authorized_dag`` indicates
which (if any) DAG sub-component the user is attempting to access. This leads
to a few important points:
+
+* If the ``access_entity`` parameter is ``None``, then the user is attempting
to interact directly with the DAG, not any of its sub-components.
+* When the ``access_entity`` parameter is not ``None``, it means the user is
attempting to access some sub-component of the DAG. This is noteworthy, as in
some cases the ``method`` parameter may be valid
+ for the DAG's sub-entity, but not a valid action directly on the DAG itself.
For example, the ``POST`` method is valid for DAG runs, but **not** for DAGs.
+* One potential way to model the example request mentioned above -- where the
``method`` only has meaning for the DAG sub-component -- is to authorize the
user if **both** statements are true:
+
+ * The user has ``PUT`` ("edit") permissions for the given DAG.
+ * The user has ``POST`` ("create") permissions for DAG runs.
+
Next Steps
----------
